From fe751bbc0c995cb35eea4b92bcc389e71f0d8d57 Mon Sep 17 00:00:00 2001
From: Your Name <you@example.com>
Date: Wed, 5 Aug 2026 04:09:19 -0400
Subject: [PATCH] feat: add category help to pos dispatcher (pos <category>
 --help)

---
 DOC/AGENT_Context_Project.md |  2 +-
 DOC/DEV.md                   |  3 ++-
 DOC/POS.md                   |  2 +-
 bin/pos                      | 42 ++++++++++++++++++++++++++++++++++--
 completions/pos.bash         |  2 +-
 5 files changed, 45 insertions(+), 6 deletions(-)

diff --git a/DOC/AGENT_Context_Project.md b/DOC/AGENT_Context_Project.md
index 330e7d5..bb367eb 100644
--- a/DOC/AGENT_Context_Project.md
+++ b/DOC/AGENT_Context_Project.md
@@ -458,7 +458,7 @@ 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` | 153 | CLI dispatcher with smart arg matching + logging |
+| `bin/pos` | 191 | 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 |
diff --git a/DOC/DEV.md b/DOC/DEV.md
index 9dddb73..2fbf90e 100644
--- a/DOC/DEV.md
+++ b/DOC/DEV.md
@@ -49,7 +49,7 @@ pos docker compose up jellyfin
 
 All non-interactive commands log to `~/.local/share/linux_post_install/logs/`.
 
-`pos help <full command>` shows a tool's help, e.g. `pos help communication telegram` (all words joined with dashes → `pos-communication-telegram --help`).
+`pos help <full command>` shows a tool's help, e.g. `pos help communication telegram` (all words joined with dashes → `pos-communication-telegram --help`). `pos <category>` or `pos <category> --help` shows a category's subcommands (derived from the `pos-<category>-*` filenames in `bin/` — no script execution, so it works even for root-only/interactive tools like `system-firewall`).
 
 **When adding a command, `bin/pos` itself has two things to keep in sync:**
 
@@ -159,6 +159,7 @@ bash -n bin/your-tool
 shellcheck bin/your-tool
 ./bin/your-tool --help
 bin/pos help <full command>   # confirm dispatch works
+bin/pos <category> --help     # confirm category listing includes the new tool (first tool in a new category)
 ```
 
 ---
diff --git a/DOC/POS.md b/DOC/POS.md
index 9a39e7a..b74271e 100644
--- a/DOC/POS.md
+++ b/DOC/POS.md
@@ -30,7 +30,7 @@ tries pos-docker-compose-up            (not found)
 tries pos-docker-compose               (found) → runs with args "up jellyfin"
 ```
 
-`pos help <full command>` runs that tool's `--help` (e.g. `pos help communication telegram`, `pos help docker compose` — the words are joined with dashes). Running `pos` with no args prints the built-in usage text (which doubles as the category cheat-sheet).
+`pos help <full command>` runs that tool's `--help` (e.g. `pos help communication telegram`, `pos help docker compose` — the words are joined with dashes). `pos <category>` and `pos <category> --help` list that category's subcommands (derived from `bin/pos-<category>-*` filenames, no script execution). Running `pos` with no args prints the built-in usage text (which doubles as the category cheat-sheet).
 
 ---
 
diff --git a/bin/pos b/bin/pos
index fd08f18..ab3666e 100755
--- a/bin/pos
+++ b/bin/pos
@@ -25,6 +25,36 @@ _pos_commands() {
     echo "${cmds[*]}"
 }
 
+# ── Category helpers ────────────────────────────────────────────
+_pos_category_exists() {
+    local cat="${1:-}" f
+    [ -n "$cat" ] || return 1
+    for f in "$self"/pos-"$cat"-*; do
+        [ -x "$f" ] && return 0
+    done
+    return 1
+}
+
+_pos_category_help() {
+    local cat="$1" sub subs=()
+    local f
+    for f in "$self"/pos-"$cat"-*; do
+        [ -x "$f" ] || continue
+        subs+=("${f##*/pos-$cat-}")
+    done
+
+    echo "pos $cat — $cat tools"
+    echo
+    echo "USAGE"
+    echo "  pos $cat <command> [args]"
+    echo
+    echo "COMMANDS"
+    printf "  %s\n" "${subs[@]}"
+    echo
+    echo "Run 'pos $cat <command> --help' for details on a command."
+    exit 0
+}
+
 # ── Help text ──────────────────────────────────────────────────
 usage() {
     cat <<'EOF'
@@ -73,8 +103,9 @@ EXAMPLES
   pos docker vbox ls                       List Docker VMs
 
 HELP
-  pos help <command>    Show help for a command
-  pos --help            Show this help
+  pos <category> --help    Show a category's commands
+  pos help <command>       Show help for a command
+  pos --help               Show this help
 
 LEGACY WRAPPERS
   wr-ip, wr-checkport, wr-scan-ping, wr-docker,
@@ -108,6 +139,13 @@ fi
 args=("$@")
 n=${#args[@]}
 
+# ── Category help: pos <category> [--help] ─────────────────────
+if _pos_category_exists "${args[0]:-}"; then
+    if [ "$n" -eq 1 ] || { [ "$n" -eq 2 ] && { [ "${args[1]}" = "-h" ] || [ "${args[1]}" = "--help" ]; }; }; then
+        _pos_category_help "${args[0]}"
+    fi
+fi
+
 # ── Logging setup ──────────────────────────────────────────────
 LOG_DIR="$HOME/.local/share/linux_post_install/logs"
 mkdir -p "$LOG_DIR" 2>/dev/null || true
diff --git a/completions/pos.bash b/completions/pos.bash
index d9b6978..be600e6 100644
--- a/completions/pos.bash
+++ b/completions/pos.bash
@@ -45,7 +45,7 @@ _pos() {
 
     _pos_complete_subcats() {
         local cat="${words[1]}"
-        COMPREPLY=($(compgen -W "${cat_cmds[$cat]:-}" -- "$cur"))
+        COMPREPLY=($(compgen -W "${cat_cmds[$cat]:-} --help" -- "$cur"))
     }
 
     _pos_complete_compose_services() {