From e62626b55ce3ee9475032e6fecaf5d18174d4207 Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Wed, 5 Aug 2026 05:47:45 -0400
Subject: [PATCH] ai need to continue ...

---
 DOC/AGENT_Context_Project.md   |  87 +++++++++++---------
 bin/pos                        |  33 +++++---
 bin/pos-communication-telegram |   2 +
 bin/pos-docker-compose         |   1 +
 bin/pos-docker-health          |   1 +
 bin/pos-docker-ps              |   1 +
 bin/pos-docker-vbox            |   1 +
 bin/pos-media-mp3              |   1 +
 bin/pos-media-mp4              |   1 +
 bin/pos-network-checkport      |   1 +
 bin/pos-network-hotspot        |   2 +
 bin/pos-network-ip             |   1 +
 bin/pos-network-scan           |   1 +
 bin/pos-ssh-load-keys          |   1 +
 bin/pos-system-backup          |   2 +
 bin/pos-system-firewall        |   1 +
 bin/pos-usb-server             |   2 +
 completions/pos.bash           |  23 +++++-
 scripts/gen-docs.sh            | 143 +++++++++++++++++++++++++++++++++
 19 files changed, 254 insertions(+), 51 deletions(-)
 create mode 100755 scripts/gen-docs.sh

diff --git a/DOC/AGENT_Context_Project.md b/DOC/AGENT_Context_Project.md
index 29c82a0..b2ba545 100644
--- a/DOC/AGENT_Context_Project.md
+++ b/DOC/AGENT_Context_Project.md
@@ -34,21 +34,22 @@ Linux_post_install/
 │
 ├── bin/                    # CLI tools — installed to /usr/local/bin/
 │   ├── pos                 # Main dispatcher — smart arg matching to pos-* scripts
-│   ├── pos-network-ip      # Show interfaces, routes, public IP + location
-│   ├── pos-network-checkport  # TCP port checker
-│   ├── pos-network-scan    # Parallel ping sweep of CIDR subnet
-│   ├── pos-docker-ps       # Enhanced docker ps (health, IPs, ports, uptime)
-│   ├── pos-docker-health   # Quick one-glance health dashboard
-│   ├── pos-docker-compose  # Docker Compose service manager (largest script, 363 lines)
-│   ├── pos-media-mp3       # Audio downloader (yt-dlp → MP3)
-│   ├── pos-media-mp4       # Video downloader (yt-dlp → MP4, interactive format select)
-│   ├── pos-system-firewall # Interactive UFW manager (menu-driven, 284 lines)
-│   ├── pos-system-backup   # Encrypted folder snapshots (tar + gpg AES-256, --service) (115 lines)
-│   ├── pos-ssh-load-keys   # Load SSH keys into ssh-agent
-│   ├── pos-usb-server      # USB Redirector server control (usbsrv)
-│   ├── pos-communication-telegram  # Send Telegram messages via Bot API
-│   ├── pos-docker-vbox     # Disposable Docker-based "VMs" (pos docker vbox)
-│   ├── pos-network-hotspot # Wi-Fi hotspot (create_ap + wihotspot-gui)
+<!-- GEN:START tree -->
+│   ├── pos-docker-compose         # Docker Compose service manager (ls/up/down/restart/logs/update/config)
+│   ├── pos-docker-health          # One-glance container health dashboard (exits 1 if unhealthy)
+│   ├── pos-docker-ps              # Enhanced container overview (health, IPs, ports, uptime)
+│   ├── pos-docker-vbox            # Disposable Docker-based VMs (create/enter/start/stop/rm/ls)
+│   ├── pos-media-mp3              # Download audio as MP3 (yt-dlp)
+│   ├── pos-media-mp4              # Download video as MP4 (interactive format select)
+│   ├── pos-network-checkport      # Check TCP port connectivity
+│   ├── pos-network-hotspot        # Wi-Fi hotspot via create_ap + wihotspot-gui
+│   ├── pos-network-ip             # Show interfaces, routes, public IP + location
+│   ├── pos-network-scan           # Parallel ping sweep of CIDR
+│   ├── pos-ssh-load-keys          # Load all SSH keys into the agent
+│   ├── pos-system-backup          # Encrypted (AES-256) folder snapshots (tar + gpg)
+│   ├── pos-system-firewall        # Interactive UFW management
+│   ├── pos-usb-server             # USB Redirector server control (--ls, --share; prompts when args omitted)
+<!-- GEN:END tree -->
 │   ├── flag-reader         # Inspect feature flags (list/status/--raw)
 │   ├── flag-set            # Set a feature flag (optionally with a value)
 │   ├── flag-clear          # Unset a feature flag
