From 58b40007fa31be489e7173674cfc2bfbe53c981a Mon Sep 17 00:00:00 2001
From: Asim Atasert <asimatasert@outlook.com>
Date: Mon, 6 Jul 2026 16:27:43 +0300
Subject: [PATCH 1/2] feat: add 'doctor' and 'explain' commands
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two terminal-native features distilled from the (abandoned) web-console
exploration — the genuinely useful parts, with no server/attack surface.

- 'doctor': local, read-only health checks with ✓/!/✗ output and a non-zero
  exit on problems — required/optional toolchain, output dir + free disk,
  per-database backup freshness (age of the newest dump), newest-archive
  readability, and the jobs file. With --from/--to it also tests connectivity.
  Good as a cron pre-flight or CI gate.
- 'explain [topic]': built-in, offline reference for what each command is for
  and when to use it (dump/restore/clone/stream/upgrade/fetch/batch/bot/
  list/meta/clean/doctor + masking/retention), with key options and examples.

Wired into dispatch, help, README, and bash/zsh/fish completions (also adds the
previously-missing 'bot' completion). New modules src/71-explain.sh and
src/73-doctor.sh; regenerated the bundled t-pgsql (build --check passes).
---
 README.md                |  23 ++
 completions/_t-pgsql     |   3 +
 completions/t-pgsql.bash |   2 +-
 completions/t-pgsql.fish |   2 +-
 src/01-globals.sh        |   1 +
 src/30-help.sh           |   2 +
 src/71-explain.sh        | 279 +++++++++++++++++++++++
 src/73-doctor.sh         | 186 +++++++++++++++
 src/90-args.sh           |   6 +
 src/99-main.sh           |   2 +
 src/build.manifest       |   2 +
 t-pgsql                  | 476 +++++++++++++++++++++++++++++++++++++++
 12 files changed, 982 insertions(+), 2 deletions(-)
 create mode 100644 src/71-explain.sh
 create mode 100644 src/73-doctor.sh

diff --git a/README.md b/README.md
index 2f62f4d..82f7217 100644
--- a/README.md
+++ b/README.md
@@ -494,6 +494,29 @@ Cleans old dump files.
 
 ---
 
+### doctor
+
+Runs local, read-only health checks and prints `✓ / ! / ✗` findings: required and optional tools, the output directory and free disk space, how fresh each database's newest dump is, whether the newest archives are readable, and the jobs file. Add `--from`/`--to` to also test connectivity. Exits non-zero if it finds a problem — handy in CI or a cron pre-flight.
+
+```bash
+./t-pgsql doctor
+./t-pgsql doctor --from "ssh://user@host/postgres@localhost/appdb"
+```
+
+---
+
+### explain
+
+Explains what a command is for and when to use it, with key options and examples — a built-in, offline reference.
+
+```bash
+./t-pgsql explain                 # list all topics
+./t-pgsql explain clone           # focused help for a command
+./t-pgsql explain masking         # also: stream, retention, doctor, ...
+```
+
+---
+
 ### jobs
 
 Lists saved batch jobs.
diff --git a/completions/_t-pgsql b/completions/_t-pgsql
index c20be24..ebb77b5 100644
--- a/completions/_t-pgsql
+++ b/completions/_t-pgsql
@@ -18,10 +18,13 @@ _t-pgsql() {
                 'upgrade:Logical major-version migration'
                 'fetch:Fetch existing dump from remote'
                 'batch:Run multiple jobs'
+                'bot:Telegram bot (listen for commands)'
                 'jobs:Manage saved jobs'
                 'list:List dump files'
                 'meta:Show metadata'
                 'clean:Clean old dumps'
+                'doctor:Check environment and backup health'
+                'explain:Explain what a command is for'
                 'version:Show version'
                 'help:Show help'
             )
