ai need to continue ...

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

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"

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"

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() {

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() {

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() {

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

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

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

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
 

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

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

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

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"
 

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

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() {