@@ -197,20 +198,22 @@ All non-interactive `pos` commands log output to `~/.local/share/linux_post_inst
 
 | Category | Command | Script | Description |
 |----------|---------|--------|-------------|
-| network | ip | `pos-network-ip` | Show interfaces, routes, public IP + location |
+<!-- GEN:START dispatch -->
+| docker | compose | `pos-docker-compose` | Docker Compose service manager (ls/up/down/restart/logs/update/config) |
+| docker | health | `pos-docker-health` | One-glance container health dashboard (exits 1 if unhealthy) |
+| docker | ps | `pos-docker-ps` | Enhanced container overview (health, IPs, ports, uptime) |
+| docker | vbox | `pos-docker-vbox` | Disposable Docker-based VMs (create/enter/start/stop/rm/ls) |
+| media | mp3 | `pos-media-mp3` | Download audio as MP3 (yt-dlp) |
+| media | mp4 | `pos-media-mp4` | Download video as MP4 (interactive format select) |
 | network | checkport | `pos-network-checkport` | Check TCP port connectivity |
+| network | hotspot | `pos-network-hotspot` | Wi-Fi hotspot via create_ap + wihotspot-gui |
+| network | ip | `pos-network-ip` | Show interfaces, routes, public IP + location |
 | network | scan | `pos-network-scan` | Parallel ping sweep of CIDR |
-| docker | ps | `pos-docker-ps` | Enhanced container overview |
-| docker | health | `pos-docker-health` | Quick health dashboard (exits 1 if unhealthy) |
-| docker | compose | `pos-docker-compose` | Service manager (ls/up/down/restart/logs/update/config) |
-| media | mp3 | `pos-media-mp3` | Download audio as MP3 |
-| media | mp4 | `pos-media-mp4` | Download video with format select |
+| ssh | load-keys | `pos-ssh-load-keys` | Load all SSH keys into the agent |
+| system | backup | `pos-system-backup` | Encrypted (AES-256) folder snapshots (tar + gpg) |
 | system | firewall | `pos-system-firewall` | Interactive UFW management |
-| system | backup | `pos-system-backup` | Encrypted folder snapshots (`tar` + gpg AES-256; `--service` picks from `/srv` and `~/srv`) |
-| ssh | load-keys | `pos-ssh-load-keys` | Load SSH keys into agent |
-| usb | server | `pos-usb-server` | USB Redirector server control: `--ls`, `--share`, `--unshare`, `--auto-share`, `--callback`, `--disconnect`, `--nickname`, `--timeout`, `--port`, `--info`, `--version` (flag-style, prompts when args omitted) |
-| communication | telegram | `pos-communication-telegram` | Send Telegram messages via Bot API (`--send`, `test`, `config set`); config in `~/.config/linux_post_install/telegram.env` |
-| docker | vbox | `pos-docker-vbox` | Disposable Docker "VMs" (`create/enter/start/stop/rm/ls`; label-filtered, auto-enter prompt) |
+| usb | server | `pos-usb-server` | USB Redirector server control (--ls, --share; prompts when args omitted) |
+<!-- GEN:END dispatch -->
 
 ### Legacy Wrappers
 
@@ -252,7 +255,10 @@ Sourced by most scripts. Provides:
 source "$(dirname "$0")/../lib/common.sh"
 ```
 