diff --git a/completions/t-pgsql.bash b/completions/t-pgsql.bash
index bb487fd..520d19d 100644
--- a/completions/t-pgsql.bash
+++ b/completions/t-pgsql.bash
@@ -4,7 +4,7 @@ _t_pgsql() {
     local cur prev words cword
     _init_completion || return
 
-    local commands="dump restore clone upgrade fetch batch jobs list meta clean version help"
+    local commands="dump restore clone upgrade fetch batch bot jobs list meta clean doctor explain version help"
 
     local opts="
         --from --to
diff --git a/completions/t-pgsql.fish b/completions/t-pgsql.fish
index dd717ef..a121258 100644
--- a/completions/t-pgsql.fish
+++ b/completions/t-pgsql.fish
@@ -1,7 +1,7 @@
 # Fish completion for t-pgsql
 
 # Commands
-set -l commands dump restore clone upgrade fetch batch jobs list meta clean version help
+set -l commands dump restore clone upgrade fetch batch bot jobs list meta clean doctor explain version help
 
 # Disable file completion by default
 complete -c t-pgsql -f
diff --git a/src/01-globals.sh b/src/01-globals.sh
index d5114f3..efd5c96 100644
--- a/src/01-globals.sh
+++ b/src/01-globals.sh
@@ -135,6 +135,7 @@ FILE=""
 
 # Clean (optional positional database/base-name for the "clean" command)
 CLEAN_DB=""
+EXPLAIN_TARGET=""
 
 # Custom dump base name (also usable by "clean")
 DUMP_NAME=""
diff --git a/src/30-help.sh b/src/30-help.sh
index b7b75bf..392edab 100644
--- a/src/30-help.sh
+++ b/src/30-help.sh
@@ -27,6 +27,8 @@ COMMANDS:
                   clean <db> --keep <N>        Clean by database name
                   clean --from <conn> --keep <N>
                   clean --dump-name <name> --retention
+    doctor      Check the environment and backup health (add --from/--to to test connectivity)
+    explain     Explain what a command is for: explain [dump|restore|clone|upgrade|...]
     version     Show version
 
 CONNECTION:
diff --git a/src/71-explain.sh b/src/71-explain.sh
new file mode 100644
index 0000000..2085316
--- /dev/null
+++ b/src/71-explain.sh
@@ -0,0 +1,279 @@
+# ==============================================================================
+# EXPLAIN — teach what each command is for and when to use it
+# ==============================================================================
+# `t-pgsql explain`          lists the topics
+# `t-pgsql explain <topic>`  prints a focused, example-driven explanation
+
+_ex_title() { echo -e "${BOLD}t-pgsql $1${NC} — $2"; echo; }
+_ex_sec()   { echo -e "${CYAN}$1${NC}"; }
+_ex_see()   { echo; echo -e "${MAGENTA}See also:${NC} $1"; }
+
+_explain_overview() {
+    echo -e "${BOLD}t-pgsql — what each command is for${NC}"
+    echo
+    echo -e "  ${CYAN}dump${NC}      Back up one database to a compressed -Fc file"
+    echo -e "  ${CYAN}restore${NC}   Load a dump back into a database (safe on --force)"
+    echo -e "  ${CYAN}clone${NC}     Dump + restore in one step (full sync)"
+    echo -e "  ${CYAN}upgrade${NC}   Logical major-version migration (e.g. 16 → 18) with globals"
+    echo -e "  ${CYAN}fetch${NC}     Download an existing remote dump (no new dump)"
+    echo -e "  ${CYAN}batch${NC}     Run saved jobs from a jobs.yaml"
+    echo -e "  ${CYAN}bot${NC}       Telegram bot to trigger/monitor backups from a chat"
+    echo -e "  ${CYAN}list${NC} / ${CYAN}meta${NC} / ${CYAN}clean${NC}   Inspect dumps, show metadata, prune old dumps"
+    echo -e "  ${CYAN}doctor${NC}    Check the environment and backup health"
+    echo
+    echo -e "  Extra topics: ${CYAN}stream${NC}, ${CYAN}masking${NC}, ${CYAN}retention${NC}"
+    echo
+    echo -e "Run ${BOLD}t-pgsql explain <topic>${NC} for details, e.g. ${BOLD}t-pgsql explain clone${NC}."
+}
+
+_explain_dump() {
+    _ex_title "dump" "point-in-time backup of one database"
+    _ex_sec "What it does"
+    echo "  Runs pg_dump in the custom format (-Fc) and writes a timestamped file"
+    echo "  to the output directory. Works against a local/TCP database or, with an"
+    echo "  ssh:// source, dumps on the remote host and transfers the file back."
+    echo
+    _ex_sec "When to use"
+    echo "  • Scheduled backups (cron / batch jobs)"
+    echo "  • A safety snapshot before a risky migration or deploy"
+    echo "  • Archiving a database for later"
+    echo
+    _ex_sec "Key options"
+    echo "  --from <conn>          source database"
+    echo "  --output <dir>         where to write (default: <script>/../data/dumps)"
+    echo "  --compress <type>      zstd | gzip | xz | bzip2 | none"
+    echo "  --keep <N>             keep only the newest N dumps locally"
+    echo "  --retention            GFS rotation (daily/weekly/monthly/yearly)"
+    echo "  --exclude-table/-data  filter what is dumped"
+    echo "  --skip-if-recent <t>   skip if a dump already exists within the window"
+    echo
+    _ex_sec "Examples"
+    echo "  t-pgsql dump --from \"postgres@localhost/appdb\" --compress zstd --keep 7"
+    echo "  t-pgsql dump --from \"ssh://user@host/postgres@localhost/db\" \\"
+    echo "               --from-password-file .secrets/db.pass --retention"
+    _ex_see "explain restore · explain retention · explain masking"
+}
+
+_explain_restore() {
+    _ex_title "restore" "load a dump back into a database"
+    _ex_sec "What it does"
+    echo "  Runs pg_restore from a dump file (any of .tar.gz/.dump/.dump.zst/.xz/.bz2,"
+    echo "  auto-picking the newest if --file is omitted) into one or more --to targets."
+    echo
+    _ex_sec "Why it is safe with --force"
+    echo "  --force does NOT drop the target first. t-pgsql restores into a temporary"
+    echo "  database and swaps it in only when the restore fully succeeds — a corrupt or"
+    echo "  truncated dump can never destroy the existing data. It also preserves the"
+    echo "  source encoding/locale."
+    echo
+    _ex_sec "When to use"
+    echo "  • Recovering a database from a backup"
+    echo "  • Spinning up a copy on another host"
+    echo
+    _ex_sec "Key options"
+    echo "  --to <conn>            target (repeatable for multiple targets)"
+    echo "  --file <path>          dump to restore (default: newest in --output)"
+    echo "  --force               overwrite an existing target (safe temp-swap)"
+    echo "  --mask                anonymize sensitive columns after restore"
+    echo
+    _ex_sec "Examples"
+    echo "  t-pgsql restore --to \"postgres@localhost/appdb\" --force -y"
+    echo "  t-pgsql restore --file dumps/appdb_20260706.tar.gz --to \"postgres@localhost/dev\""
+    _ex_see "explain clone · explain masking"
+}
+
+_explain_clone() {
+    _ex_title "clone" "dump + restore in one step"
+    _ex_sec "What it does"
+    echo "  A full sync: dumps --from and restores it into --to. With --globals it also"
+    echo "  migrates cluster roles/tablespaces first. Refuses source == target."
+    echo
+    _ex_sec "When to use"
+    echo "  • Refreshing dev/staging from production"
+    echo "  • One-shot copy of a database between hosts"
+    echo
+    _ex_sec "Key options"
+    echo "  --from / --to <conn>   source and target (--to repeatable)"
+    echo "  --stream               pipe directly, no temp files (see: explain stream)"
+    echo "  --mask                 anonymize data after restore (not with --stream)"
+    echo "  --force                overwrite the target (safe temp-swap)"
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql clone --from \"ssh://user@prod/postgres@localhost/appdb\" \\"
+    echo "                --to \"postgres@localhost/appdb_dev\" \\"
+    echo "                --from-password-file .secrets/prod.pass --force -y"
+    _ex_see "explain stream · explain dump · explain restore"
+}
+
+_explain_stream() {
+    _ex_title "clone --stream" "pipe dump→restore with no temp files"
+    _ex_sec "What it does"
+    echo "  Streams pg_dump directly into pg_restore over a pipe — nothing is staged to"
+    echo "  disk. Use --stream-buffer <MB> and --bwlimit to shape the flow (needs 'pv')."
+    echo
+    _ex_sec "When to use"
+    echo "  • Very large databases"
+    echo "  • Hosts that don't have room for a temporary dump file"
+    echo
+    _ex_sec "Trade-offs"
+    echo "  • --mask is NOT supported (masking runs after a full restore)"
+    echo "  • The remote command rides briefly in the ssh argv during the stream"
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql clone --stream --from \"...\" --to \"...\" --bwlimit 50m --force -y"
+    _ex_see "explain clone"
+}
+
+_explain_upgrade() {
+    _ex_title "upgrade" "logical major-version migration"
+    _ex_sec "What it does"
+    echo "  A clone that also migrates cluster globals and refuses to restore into an"
+    echo "  OLDER major version. It is a logical dump+restore — NOT a pg_upgrade or"
+    echo "  logical-replication replacement for large, low-downtime migrations."
+    echo
+    _ex_sec "Important"
+    echo "  Run it where pg_dump matches the TARGET major version (e.g. PG18), or point"
+    echo "  --pg-bindir at that version's client tools."
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql upgrade --from \"postgres@old-16:5432/appdb\" \\"
+    echo "                  --to \"postgres@new-18:5432/appdb\" \\"
+    echo "                  --pg-bindir /usr/lib/postgresql/18/bin -y"
+    _ex_see "explain clone"
+}
+
+_explain_fetch() {
+    _ex_title "fetch" "download an existing remote dump"
+    _ex_sec "What it does"
+    echo "  Downloads a dump that already exists on an ssh:// source (from its"
+    echo "  /tmp/t-pgsql dir) without creating a new one."
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql fetch --from \"ssh://user@host/postgres@localhost/appdb\" --from-file latest"
+    _ex_see "explain dump"
+}
+
+_explain_batch() {
+    _ex_title "batch / jobs" "run saved jobs from a jobs.yaml"
+    _ex_sec "What it does"
+    echo "  Saved jobs live in a YAML file. 'batch <job>' runs one; 'batch all' runs all"
+    echo "  (with --only-jobs/--exclude-jobs filters, optional --parallel N). Save the"
+    echo "  current command as a job with --save <name>."
+    echo
+    _ex_sec "Key options"
+    echo "  --yaml <name>          jobs file (bare name → <script>/<name>.yaml)"
+    echo "  --parallel <N>         run N jobs concurrently"
+    echo "  --continue-on-error    keep going if a job fails"
+    echo "  --notify-summary       send one summary after the batch"
+    echo
+    _ex_sec "Examples"
+    echo "  t-pgsql clone --from ... --to ... --save nightly     # save it"
+    echo "  t-pgsql batch nightly --yaml jobs.yaml -y            # run it"
+    echo "  t-pgsql jobs list                                   # see saved jobs"
+    _ex_see "explain doctor · README (jobs.yaml format)"
+}
+
+_explain_bot() {
+    _ex_title "bot" "control backups from a Telegram chat"
+    _ex_sec "What it does"
+    echo "  A long-running poller that only obeys the configured chat (fail-closed)."
+    echo "  Chat commands: /help, /list, /list <yaml>, /backup <yaml> <job>, plus a"
+    echo "  'Re-run Backup' button on failure notifications."
+    echo
+    _ex_sec "Key options"
+    echo "  --token <token>        bot token (or TELEGRAM_BOT_TOKEN / YAML defaults)"
+    echo "  --cooldown <t>         throttle re-triggered runs (default 1h)"
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql bot --yaml jobs.yaml --token \"123:ABC...\" --cooldown 30m"
+    _ex_see "explain batch"
+}
+
+_explain_maint() {
+    _ex_title "list / meta / clean" "inspect and prune dumps"
+    _ex_sec "list"
+    echo "  Show dump files in --output, newest first, with size and date."
+    echo
+    _ex_sec "meta"
+    echo "  Show the metadata sidecar for a dump (timing, source, target)."
+    echo
+    _ex_sec "clean"
+    echo "  Delete old dumps for a base name per --keep or --retention (GFS). The single"
+    echo "  newest dump is always kept. Supports --dry-run."
+    echo
+    _ex_sec "Examples"
+    echo "  t-pgsql list"
+    echo "  t-pgsql clean appdb --retention --dry-run"
+    _ex_see "explain retention · explain doctor"
+}
+
+_explain_doctor() {
+    _ex_title "doctor" "check the environment and backup health"
+    _ex_sec "What it does"
+    echo "  Runs local checks and prints ✓/!/✗ findings: required and optional tools,"
+    echo "  the output directory and free disk space, how fresh each database's newest"
+    echo "  dump is, whether the newest archives are readable, and the jobs file. Add"
+    echo "  --from/--to to also test connectivity. Exits non-zero if it finds a problem."
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql doctor"
+    echo "  t-pgsql doctor --from \"ssh://user@host/postgres@localhost/appdb\""
+    _ex_see "explain list"
+}
+
+_explain_mask() {
+    _ex_title "masking" "anonymize sensitive data after restore"
+    _ex_sec "What it does"
+    echo "  With --mask, after a restore/clone t-pgsql overwrites sensitive columns."
+    echo "  --mask-tables auto-masks known columns (email, phone, password, ssn, ...)"
+    echo "  that actually exist; --mask-rules applies your own SQL from a JSON file."
+    echo "  Fail-safe: if nothing was masked, or a statement errors, the op FAILS rather"
+    echo "  than reporting an unmasked copy as success. Not supported with --stream."
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql clone --from ... --to ... --mask --mask-tables \"users,customers\" --force"
+    _ex_see "explain clone · explain restore"
+}
+
+_explain_retention() {
+    _ex_title "retention" "Grandfather-Father-Son dump rotation"
+    _ex_sec "What it does"
+    echo "  With --retention, t-pgsql keeps the newest dump per day/week/month/year up"
+    echo "  to the configured counts and prunes the rest. The single newest dump is"
+    echo "  always kept, so retention can never leave a base with nothing."
+    echo
+    _ex_sec "Key options"
+    echo "  --retention                 enable GFS"
+    echo "  --retention-daily <N>       (default 7)"
+    echo "  --retention-weekly <N>      (default 4)"
+    echo "  --retention-monthly <N>     (default 12)"
+    echo "  --retention-yearly <N>      (default 3)"
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql dump --from ... --retention --retention-daily 14 --retention-monthly 24"
+    _ex_see "explain dump · explain clean"
+}
+
+cmd_explain() {
+    local topic
+    topic=$(printf '%s' "${EXPLAIN_TARGET:-}" | tr '[:upper:]' '[:lower:]')
+    case "$topic" in
+        "")                     _explain_overview ;;
+        dump)                   _explain_dump ;;
+        restore)                _explain_restore ;;
+        clone)                  _explain_clone ;;
+        stream|streaming)       _explain_stream ;;
+        upgrade)                _explain_upgrade ;;
+        fetch)                  _explain_fetch ;;
+        batch|jobs|job)         _explain_batch ;;
+        bot|telegram)           _explain_bot ;;
+        list|meta|clean)        _explain_maint ;;
+        doctor)                 _explain_doctor ;;
+        mask|masking)           _explain_mask ;;
+        retention|gfs)          _explain_retention ;;
+        *)
+            log_error "No explanation for '$topic'. Run 't-pgsql explain' to see the topics."
+            return 1
+            ;;
+    esac
+}
diff --git a/src/73-doctor.sh b/src/73-doctor.sh
new file mode 100644
index 0000000..e33a7ce
--- /dev/null
+++ b/src/73-doctor.sh
@@ -0,0 +1,186 @@
+# ==============================================================================
+# DOCTOR — environment & backup-health checks
+# ==============================================================================
+# Local, read-only diagnostics: required/optional tools, output dir + free disk,
+# per-database backup freshness, newest-archive readability, and the jobs file.
+# With --from/--to it also tests connectivity. Exits non-zero if a problem is found.
+
+DOCTOR_WARN=0
+DOCTOR_FAIL=0
+_dok_ok()   { echo -e "  ${GREEN}\xE2\x9C\x93${NC} $1"; }
+_dok_warn() { echo -e "  ${YELLOW}!${NC} $1"; DOCTOR_WARN=$((DOCTOR_WARN+1)); }
+_dok_fail() { echo -e "  ${RED}\xE2\x9C\x97${NC} $1"; DOCTOR_FAIL=$((DOCTOR_FAIL+1)); }
+_dok_note() { echo -e "    ${CYAN}\xE2\x86\xB3${NC} $1"; }
+_dok_head() { echo; echo -e "${BOLD}$1${NC}"; }
+
+# Cross-platform file mtime (GNU stat -c, then BSD stat -f).
+_dok_mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null; }
+
+# Human-friendly age from a number of seconds.
+_dok_age() {
+    local s=$1
+    if [ "$s" -lt 3600 ]; then echo "$((s/60))m"
+    elif [ "$s" -lt 86400 ]; then echo "$((s/3600))h $(((s%3600)/60))m"
+    else echo "$((s/86400))d $(((s%86400)/3600))h"; fi
+}
+
+# Distinct dump base names present in the output directory.
+_dok_bases() {
+    ls -1 "$OUTPUT_DIR"/*.tar.gz "$OUTPUT_DIR"/*.dump "$OUTPUT_DIR"/*.dump.zst \
+          "$OUTPUT_DIR"/*.dump.xz "$OUTPUT_DIR"/*.dump.bz2 2>/dev/null \
+        | while IFS= read -r f; do basename "$f"; done \
+        | sed -E 's/_[0-9]{8}_[0-9]{6}(_[0-9]+)?\.(tar\.gz|dump\.zst|dump\.xz|dump\.bz2|dump)$//' \
+        | sort -u
+}
+
+_dok_tool() {
+    local name="$1" req="$2" why="$3"
+    if command -v "$name" >/dev/null 2>&1; then
+        _dok_ok "$name"
+    elif [ "$req" = "req" ]; then
+        _dok_fail "$name not found (required)"
+    else
+        _dok_warn "$name not found — ${why:-optional}"
+    fi
+}
+
+cmd_doctor() {
+    DOCTOR_WARN=0; DOCTOR_FAIL=0
+    echo -e "${BOLD}t-pgsql doctor${NC} — environment & backup health"
+
+    # ---- Toolchain --------------------------------------------------------
+    _dok_head "Toolchain"
+    _dok_tool pg_dump    req
+    _dok_tool pg_restore req
+    _dok_tool psql       req
+    _dok_tool createdb   req
+    _dok_tool dropdb     req
+    _dok_tool pg_dumpall opt "needed for --globals / upgrade"
+    _dok_tool ssh        opt "needed for ssh:// connections"
+    _dok_tool scp        opt "needed for SSH transfers"
+    _dok_tool pv         opt "needed for --stream buffering / --bwlimit"
+    _dok_tool zstd       opt "needed for --compress zstd"
+    _dok_tool xz         opt "needed for --compress xz"
+    _dok_tool bzip2      opt "needed for --compress bzip2"
+    _dok_tool curl       opt "needed for notifications / bot"
+    _dok_tool python3    opt "improves the Telegram bot update parsing"
+
+    # ---- Storage ----------------------------------------------------------
+    _dok_head "Backup storage"
+    if [ -d "$OUTPUT_DIR" ]; then
+        _dok_ok "output directory: $OUTPUT_DIR"
+        [ -w "$OUTPUT_DIR" ] || _dok_warn "output directory is not writable"
+        local dfline avail usep availh
+        dfline=$(df -Pk "$OUTPUT_DIR" 2>/dev/null | awk 'NR==2{print $4","$5}')
+        if [ -n "$dfline" ]; then
+            avail=${dfline%,*}; usep=${dfline#*,}; usep=${usep%\%}
+            availh=$(awk -v k="$avail" 'BEGIN{ if(k>1048576) printf "%.1f GB", k/1048576; else printf "%.0f MB", k/1024 }')
+            if   [ "${usep:-0}" -ge 90 ]; then _dok_fail "disk ${usep}% used — only ${availh} free"
+            elif [ "${usep:-0}" -ge 85 ]; then _dok_warn "disk ${usep}% used — ${availh} free"
+            else _dok_ok "disk ${usep}% used — ${availh} free"; fi
+        fi
+    else
+        _dok_note "output directory does not exist yet: $OUTPUT_DIR (created on first dump)"
+    fi
+
+    # ---- Freshness --------------------------------------------------------
+    _dok_head "Backup freshness"
+    local bases; bases=$(_dok_bases)
+    if [ -z "$bases" ]; then
+        _dok_note "no dumps found in $OUTPUT_DIR"
+    else
+        local now base newest mt age count
+        now=$(date +%s)
+        while IFS= read -r base; do
+            [ -z "$base" ] && continue
+            newest=$(list_dumps_for_base "$OUTPUT_DIR" "$base" | head -1)
+            [ -z "$newest" ] && continue
+            mt=$(_dok_mtime "$newest"); [ -z "$mt" ] && continue
+            age=$((now - mt))
+            count=$(list_dumps_for_base "$OUTPUT_DIR" "$base" | wc -l | tr -d ' ')
+            if [ "$age" -ge 172800 ]; then
+                _dok_warn "$base — newest dump is $(_dok_age "$age") old (${count} kept)"
+            else
+                _dok_ok "$base — newest $(_dok_age "$age") ago (${count} kept)"
+            fi
+        done <<< "$bases"
+    fi
+
+    # ---- Integrity (newest archive per base) ------------------------------
+    if [ -n "$bases" ]; then
+        _dok_head "Archive integrity (newest per database)"
+        local newest bn
+        while IFS= read -r base; do
+            [ -z "$base" ] && continue
+            newest=$(list_dumps_for_base "$OUTPUT_DIR" "$base" | head -1)
+            [ -z "$newest" ] && continue
+            bn=$(basename "$newest")
+            case "$newest" in
+                *.tar.gz)
+                    if tar -tzf "$newest" 2>/dev/null | head -1 | grep -q .; then _dok_ok "$bn — readable archive"
+                    else _dok_fail "$bn — unreadable tar.gz"; fi ;;
+                *.dump)
+                    if command -v pg_restore >/dev/null 2>&1 && pg_restore -l "$newest" >/dev/null 2>&1; then _dok_ok "$bn — valid dump archive"
+                    else _dok_warn "$bn — could not validate (pg_restore)"; fi ;;
+                *.dump.zst)
+                    if command -v zstd >/dev/null 2>&1 && zstd -l "$newest" >/dev/null 2>&1; then _dok_ok "$bn — valid zstd"
+                    else _dok_warn "$bn — could not validate (zstd)"; fi ;;
+                *.dump.xz)
+                    if command -v xz >/dev/null 2>&1 && xz -l "$newest" >/dev/null 2>&1; then _dok_ok "$bn — valid xz"
+                    else _dok_warn "$bn — could not validate (xz)"; fi ;;
+                *)
+                    if [ -s "$newest" ]; then _dok_ok "$bn — present"; else _dok_fail "$bn — empty file"; fi ;;
+            esac
+        done <<< "$bases"
+    fi
+
+    # ---- Jobs configuration ----------------------------------------------
+    _dok_head "Jobs configuration"
+    if [ -f "$JOBS_FILE" ]; then
+        local jc
+        jc=$(awk '/^jobs:/{f=1;next} /^[a-zA-Z]/{if($0!~/^jobs:/)f=0} f&&/^  [a-zA-Z0-9_-]+:/{c++} END{print c+0}' "$JOBS_FILE")
+        _dok_ok "jobs file: $JOBS_FILE (${jc} job(s))"
+        local pf exp
+        while IFS= read -r pf; do
+            [ -z "$pf" ] && continue
+            exp="${pf/#\~/$HOME}"
+            [ -f "$exp" ] || _dok_warn "job password file not found: $pf"
+        done < <(grep -hoE 'password_file:[[:space:]]*"?[^"]+' "$JOBS_FILE" 2>/dev/null | sed -E 's/.*password_file:[[:space:]]*"?//')
+    else
+        _dok_note "no jobs file at $JOBS_FILE (optional)"
+    fi
+
+    # ---- Connections (only if a connection was supplied) ------------------
+    if [ -n "$FROM_CONNECTION" ] || [ "${#TO_CONNECTIONS[@]}" -gt 0 ]; then
+        _dok_head "Connections"
+        if [ -n "$FROM_CONNECTION" ]; then
+            if parse_connection "$FROM_CONNECTION" "FROM"; then
+                get_password "FROM"
+                if health_check "FROM" "Source" >/dev/null 2>&1; then _dok_ok "source reachable: $FROM_CONNECTION"
+                else _dok_fail "source NOT reachable: $FROM_CONNECTION"; fi
+            else _dok_fail "invalid source connection: $FROM_CONNECTION"; fi
+        fi
+        local i=0 conn
+        for conn in "${TO_CONNECTIONS[@]}"; do
+            if parse_connection "$conn" "TO"; then
+                get_password "TO" "$i"
+                if health_check "TO" "Target" >/dev/null 2>&1; then _dok_ok "target reachable: $conn"
+                else _dok_fail "target NOT reachable: $conn"; fi
+            else _dok_fail "invalid target connection: $conn"; fi
+            i=$((i+1))
+        done
+    fi
+
+    # ---- Summary ----------------------------------------------------------
+    echo
+    if [ "$DOCTOR_FAIL" -gt 0 ]; then
+        echo -e "${RED}\xE2\x9C\x97 ${DOCTOR_FAIL} problem(s), ${DOCTOR_WARN} warning(s)${NC}"
+        return 1
+    elif [ "$DOCTOR_WARN" -gt 0 ]; then
+        echo -e "${YELLOW}! ${DOCTOR_WARN} warning(s), no blocking problems${NC}"
+        return 0
+    else
+        echo -e "${GREEN}\xE2\x9C\x93 all checks passed${NC}"
+        return 0
+    fi
+}
diff --git a/src/90-args.sh b/src/90-args.sh
index 85e1e0d..23c9698 100644
--- a/src/90-args.sh
+++ b/src/90-args.sh
@@ -60,6 +60,12 @@ parse_args() {
         shift
     fi
 
+    # Handle explain subcommand optional positional topic (explain <topic>)
+    if [ "$COMMAND" = "explain" ] && [ $# -gt 0 ] && [[ "$1" != -* ]]; then
+        EXPLAIN_TARGET="$1"
+        shift
+    fi
+
     while [[ $# -gt 0 ]]; do
         case $1 in
             --from) FROM_CONNECTION="$2"; shift 2 || _need_val "$1" ;;
diff --git a/src/99-main.sh b/src/99-main.sh
index 9726170..b1f74e4 100644
--- a/src/99-main.sh
+++ b/src/99-main.sh
@@ -115,6 +115,8 @@ main() {
         list)    cmd_list ;;
         meta)    cmd_meta ;;
         clean)   cmd_clean ;;
+        doctor)  cmd_doctor ;;
+        explain) cmd_explain ;;
         jobs)
             case "$JOBS_ACTION" in
                 show)   show_job "$JOBS_TARGET" ;;
diff --git a/src/build.manifest b/src/build.manifest
index 4708e2e..68b03c1 100644
--- a/src/build.manifest
+++ b/src/build.manifest
@@ -16,7 +16,9 @@
 66-stream.sh
 68-clone.sh
 70-upgrade.sh
+71-explain.sh
 72-list-meta-clean.sh
+73-doctor.sh
 75-yaml.sh
 76-jobs.sh
 78-batch.sh
diff --git a/t-pgsql b/t-pgsql
index 8ca9aad..a90d79f 100755
--- a/t-pgsql
+++ b/t-pgsql
@@ -174,6 +174,7 @@ FILE=""
 
 # Clean (optional positional database/base-name for the "clean" command)
 CLEAN_DB=""
+EXPLAIN_TARGET=""
 
 # Custom dump base name (also usable by "clean")
 DUMP_NAME=""
@@ -1036,6 +1037,8 @@ COMMANDS:
                   clean <db> --keep <N>        Clean by database name
                   clean --from <conn> --keep <N>
                   clean --dump-name <name> --retention
+    doctor      Check the environment and backup health (add --from/--to to test connectivity)
+    explain     Explain what a command is for: explain [dump|restore|clone|upgrade|...]
     version     Show version
 
 CONNECTION:
@@ -3084,6 +3087,285 @@ cmd_upgrade() {
     cmd_clone
 }
 
+# ==============================================================================
+# EXPLAIN — teach what each command is for and when to use it
+# ==============================================================================
+# `t-pgsql explain`          lists the topics
+# `t-pgsql explain <topic>`  prints a focused, example-driven explanation
+
+_ex_title() { echo -e "${BOLD}t-pgsql $1${NC} — $2"; echo; }
+_ex_sec()   { echo -e "${CYAN}$1${NC}"; }
+_ex_see()   { echo; echo -e "${MAGENTA}See also:${NC} $1"; }
+
+_explain_overview() {
+    echo -e "${BOLD}t-pgsql — what each command is for${NC}"
+    echo
+    echo -e "  ${CYAN}dump${NC}      Back up one database to a compressed -Fc file"
+    echo -e "  ${CYAN}restore${NC}   Load a dump back into a database (safe on --force)"
+    echo -e "  ${CYAN}clone${NC}     Dump + restore in one step (full sync)"
+    echo -e "  ${CYAN}upgrade${NC}   Logical major-version migration (e.g. 16 → 18) with globals"
+    echo -e "  ${CYAN}fetch${NC}     Download an existing remote dump (no new dump)"
+    echo -e "  ${CYAN}batch${NC}     Run saved jobs from a jobs.yaml"
+    echo -e "  ${CYAN}bot${NC}       Telegram bot to trigger/monitor backups from a chat"
+    echo -e "  ${CYAN}list${NC} / ${CYAN}meta${NC} / ${CYAN}clean${NC}   Inspect dumps, show metadata, prune old dumps"
+    echo -e "  ${CYAN}doctor${NC}    Check the environment and backup health"
+    echo
+    echo -e "  Extra topics: ${CYAN}stream${NC}, ${CYAN}masking${NC}, ${CYAN}retention${NC}"
+    echo
+    echo -e "Run ${BOLD}t-pgsql explain <topic>${NC} for details, e.g. ${BOLD}t-pgsql explain clone${NC}."
+}
+
+_explain_dump() {
+    _ex_title "dump" "point-in-time backup of one database"
+    _ex_sec "What it does"
+    echo "  Runs pg_dump in the custom format (-Fc) and writes a timestamped file"
+    echo "  to the output directory. Works against a local/TCP database or, with an"
+    echo "  ssh:// source, dumps on the remote host and transfers the file back."
+    echo
+    _ex_sec "When to use"
+    echo "  • Scheduled backups (cron / batch jobs)"
+    echo "  • A safety snapshot before a risky migration or deploy"
+    echo "  • Archiving a database for later"
+    echo
+    _ex_sec "Key options"
+    echo "  --from <conn>          source database"
+    echo "  --output <dir>         where to write (default: <script>/../data/dumps)"
+    echo "  --compress <type>      zstd | gzip | xz | bzip2 | none"
+    echo "  --keep <N>             keep only the newest N dumps locally"
+    echo "  --retention            GFS rotation (daily/weekly/monthly/yearly)"
+    echo "  --exclude-table/-data  filter what is dumped"
+    echo "  --skip-if-recent <t>   skip if a dump already exists within the window"
+    echo
+    _ex_sec "Examples"
+    echo "  t-pgsql dump --from \"postgres@localhost/appdb\" --compress zstd --keep 7"
+    echo "  t-pgsql dump --from \"ssh://user@host/postgres@localhost/db\" \\"
+    echo "               --from-password-file .secrets/db.pass --retention"
+    _ex_see "explain restore · explain retention · explain masking"
+}
+
+_explain_restore() {
+    _ex_title "restore" "load a dump back into a database"
+    _ex_sec "What it does"
+    echo "  Runs pg_restore from a dump file (any of .tar.gz/.dump/.dump.zst/.xz/.bz2,"
+    echo "  auto-picking the newest if --file is omitted) into one or more --to targets."
+    echo
+    _ex_sec "Why it is safe with --force"
+    echo "  --force does NOT drop the target first. t-pgsql restores into a temporary"
+    echo "  database and swaps it in only when the restore fully succeeds — a corrupt or"
+    echo "  truncated dump can never destroy the existing data. It also preserves the"
+    echo "  source encoding/locale."
+    echo
+    _ex_sec "When to use"
+    echo "  • Recovering a database from a backup"
+    echo "  • Spinning up a copy on another host"
+    echo
+    _ex_sec "Key options"
+    echo "  --to <conn>            target (repeatable for multiple targets)"
+    echo "  --file <path>          dump to restore (default: newest in --output)"
+    echo "  --force               overwrite an existing target (safe temp-swap)"
+    echo "  --mask                anonymize sensitive columns after restore"
+    echo
+    _ex_sec "Examples"
+    echo "  t-pgsql restore --to \"postgres@localhost/appdb\" --force -y"
+    echo "  t-pgsql restore --file dumps/appdb_20260706.tar.gz --to \"postgres@localhost/dev\""
+    _ex_see "explain clone · explain masking"
+}
+
+_explain_clone() {
+    _ex_title "clone" "dump + restore in one step"
+    _ex_sec "What it does"
+    echo "  A full sync: dumps --from and restores it into --to. With --globals it also"
+    echo "  migrates cluster roles/tablespaces first. Refuses source == target."
+    echo
+    _ex_sec "When to use"
+    echo "  • Refreshing dev/staging from production"
+    echo "  • One-shot copy of a database between hosts"
+    echo
+    _ex_sec "Key options"
+    echo "  --from / --to <conn>   source and target (--to repeatable)"
+    echo "  --stream               pipe directly, no temp files (see: explain stream)"
+    echo "  --mask                 anonymize data after restore (not with --stream)"
+    echo "  --force                overwrite the target (safe temp-swap)"
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql clone --from \"ssh://user@prod/postgres@localhost/appdb\" \\"
+    echo "                --to \"postgres@localhost/appdb_dev\" \\"
+    echo "                --from-password-file .secrets/prod.pass --force -y"
+    _ex_see "explain stream · explain dump · explain restore"
+}
+
+_explain_stream() {
+    _ex_title "clone --stream" "pipe dump→restore with no temp files"
+    _ex_sec "What it does"
+    echo "  Streams pg_dump directly into pg_restore over a pipe — nothing is staged to"
+    echo "  disk. Use --stream-buffer <MB> and --bwlimit to shape the flow (needs 'pv')."
+    echo
+    _ex_sec "When to use"
+    echo "  • Very large databases"
+    echo "  • Hosts that don't have room for a temporary dump file"
+    echo
+    _ex_sec "Trade-offs"
+    echo "  • --mask is NOT supported (masking runs after a full restore)"
+    echo "  • The remote command rides briefly in the ssh argv during the stream"
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql clone --stream --from \"...\" --to \"...\" --bwlimit 50m --force -y"
+    _ex_see "explain clone"
+}
+
+_explain_upgrade() {
+    _ex_title "upgrade" "logical major-version migration"
+    _ex_sec "What it does"
+    echo "  A clone that also migrates cluster globals and refuses to restore into an"
+    echo "  OLDER major version. It is a logical dump+restore — NOT a pg_upgrade or"
+    echo "  logical-replication replacement for large, low-downtime migrations."
+    echo
+    _ex_sec "Important"
+    echo "  Run it where pg_dump matches the TARGET major version (e.g. PG18), or point"
+    echo "  --pg-bindir at that version's client tools."
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql upgrade --from \"postgres@old-16:5432/appdb\" \\"
+    echo "                  --to \"postgres@new-18:5432/appdb\" \\"
+    echo "                  --pg-bindir /usr/lib/postgresql/18/bin -y"
+    _ex_see "explain clone"
+}
+
+_explain_fetch() {
+    _ex_title "fetch" "download an existing remote dump"
+    _ex_sec "What it does"
+    echo "  Downloads a dump that already exists on an ssh:// source (from its"
+    echo "  /tmp/t-pgsql dir) without creating a new one."
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql fetch --from \"ssh://user@host/postgres@localhost/appdb\" --from-file latest"
+    _ex_see "explain dump"
+}
+
+_explain_batch() {
+    _ex_title "batch / jobs" "run saved jobs from a jobs.yaml"
+    _ex_sec "What it does"
+    echo "  Saved jobs live in a YAML file. 'batch <job>' runs one; 'batch all' runs all"
+    echo "  (with --only-jobs/--exclude-jobs filters, optional --parallel N). Save the"
+    echo "  current command as a job with --save <name>."
+    echo
+    _ex_sec "Key options"
+    echo "  --yaml <name>          jobs file (bare name → <script>/<name>.yaml)"
+    echo "  --parallel <N>         run N jobs concurrently"
+    echo "  --continue-on-error    keep going if a job fails"
+    echo "  --notify-summary       send one summary after the batch"
+    echo
+    _ex_sec "Examples"
+    echo "  t-pgsql clone --from ... --to ... --save nightly     # save it"
+    echo "  t-pgsql batch nightly --yaml jobs.yaml -y            # run it"
+    echo "  t-pgsql jobs list                                   # see saved jobs"
+    _ex_see "explain doctor · README (jobs.yaml format)"
+}
+
+_explain_bot() {
+    _ex_title "bot" "control backups from a Telegram chat"
+    _ex_sec "What it does"
+    echo "  A long-running poller that only obeys the configured chat (fail-closed)."
+    echo "  Chat commands: /help, /list, /list <yaml>, /backup <yaml> <job>, plus a"
+    echo "  'Re-run Backup' button on failure notifications."
+    echo
+    _ex_sec "Key options"
+    echo "  --token <token>        bot token (or TELEGRAM_BOT_TOKEN / YAML defaults)"
+    echo "  --cooldown <t>         throttle re-triggered runs (default 1h)"
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql bot --yaml jobs.yaml --token \"123:ABC...\" --cooldown 30m"
+    _ex_see "explain batch"
+}
+
+_explain_maint() {
+    _ex_title "list / meta / clean" "inspect and prune dumps"
+    _ex_sec "list"
+    echo "  Show dump files in --output, newest first, with size and date."
+    echo
+    _ex_sec "meta"
+    echo "  Show the metadata sidecar for a dump (timing, source, target)."
+    echo
+    _ex_sec "clean"
+    echo "  Delete old dumps for a base name per --keep or --retention (GFS). The single"
+    echo "  newest dump is always kept. Supports --dry-run."
+    echo
+    _ex_sec "Examples"
+    echo "  t-pgsql list"
+    echo "  t-pgsql clean appdb --retention --dry-run"
+    _ex_see "explain retention · explain doctor"
+}
+
+_explain_doctor() {
+    _ex_title "doctor" "check the environment and backup health"
+    _ex_sec "What it does"
+    echo "  Runs local checks and prints ✓/!/✗ findings: required and optional tools,"
+    echo "  the output directory and free disk space, how fresh each database's newest"
+    echo "  dump is, whether the newest archives are readable, and the jobs file. Add"
+    echo "  --from/--to to also test connectivity. Exits non-zero if it finds a problem."
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql doctor"
+    echo "  t-pgsql doctor --from \"ssh://user@host/postgres@localhost/appdb\""
+    _ex_see "explain list"
+}
+
+_explain_mask() {
+    _ex_title "masking" "anonymize sensitive data after restore"
+    _ex_sec "What it does"
+    echo "  With --mask, after a restore/clone t-pgsql overwrites sensitive columns."
+    echo "  --mask-tables auto-masks known columns (email, phone, password, ssn, ...)"
+    echo "  that actually exist; --mask-rules applies your own SQL from a JSON file."
+    echo "  Fail-safe: if nothing was masked, or a statement errors, the op FAILS rather"
+    echo "  than reporting an unmasked copy as success. Not supported with --stream."
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql clone --from ... --to ... --mask --mask-tables \"users,customers\" --force"
+    _ex_see "explain clone · explain restore"
+}
+
+_explain_retention() {
+    _ex_title "retention" "Grandfather-Father-Son dump rotation"
+    _ex_sec "What it does"
+    echo "  With --retention, t-pgsql keeps the newest dump per day/week/month/year up"
+    echo "  to the configured counts and prunes the rest. The single newest dump is"
+    echo "  always kept, so retention can never leave a base with nothing."
+    echo
+    _ex_sec "Key options"
+    echo "  --retention                 enable GFS"
+    echo "  --retention-daily <N>       (default 7)"
+    echo "  --retention-weekly <N>      (default 4)"
+    echo "  --retention-monthly <N>     (default 12)"
+    echo "  --retention-yearly <N>      (default 3)"
+    echo
+    _ex_sec "Example"
+    echo "  t-pgsql dump --from ... --retention --retention-daily 14 --retention-monthly 24"
+    _ex_see "explain dump · explain clean"
+}
+
+cmd_explain() {
+    local topic
+    topic=$(printf '%s' "${EXPLAIN_TARGET:-}" | tr '[:upper:]' '[:lower:]')
+    case "$topic" in
+        "")                     _explain_overview ;;
+        dump)                   _explain_dump ;;
+        restore)                _explain_restore ;;
+        clone)                  _explain_clone ;;
+        stream|streaming)       _explain_stream ;;
+        upgrade)                _explain_upgrade ;;
+        fetch)                  _explain_fetch ;;
+        batch|jobs|job)         _explain_batch ;;
+        bot|telegram)           _explain_bot ;;
+        list|meta|clean)        _explain_maint ;;
+        doctor)                 _explain_doctor ;;
+        mask|masking)           _explain_mask ;;
+        retention|gfs)          _explain_retention ;;
+        *)
+            log_error "No explanation for '$topic'. Run 't-pgsql explain' to see the topics."
+            return 1
+            ;;
+    esac
+}
 # ==============================================================================
 # LIST
 # ==============================================================================
@@ -3163,6 +3445,192 @@ cmd_clean() {
     log_success "Done"
 }
 
+# ==============================================================================
+# DOCTOR — environment & backup-health checks
+# ==============================================================================
+# Local, read-only diagnostics: required/optional tools, output dir + free disk,
+# per-database backup freshness, newest-archive readability, and the jobs file.
+# With --from/--to it also tests connectivity. Exits non-zero if a problem is found.
+
+DOCTOR_WARN=0
+DOCTOR_FAIL=0
+_dok_ok()   { echo -e "  ${GREEN}\xE2\x9C\x93${NC} $1"; }
+_dok_warn() { echo -e "  ${YELLOW}!${NC} $1"; DOCTOR_WARN=$((DOCTOR_WARN+1)); }
+_dok_fail() { echo -e "  ${RED}\xE2\x9C\x97${NC} $1"; DOCTOR_FAIL=$((DOCTOR_FAIL+1)); }
+_dok_note() { echo -e "    ${CYAN}\xE2\x86\xB3${NC} $1"; }
+_dok_head() { echo; echo -e "${BOLD}$1${NC}"; }
+
+# Cross-platform file mtime (GNU stat -c, then BSD stat -f).
+_dok_mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null; }
+
+# Human-friendly age from a number of seconds.
+_dok_age() {
+    local s=$1
+    if [ "$s" -lt 3600 ]; then echo "$((s/60))m"
+    elif [ "$s" -lt 86400 ]; then echo "$((s/3600))h $(((s%3600)/60))m"
+    else echo "$((s/86400))d $(((s%86400)/3600))h"; fi
+}
+
+# Distinct dump base names present in the output directory.
+_dok_bases() {
+    ls -1 "$OUTPUT_DIR"/*.tar.gz "$OUTPUT_DIR"/*.dump "$OUTPUT_DIR"/*.dump.zst \
+          "$OUTPUT_DIR"/*.dump.xz "$OUTPUT_DIR"/*.dump.bz2 2>/dev/null \
+        | while IFS= read -r f; do basename "$f"; done \
+        | sed -E 's/_[0-9]{8}_[0-9]{6}(_[0-9]+)?\.(tar\.gz|dump\.zst|dump\.xz|dump\.bz2|dump)$//' \
+        | sort -u
+}
+
+_dok_tool() {
+    local name="$1" req="$2" why="$3"
+    if command -v "$name" >/dev/null 2>&1; then
+        _dok_ok "$name"
+    elif [ "$req" = "req" ]; then
+        _dok_fail "$name not found (required)"
+    else
+        _dok_warn "$name not found — ${why:-optional}"
+    fi
+}
+
+cmd_doctor() {
+    DOCTOR_WARN=0; DOCTOR_FAIL=0
+    echo -e "${BOLD}t-pgsql doctor${NC} — environment & backup health"
+
+    # ---- Toolchain --------------------------------------------------------
+    _dok_head "Toolchain"
+    _dok_tool pg_dump    req
+    _dok_tool pg_restore req
+    _dok_tool psql       req
+    _dok_tool createdb   req
+    _dok_tool dropdb     req
+    _dok_tool pg_dumpall opt "needed for --globals / upgrade"
+    _dok_tool ssh        opt "needed for ssh:// connections"
+    _dok_tool scp        opt "needed for SSH transfers"
+    _dok_tool pv         opt "needed for --stream buffering / --bwlimit"
+    _dok_tool zstd       opt "needed for --compress zstd"
+    _dok_tool xz         opt "needed for --compress xz"
+    _dok_tool bzip2      opt "needed for --compress bzip2"
+    _dok_tool curl       opt "needed for notifications / bot"
+    _dok_tool python3    opt "improves the Telegram bot update parsing"
+
+    # ---- Storage ----------------------------------------------------------
+    _dok_head "Backup storage"
+    if [ -d "$OUTPUT_DIR" ]; then
+        _dok_ok "output directory: $OUTPUT_DIR"
+        [ -w "$OUTPUT_DIR" ] || _dok_warn "output directory is not writable"
+        local dfline avail usep availh
+        dfline=$(df -Pk "$OUTPUT_DIR" 2>/dev/null | awk 'NR==2{print $4","$5}')
+        if [ -n "$dfline" ]; then
+            avail=${dfline%,*}; usep=${dfline#*,}; usep=${usep%\%}
+            availh=$(awk -v k="$avail" 'BEGIN{ if(k>1048576) printf "%.1f GB", k/1048576; else printf "%.0f MB", k/1024 }')
+            if   [ "${usep:-0}" -ge 90 ]; then _dok_fail "disk ${usep}% used — only ${availh} free"
+            elif [ "${usep:-0}" -ge 85 ]; then _dok_warn "disk ${usep}% used — ${availh} free"
+            else _dok_ok "disk ${usep}% used — ${availh} free"; fi
+        fi
+    else
+        _dok_note "output directory does not exist yet: $OUTPUT_DIR (created on first dump)"
+    fi
+
+    # ---- Freshness --------------------------------------------------------
+    _dok_head "Backup freshness"
+    local bases; bases=$(_dok_bases)
+    if [ -z "$bases" ]; then
+        _dok_note "no dumps found in $OUTPUT_DIR"
+    else
+        local now base newest mt age count
+        now=$(date +%s)
+        while IFS= read -r base; do
+            [ -z "$base" ] && continue
+            newest=$(list_dumps_for_base "$OUTPUT_DIR" "$base" | head -1)
+            [ -z "$newest" ] && continue
+            mt=$(_dok_mtime "$newest"); [ -z "$mt" ] && continue
+            age=$((now - mt))
+            count=$(list_dumps_for_base "$OUTPUT_DIR" "$base" | wc -l | tr -d ' ')
+            if [ "$age" -ge 172800 ]; then
+                _dok_warn "$base — newest dump is $(_dok_age "$age") old (${count} kept)"
+            else
+                _dok_ok "$base — newest $(_dok_age "$age") ago (${count} kept)"
+            fi
+        done <<< "$bases"
+    fi
+
+    # ---- Integrity (newest archive per base) ------------------------------
+    if [ -n "$bases" ]; then
+        _dok_head "Archive integrity (newest per database)"
+        local newest bn
+        while IFS= read -r base; do
+            [ -z "$base" ] && continue
+            newest=$(list_dumps_for_base "$OUTPUT_DIR" "$base" | head -1)
+            [ -z "$newest" ] && continue
+            bn=$(basename "$newest")
+            case "$newest" in
+                *.tar.gz)
+                    if tar -tzf "$newest" 2>/dev/null | head -1 | grep -q .; then _dok_ok "$bn — readable archive"
+                    else _dok_fail "$bn — unreadable tar.gz"; fi ;;
+                *.dump)
+                    if command -v pg_restore >/dev/null 2>&1 && pg_restore -l "$newest" >/dev/null 2>&1; then _dok_ok "$bn — valid dump archive"
+                    else _dok_warn "$bn — could not validate (pg_restore)"; fi ;;
+                *.dump.zst)
+                    if command -v zstd >/dev/null 2>&1 && zstd -l "$newest" >/dev/null 2>&1; then _dok_ok "$bn — valid zstd"
+                    else _dok_warn "$bn — could not validate (zstd)"; fi ;;
+                *.dump.xz)
+                    if command -v xz >/dev/null 2>&1 && xz -l "$newest" >/dev/null 2>&1; then _dok_ok "$bn — valid xz"
+                    else _dok_warn "$bn — could not validate (xz)"; fi ;;
+                *)
+                    if [ -s "$newest" ]; then _dok_ok "$bn — present"; else _dok_fail "$bn — empty file"; fi ;;
+            esac
+        done <<< "$bases"
+    fi
+
+    # ---- Jobs configuration ----------------------------------------------
+    _dok_head "Jobs configuration"
+    if [ -f "$JOBS_FILE" ]; then
+        local jc
+        jc=$(awk '/^jobs:/{f=1;next} /^[a-zA-Z]/{if($0!~/^jobs:/)f=0} f&&/^  [a-zA-Z0-9_-]+:/{c++} END{print c+0}' "$JOBS_FILE")
+        _dok_ok "jobs file: $JOBS_FILE (${jc} job(s))"
+        local pf exp
+        while IFS= read -r pf; do
+            [ -z "$pf" ] && continue
+            exp="${pf/#\~/$HOME}"
+            [ -f "$exp" ] || _dok_warn "job password file not found: $pf"
+        done < <(grep -hoE 'password_file:[[:space:]]*"?[^"]+' "$JOBS_FILE" 2>/dev/null | sed -E 's/.*password_file:[[:space:]]*"?//')
+    else
+        _dok_note "no jobs file at $JOBS_FILE (optional)"
+    fi
+
+    # ---- Connections (only if a connection was supplied) ------------------
+    if [ -n "$FROM_CONNECTION" ] || [ "${#TO_CONNECTIONS[@]}" -gt 0 ]; then
+        _dok_head "Connections"
+        if [ -n "$FROM_CONNECTION" ]; then
+            if parse_connection "$FROM_CONNECTION" "FROM"; then
+                get_password "FROM"
+                if health_check "FROM" "Source" >/dev/null 2>&1; then _dok_ok "source reachable: $FROM_CONNECTION"
+                else _dok_fail "source NOT reachable: $FROM_CONNECTION"; fi
+            else _dok_fail "invalid source connection: $FROM_CONNECTION"; fi
+        fi
+        local i=0 conn
+        for conn in "${TO_CONNECTIONS[@]}"; do
+            if parse_connection "$conn" "TO"; then
+                get_password "TO" "$i"
+                if health_check "TO" "Target" >/dev/null 2>&1; then _dok_ok "target reachable: $conn"
+                else _dok_fail "target NOT reachable: $conn"; fi
+            else _dok_fail "invalid target connection: $conn"; fi
+            i=$((i+1))
+        done
+    fi
+
+    # ---- Summary ----------------------------------------------------------
+    echo
+    if [ "$DOCTOR_FAIL" -gt 0 ]; then
+        echo -e "${RED}\xE2\x9C\x97 ${DOCTOR_FAIL} problem(s), ${DOCTOR_WARN} warning(s)${NC}"
+        return 1
+    elif [ "$DOCTOR_WARN" -gt 0 ]; then
+        echo -e "${YELLOW}! ${DOCTOR_WARN} warning(s), no blocking problems${NC}"
+        return 0
+    else
+        echo -e "${GREEN}\xE2\x9C\x93 all checks passed${NC}"
+        return 0
+    fi
+}
 # ==============================================================================
 # BATCH SYSTEM
 # ==============================================================================
@@ -4910,6 +5378,12 @@ parse_args() {
         shift
     fi
 
+    # Handle explain subcommand optional positional topic (explain <topic>)
+    if [ "$COMMAND" = "explain" ] && [ $# -gt 0 ] && [[ "$1" != -* ]]; then
+        EXPLAIN_TARGET="$1"
+        shift
+    fi
+
     while [[ $# -gt 0 ]]; do
         case $1 in
             --from) FROM_CONNECTION="$2"; shift 2 || _need_val "$1" ;;
@@ -5139,6 +5613,8 @@ main() {
         list)    cmd_list ;;
         meta)    cmd_meta ;;
         clean)   cmd_clean ;;
+        doctor)  cmd_doctor ;;
+        explain) cmd_explain ;;
         jobs)
             case "$JOBS_ACTION" in
                 show)   show_job "$JOBS_TARGET" ;;

From b176170435e0a6a2acb0b79739bc1c975bac9993 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?As=C4=B1m=20Atasert?= <asimatasert@outlook.com>
Date: Thu, 16 Jul 2026 15:50:51 +0300
Subject: [PATCH 2/2] chore: bump version to 3.11.0, add changelog entry

---
 debian/changelog | 10 ++++++++++
 src/00-header.sh |  2 +-
 t-pgsql          |  2 +-
 3 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 2124229..4406265 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,13 @@
+t-pgsql (3.11.0-1) unstable; urgency=medium
+
+  * New commands:
+    - doctor: read-only environment & backup health checks (toolchain, disk,
+      per-database dump freshness, archive readability, jobs file, optional
+      connectivity) with a non-zero exit on problems
+    - explain: built-in offline reference for commands and workflows
+
+ -- Asim Atasert <asimatasert@outlook.com>  Wed, 16 Jul 2026 16:00:00 +0300
+
 t-pgsql (3.10.0-1) unstable; urgency=medium
 
   * New features for SSH dumps:
diff --git a/src/00-header.sh b/src/00-header.sh
index f2185c6..c5bab2c 100644
--- a/src/00-header.sh
+++ b/src/00-header.sh
@@ -21,7 +21,7 @@
 # ==============================================================================
 # VERSION & PATHS
 # ==============================================================================
-VERSION="3.10.0"
+VERSION="3.11.0"
 SCRIPT_NAME="t-pgsql"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
diff --git a/t-pgsql b/t-pgsql
index a90d79f..e087a4a 100755
--- a/t-pgsql
+++ b/t-pgsql
@@ -21,7 +21,7 @@
 # ==============================================================================
 # VERSION & PATHS
 # ==============================================================================
-VERSION="3.10.0"
+VERSION="3.11.0"
 SCRIPT_NAME="t-pgsql"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"