-**Scripts that do NOT source common.sh** (self-contained): `bin/pos`, `pos-network-ip`, `pos-network-checkport`, `pos-network-scan`, `pos-network-hotspot`, `pos-media-mp3`, `pos-media-mp4`, `pos-ssh-load-keys`, `pos-system-firewall`, `pos-communication-telegram`.
+**Scripts that do NOT source common.sh** (self-contained):
+<!-- GEN:START selfcontained -->
+`bin/pos`, `pos-network-ip`, `pos-network-checkport`, `pos-network-scan`, `pos-network-hotspot`, `pos-media-mp3`, `pos-media-mp4`, `pos-ssh-load-keys`, `pos-system-firewall`, `pos-communication-telegram`.
+<!-- GEN:END selfcontained -->
 
 ---
 
@@ -460,17 +466,22 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/flag-set` | 21 | Set a flag (optionally with a value) |
 | `bin/flag-clear` | 21 | Unset a flag |
 | `features/autostart.sh` | 14 | Boot-time feature (moved from `bin/`, flag-gated service) |
-| `bin/pos` | 195 | CLI dispatcher with smart arg matching + logging + category help |
-| `bin/pos-docker-compose` | 363 | Largest script — full compose management |
-| `bin/pos-system-firewall` | 284 | Interactive UFW manager |
-| `bin/pos-system-backup` | 115 | Encrypted folder snapshots: path mode + `--service` (`/srv`, `~/srv` picker), tar + gpg AES-256 |
-| `bin/pos-docker-ps` | 127 | Enhanced container overview |
-| `bin/pos-docker-health` | 109 | Quick health dashboard |
-| `bin/pos-docker-vbox` | 156 | Docker-based disposable VMs (`pos docker vbox`; label-filtered, auto-enter prompt) |
-| `bin/pos-network-hotspot` | 91 | Wi-Fi hotspot: `create_ap` (start with background prompt/`--foreground`, stop, status) + `wihotspot-gui` |
-| `bin/pos-communication-telegram` | 138 | Telegram sender via Bot API: `--send`, `test`, `config set`; token masked; config `~/.config/linux_post_install/telegram.env` |
-| `bin/pos-usb-server` | 216 | USB Redirector server control (`usbsrv`): `--ls`, `--share` (interactive picker), `--unshare`, `--auto-share`, `--callback`, `--close-callback`, `--auto-connect`, `--disconnect`, `--nickname`, `--timeout`, `--port`, `--info`, `--version` |
-| `completions/pos.bash` | 129 | Dynamic bash completion |
+| `bin/pos-communication-telegram` | 140 | Send Telegram messages via Bot API (--send, test, config set) |
+| `bin/pos-docker-compose` | 364 | Docker Compose service manager (ls/up/down/restart/logs/update/config) |
+| `bin/pos-docker-health` | 110 | One-glance container health dashboard (exits 1 if unhealthy) |
+| `bin/pos-docker-ps` | 128 | Enhanced container overview (health, IPs, ports, uptime) |
+| `bin/pos-docker-vbox` | 157 | Disposable Docker-based VMs (create/enter/start/stop/rm/ls) |
+| `bin/pos-media-mp3` | 31 | Download audio as MP3 (yt-dlp) |
+| `bin/pos-media-mp4` | 34 | Download video as MP4 (interactive format select) |
+| `bin/pos-network-checkport` | 45 | Check TCP port connectivity |
+| `bin/pos-network-hotspot` | 93 | Wi-Fi hotspot via create_ap + wihotspot-gui |
+| `bin/pos-network-ip` | 69 | Show interfaces, routes, public IP + location |
+| `bin/pos-network-scan` | 271 | Parallel ping sweep of CIDR |
+| `bin/pos-ssh-load-keys` | 31 | Load all SSH keys into the agent |
+| `bin/pos-system-backup` | 117 | Encrypted (AES-256) folder snapshots (tar + gpg) |
+| `bin/pos-system-firewall` | 285 | Interactive UFW management |
+| `bin/pos-usb-server` | 218 | USB Redirector server control (--ls, --share; prompts when args omitted) |
+| `completions/pos.bash` | 146 | Dynamic bash completion |
 | `apps/install.sh` | 171 | App install/uninstall picker/orchestrator |
 
 ---
diff --git a/bin/pos b/bin/pos
index b44c95d..2eff6dd 100755
--- a/bin/pos
+++ b/bin/pos
@@ -25,6 +25,25 @@ _pos_commands() {
     echo "${cmds[*]}"
 }
 
+# ── Category list (sorted, filename-derived) ─────────────────────
+_pos_category_list() {
+    local -A cats=()
+    local cmd cat f
+    for f in "$self"/pos-*; do
+        [ -x "$f" ] || continue
+        cmd="${f##*/pos-}"
+        cat="${cmd%%-*}"
+        [ "$cat" = "$cmd" ] && continue
+        cats["$cat"]+="${cmd#*-} "
+    done
+    local c line subs joined
+    for c in $(printf '%s\n' "${!cats[@]}" | sort); do
+        subs=(${cats[$c]})
+        joined="$(IFS='|'; echo "${subs[*]}")"
+        printf "  %-14s%s\n" "$c" "$joined"
+    done
+}
+
 # ── Category helpers ────────────────────────────────────────────
 _pos_category_exists() {
     local cat="${1:-}" f
@@ -57,7 +76,9 @@ _pos_category_help() {
 
 # ── Help text ──────────────────────────────────────────────────
 usage() {
-    cat <<'EOF'
+    local cats
+    cats="$(_pos_category_list)"
+    cat <<EOF
 pos — Personal OS Toolkit
 
   A unified CLI for network, docker, media, system,
@@ -67,15 +88,7 @@ USAGE
   pos <category> <command> [args]
 
 CATEGORIES
-  network    ip | checkport | scan | hotspot
-  docker     ps | compose | health | vbox
-  media      mp3 | mp4
-  system     firewall | backup
-  ssh        load-keys
-  usb        server
-  communication
-             telegram
-
+$cats
 EXAMPLES
   pos network ip                          Show interfaces, routes, public IP
   pos network checkport 10.0.0.1:80       Check if a TCP port is open
diff --git a/bin/pos-communication-telegram b/bin/pos-communication-telegram
index a2b369e..4a2c62e 100755
--- a/bin/pos-communication-telegram
+++ b/bin/pos-communication-telegram
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: communication telegram — Send Telegram messages via Bot API (--send, test, config set)
+# POS_FLAGS: --send
 
 CONFIG_DIR="$HOME/.config/linux_post_install"
 CONFIG_FILE="$CONFIG_DIR/telegram.env"
diff --git a/bin/pos-docker-compose b/bin/pos-docker-compose
index a7f0cf3..3022496 100755
--- a/bin/pos-docker-compose
+++ b/bin/pos-docker-compose
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: docker compose — Docker Compose service manager (ls/up/down/restart/logs/update/config)
 source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
 
 SCALE_DIR="/usr/local/share/linux_post_install/scale-tail/services"
diff --git a/bin/pos-docker-health b/bin/pos-docker-health
index 82658a3..e0596ee 100755
--- a/bin/pos-docker-health
+++ b/bin/pos-docker-health
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: docker health — One-glance container health dashboard (exits 1 if unhealthy)
 source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
 
 usage() {
diff --git a/bin/pos-docker-ps b/bin/pos-docker-ps
index 320f4f7..5519369 100755
--- a/bin/pos-docker-ps
+++ b/bin/pos-docker-ps
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: docker ps — Enhanced container overview (health, IPs, ports, uptime)
 source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
 
 usage() {
diff --git a/bin/pos-docker-vbox b/bin/pos-docker-vbox
index 33c711b..145681d 100755
--- a/bin/pos-docker-vbox
+++ b/bin/pos-docker-vbox
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: docker vbox — Disposable Docker-based VMs (create/enter/start/stop/rm/ls)
 source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
 
 usage() {
diff --git a/bin/pos-media-mp3 b/bin/pos-media-mp3
index 8a9de83..e3a6b7d 100755
--- a/bin/pos-media-mp3
+++ b/bin/pos-media-mp3
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: media mp3 — Download audio as MP3 (yt-dlp)
 
 usage() {
     cat <<EOF
diff --git a/bin/pos-media-mp4 b/bin/pos-media-mp4
index 8ce842f..295864e 100755
--- a/bin/pos-media-mp4
+++ b/bin/pos-media-mp4
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: media mp4 — Download video as MP4 (interactive format select)
 
 usage() {
     cat <<EOF
diff --git a/bin/pos-network-checkport b/bin/pos-network-checkport
index d437b00..2e77b7d 100755
--- a/bin/pos-network-checkport
+++ b/bin/pos-network-checkport
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: network checkport — Check TCP port connectivity
 
 usage() {
     cat <<EOF
diff --git a/bin/pos-network-hotspot b/bin/pos-network-hotspot
index 0d26aae..8b8a3a2 100755
--- a/bin/pos-network-hotspot
+++ b/bin/pos-network-hotspot
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: network hotspot — Wi-Fi hotspot via create_ap + wihotspot-gui
+# POS_FLAGS: --foreground
 
 LOGFILE=/var/log/linux_post_install_hotspot.log
 
diff --git a/bin/pos-network-ip b/bin/pos-network-ip
index 90774ea..1c01fed 100755
--- a/bin/pos-network-ip
+++ b/bin/pos-network-ip
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: network ip — Show interfaces, routes, public IP + location
 
 usage() {
     cat <<EOF
diff --git a/bin/pos-network-scan b/bin/pos-network-scan
index a9fb3ce..a210881 100755
--- a/bin/pos-network-scan
+++ b/bin/pos-network-scan
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: network scan — Parallel ping sweep of CIDR
 
 usage() {
     cat <<EOF
diff --git a/bin/pos-ssh-load-keys b/bin/pos-ssh-load-keys
index b301da6..82c247e 100755
--- a/bin/pos-ssh-load-keys
+++ b/bin/pos-ssh-load-keys
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: ssh load-keys — Load all SSH keys into the agent
 
 usage() {
     cat <<EOF
diff --git a/bin/pos-system-backup b/bin/pos-system-backup
index 94f9bbf..e60cfc3 100755
--- a/bin/pos-system-backup
+++ b/bin/pos-system-backup
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: system backup — Encrypted (AES-256) folder snapshots (tar + gpg)
+# POS_FLAGS: --service
 
 source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
 
diff --git a/bin/pos-system-firewall b/bin/pos-system-firewall
index 92c095d..4215a7e 100755
--- a/bin/pos-system-firewall
+++ b/bin/pos-system-firewall
@@ -1,5 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: system firewall — Interactive UFW management
 IFS=$'\n\t'
 
 if [[ $EUID -ne 0 ]]; then
diff --git a/bin/pos-usb-server b/bin/pos-usb-server
index 627559a..b237db9 100755
--- a/bin/pos-usb-server
+++ b/bin/pos-usb-server
@@ -1,5 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
+# POS: usb server — USB Redirector server control (--ls, --share; prompts when args omitted)
+# POS_FLAGS: --ls --ls-shared --share --unshare --auto-share --callback --close-callback --auto-connect --disconnect --nickname --timeout --port --info --version
 source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
 
 usage() {
diff --git a/completions/pos.bash b/completions/pos.bash
index 66ba576..8b9cfde 100644
--- a/completions/pos.bash
+++ b/completions/pos.bash
@@ -1,6 +1,13 @@
 #!/usr/bin/env bash
 # Bash completion for pos — dynamically discovers pos-* subcommands
 # Install: source this file in ~/.bashrc or place in /etc/bash_completion.d/
+# GEN:START posflags
+declare -A _pos_flags
+_pos_flags[communication-telegram]="--send"
+_pos_flags[network-hotspot]="--foreground"
+_pos_flags[system-backup]="--service"
+_pos_flags[usb-server]="--ls --ls-shared --share --unshare --auto-share --callback --close-callback --auto-connect --disconnect --nickname --timeout --port --info --version"
+# GEN:END posflags
 
 _pos() {
     local cur prev words cword
@@ -73,8 +80,9 @@ _pos() {
         COMPREPLY=($(compgen -W "$names" -- "$cur"))
     }
 
-    _pos_complete_usb_server_flags() {
-        COMPREPLY=($(compgen -W "--ls --ls-shared --share --unshare --auto-share --callback --close-callback --auto-connect --disconnect --nickname --timeout --port --info --version --help" -- "$cur"))
+    _pos_complete_flags() {
+        local tool="$1"
+        COMPREPLY=($(compgen -W "${_pos_flags[$tool]:-} --help" -- "$cur"))
     }
 
     # ── Dispatch ───────────────────────────────────────────────
@@ -101,7 +109,16 @@ _pos() {
                     _pos_complete_docker_vbox_cmds
                     ;;
                 usb-server)
-                    _pos_complete_usb_server_flags
+                    _pos_complete_flags usb-server
+                    ;;
+                communication-telegram)
+                    _pos_complete_flags communication-telegram
+                    ;;
+                network-hotspot)
+                    _pos_complete_flags network-hotspot
+                    ;;
+                system-backup)
+                    _pos_complete_flags system-backup
                     ;;
             esac
             ;;
diff --git a/scripts/gen-docs.sh b/scripts/gen-docs.sh
new file mode 100755
index 0000000..a051fd9
--- /dev/null
+++ b/scripts/gen-docs.sh
@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# Regenerate code-derived doc sections between GEN markers.
+#
+#   scripts/gen-docs.sh          rewrite files in place
+#   scripts/gen-docs.sh --check  verify only; exit 1 on any drift
+#
+# Sources of truth:
+#   - bin/pos-* filenames  → category, subcommand
+#   - "# POS:" header line → one-line description
+#   - "# POS_FLAGS:" line  → flag completion list (flag-style tools only)
+
+root="$(cd "$(dirname "$0")/.." && pwd)"
+mode="write"
+[ "${1:-}" = "--check" ] && mode="check"
+
+ctx="$root/DOC/AGENT_Context_Project.md"
+comp="$root/completions/pos.bash"
+
+# ── Collect tools: "cat|sub|desc|flags" ────────────────────────
+tools=()
+for f in "$root"/bin/pos-*; do
+    [ -x "$f" ] || continue
+    name="${f##*/pos-}"
+    cat="${name%%-*}"
+    sub="${name#*-}"
+    desc="$(sed -n '/^# POS: /{s/^# POS: //;p;q}' "$f")"
+    [ -n "$desc" ] || { echo "gen-docs: no '# POS:' header in $f" >&2; exit 1; }
+    desc="${desc#*— }"
+    flags="$(sed -n '/^# POS_FLAGS: /{s/^# POS_FLAGS: //;p;q}' "$f")"
+    tools+=("$cat|$sub|$desc|$flags")
+done
+mapfile -t tools < <(printf '%s\n' "${tools[@]}" | sort)
+
+# ── Block generators (emit inner content only, no markers) ──────
+gen_tree() {
+    local width=0 cat sub desc flags name t
+    for t in "${tools[@]}"; do
+        IFS='|' read -r cat sub desc flags <<<"$t"
+        name="pos-$cat-$sub"
+        [ ${#name} -gt "$width" ] && width=${#name}
+    done
+    for t in "${tools[@]}"; do
+        IFS='|' read -r cat sub desc flags <<<"$t"
+        name="pos-$cat-$sub"
+        printf '│   ├── %-*s# %s\n' "$((width + 1))" "$name" "$desc"
+    done
+}
+
+gen_dispatch() {
+    local cat sub desc flags t
+    for t in "${tools[@]}"; do
+        IFS='|' read -r cat sub desc flags <<<"$t"
+        printf '| %s | %s | `pos-%s-%s` | %s |\n' "$cat" "$sub" "$cat" "$sub" "$desc"
+    done
+}
+
+gen_selfcontained() {
+    local list=() f base out=""
+    for f in "$root"/bin/pos "$root"/bin/pos-*; do
+        [ -x "$f" ] || continue
+        base="$(basename "$f")"
+        grep -q 'common\.sh' "$f" || list+=("$base")
+    done
+    for b in "${list[@]}"; do
+        out+="\`$b\`, "
+    done
+    echo "${out%, }."
+}
+
+gen_filetable() {
+    local cat sub desc flags name t
+    printf '| `bin/pos` | %s | CLI dispatcher with smart arg matching + logging + category help |\n' "$(wc -l < "$root/bin/pos")"
+    for t in "${tools[@]}"; do
+        IFS='|' read -r cat sub desc flags <<<"$t"
+        name="bin/pos-$cat-$sub"
+        printf '| `%s` | %s | %s |\n' "$name" "$(wc -l < "$root/$name")" "$desc"
+    done
+    printf '| `completions/pos.bash` | %s | Dynamic bash completion |\n' "$(wc -l < "$comp")"
+}
+
+gen_posflags() {
+    local cat sub desc flags t
+    echo "declare -A _pos_flags"
+    for t in "${tools[@]}"; do
+        IFS='|' read -r cat sub desc flags <<<"$t"
+        [ -n "$flags" ] || continue
+        printf '_pos_flags[%s-%s]="%s"\n' "$cat" "$sub" "$flags"
+    done
+}
+
+# ── Replace (write) or verify (check) one marker block ──────────
+markers() {
+    # bash files use '#' comment markers, markdown uses HTML comments
+    case "$1" in
+        *.bash|*.sh) echo "# GEN:START $2" "# GEN:END $2" ;;
+        *)           echo "<!-- GEN:START $2 -->" "<!-- GEN:END $2 -->" ;;
+    esac
+}
+
+regen_block() {
+    local file="$1" name="$2"
+    local start end newfile tmp
+    read -r start end <<<"$(markers "$file" "$name")"
+    newfile="$(mktemp)"
+    "gen_$name" > "$newfile"
+
+    grep -qF "$start" "$file" || { echo "gen-docs: missing marker '$start' in $file" >&2; rm -f "$newfile"; exit 1; }
+
+    if [ "$mode" = "check" ]; then
+        local cur
+        cur="$(sed -n "/^$start$/,/^$end$/p" "$file" | sed '1d;$d')"
+        if [ "$cur" != "$(cat "$newfile")" ]; then
+            echo "gen-docs: DRIFT in $file ($name block)" >&2
+            diff <(printf '%s\n' "$cur") <(cat "$newfile") >&2 || true
+            rm -f "$newfile"
+            exit 1
+        fi
+    else
+        tmp="$(mktemp)"
+        awk -v start="$start" -v end="$end" -v nf="$newfile" '
+            $0==start {
+                print
+                while ((getline line < nf) > 0) print line
+                skip=1
+                next
+            }
+            skip && $0==end { skip=0; print; next }
+            skip { next }
+            { print }
+        ' "$file" > "$tmp"
+        mv "$tmp" "$file"
+    fi
+    rm -f "$newfile"
+}
+
+regen_block "$ctx" tree
+regen_block "$ctx" dispatch
+regen_block "$ctx" selfcontained
+regen_block "$ctx" filetable
+regen_block "$comp" posflags
+
+echo "gen-docs: $mode OK"