chore: note pos bank multiline fix in AGENT_TODO Done

fix: store and execute multiline commands in pos bank
bank.env is line-oriented (name|description|command) so commands with real newlines spanned records: bank_load truncated the command to its first line and the remaining script lines became bogus entries. The bank_get+cut -f3 retrieval path also truncated at embedded tabs. - lib/bank-lib.sh: v2 format escapes backslash->\\ and newline->\\n in the command field, writes # BANK_VERSION: 2; bank_load decodes with printf %b only for v2 files, so existing v1 files load raw (backward compatible, verified against the real ts-google entry). - bin/pos-bank: cmd_show/cmd_run/cmd_edit now read fields from the BANK_* arrays via bank_find instead of bank_get+cut. - tests/t-bank.sh: +13 checks (71 total) - multiline round-trip exact bytes, literal backslash-n, v1 raw-backslash compat, v1+re-save byte-identical, CLI show/run full script.
2026-09-12 08:27:12 -04:00 · 2026-09-12 08:25:40 -04:00 · 2026-09-12 07:29:30 -04:00 · 2026-09-12 05:20:20 -04:00 · 2026-09-12 03:28:15 -04:00 · 2026-09-12 03:02:20 -04:00
19 changed files with 1725 additions and 29 deletions
@@ -33,3 +33,6 @@ dream.md

 # Agent process reports — local-only shared memory (not tracked)
 AgentsReport/
+
+# Task breakdown notes — never committed
+.tasks/
@@ -42,6 +42,10 @@ summary (newest last).

 ## Done

+- **`pos bank` command bank** — feature (41efc91) + lib registration fix (73d15a2) + main-menu visibility & `run` crash fix (c5d501a) + tab-completion of category-less tools (e23d57e) + multiline command storage/execution fix (11b4a67, v2 escaped format with backward compat). Done 2026-09-12.
+
+- **2026-09-09** — New `pos system alias` tool (Architect→Builder→Reviewer→Writer): persistent command aliases via wrapper scripts in `~/.local/bin/`. Interactive menu (create/edit/remove/list/show), storage at `~/.config/linux_post_install/aliases.env` (pipe-delimited `name|command`), wrapper sync on every invocation, name validation (`^[a-zA-Z][a-zA-Z0-9_-]*$`), ownership markers, collision checks. Docs: POS.md system category + detail block, howto/system.md recipes section. Verified: `bash -n`, `make gen` byte-idempotent, `make check` OK, `make lint` 0 FAIL / 0 WARN.
+
 - **2026-09-09** — Telegram listener single-instance guard (Toolsmith): `bin/pos-communication-telegram-listener --run` now takes a `flock(1)` on `${XDG_RUNTIME_DIR:-/tmp}/pos-telegram-listener.lock` inside `run_daemon()` (before config load/sync/poll loop) — a second `--run` on the same token fails fast (exit 1, `ERROR: listener already running (single instance) — check: systemctl --user status pos-telegram-listener`), never racing getUpdates (Telegram 409/command stealing). Kernel auto-release → no stale-lock bookkeeping, systemd `Restart=always` restarts clean. `--status` first line now reports `listener:  running (single instance lock held)` / `listener:  not running` via the same `lock_held()` probe. `flock` dep guard added (`util-linux`). New regression `tests/t-telegram-listener-singleton.sh` (7 checks: first acquires+loops, second exits 1 with exact message, lock releases → third starts clean, status reports both states; stubbed curl/systemctl, sandboxed XDG_RUNTIME_DIR — hermetic, no network). Verified: `bash -n`, `make gen` ×2 byte-idempotent, `make check` OK, `make lint` 0 FAIL / 0 WARN, `make test` green, `git diff --check` clean.

 - **2026-09-09** — Unified YouTube tools into `pos media yt` + new `subtitles` (Architect POS--9). New `bin/pos-media-yt` dispatcher (mp3/mp4/grab/ytsync/subtitles) + `bin/pos-media-yt-{mp3,mp4,grab,subtitles,ytsync}`; the ytsync file is a forwarder to the existing `pos media ytsync`; legacy `bin/pos-media-{mp3,mp4,grab}` became thin forwarders to the `yt` forms. New `lib/yt-lib.sh` (deps/URL-validation/echo/classify helpers; `classify_url` migrated from grab, `yt_validate_url` is a return-1 checker — never exits, so callers can prefix errors). `bin/pos` INTERACTIVE_CMDS += `media-yt-mp4` (interactive format pick reads stdin). `pos-media-yt-subtitles` extracts captions via `--write-subs --write-auto-subs --sub-langs best`, `--lang en,ar` (one `--sub-langs` arg), `srt|vtt|txt` (txt = srt→txt conversion stripping timestamps/HTML), `--auto-only`, `--list-subs` probe, `--output`, no-ffmpeg dep (yt-dlp only; dry-run skips deps entirely). Docs: DOC/POS.md media section rewritten (yt group + forwarder rows), DOC/howto/media.md `yt` commands + subtitles section, AGENT_Context hand-maintained `lib/yt-lib.sh` row, tests/README row. New `tests/t-pos-media-yt.sh` (72 checks: dispatcher/forwarder resolution, full `pos media mp3` dispatch chain, yt-lib helpers, per-tool flags/dry-run/`YT_OUT_DIR` seam/`GRAB_DEFAULT` config, 3 mandated negative controls — unsafe-URL no-expansion, `--lang en,ar` single arg, txt timestamp-stripping, unavailable-subs detection). `tests/t-config-precedence.sh` Part D config-consumer list updated `pos-media-grab` → `pos-media-yt-grab`. Verified: `bash -n` all; `make gen` ×2 byte-idempotent; `make check` OK; `make lint` 0 FAIL / 0 WARN; `make test` 21 files / 533 checks / 0 fail / 0 skip; `git diff --check` clean; smokes — `pos media yt --help`, `yt mp3/mp4/subtitles --help`, `yt ytsync --help` (reaches `pos media ytsync`), `pos media mp3 --help` forwarder, `pos tree` shows the `yt` subtree (with repo-first PATH; system `/usr/local/bin` has a stale pre-POS--9 install that shadows it otherwise).
@@ -10,19 +10,19 @@

 <!-- GEN:START docmap -->
 | ## 1. Project Overview | 28–43 |
-| ## 2. Directory Structure | 44–216 |
-| ## 3. Installation Flow | 217–275 |
-| ## 4. The `pos` CLI System | 276–363 |
-| ## 5. Shared Library — `lib/common.sh` | 364–395 |
-| ## 6. Docker Compose / ScaleTail | 396–438 |
-| ## 7. Optional Apps (`apps/`) | 439–468 |
-| ## 8. Entertainment Module | 469–482 |
-| ## 9. Systemd Services | 483–494 |
-| ## 10. Configuration Files | 495–521 |
-| ## 11. Coding Conventions | 522–554 |
-| ## 12. Development Workflow | 555–607 |
-| ## 13. Key File Quick Reference | 608–690 |
-| ## 14. Common Tasks for Agents | 691–724 |
+| ## 2. Directory Structure | 44–218 |
+| ## 3. Installation Flow | 219–277 |
+| ## 4. The `pos` CLI System | 278–367 |
+| ## 5. Shared Library — `lib/common.sh` | 368–399 |
+| ## 6. Docker Compose / ScaleTail | 400–442 |
+| ## 7. Optional Apps (`apps/`) | 443–472 |
+| ## 8. Entertainment Module | 473–486 |
+| ## 9. Systemd Services | 487–498 |
+| ## 10. Configuration Files | 499–525 |
+| ## 11. Coding Conventions | 526–558 |
+| ## 12. Development Workflow | 559–611 |
+| ## 13. Key File Quick Reference | 612–697 |
+| ## 14. Common Tasks for Agents | 698–731 |
 <!-- GEN:END docmap -->

 ## 1. Project Overview
@@ -109,6 +109,7 @@ Linux_post_install/
 │   ├── pos-share-smb-server                # Manage the Samba server (status, share/unshare exports, users, enable/disable)
 │   ├── pos-share-usb-server                # USB Redirector server control (--ls, --share; prompts when args omitted)
 │   ├── pos-ssh-load-keys                   # Load all SSH keys into the agent
+│   ├── pos-system-alias                    # Manage persistent command aliases (wrapper scripts in ~/.local/bin/)
 │   ├── pos-system-backup                   # Encrypted (AES-256) folder snapshots (tar + gpg)
 │   │   [deps: tar]
 │   ├── pos-system-firewall                 # Interactive UFW management
@@ -116,6 +117,7 @@ Linux_post_install/
 │   ├── pos-system-schedule                 # Scheduled jobs: run a command on a timer; notify on threshold/change/error/always or silently
 │   ├── pos-system-uninstall                # Remove pos toolkit binaries, services, shell integration, config, and data
 │   ├── pos-ai                              # AI assistant: ask, chat, sessions, capture, models, providers
+│   ├── pos-bank                            # Persistent command bank for saving and running shell commands
 │   ├── pos-config                          # Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry)
 │   ├── pos-tree                            # Show the pos CLI command tree: categories, commands, and subcommands
 <!-- GEN:END tree -->
@@ -230,7 +232,7 @@ User runs: ./install.sh [--apps|--full|--feature|--dry-run|--force|--skip <phase
 │   └─ Copies bin/* → /usr/local/bin/ (chmod 755)
 │   └─ Copies lib/*.sh (common, flags, notify, registry, entertainment-lib,
 │      scheduler-lib, config-ui, user-timers-lib, entertainment-plugin-lib,
-│      usb-lib, share-lib, menu-lib) → /usr/local/bin/ (chmod 644)
+│      usb-lib, share-lib, menu-lib, yt-lib, bank-lib) → /usr/local/bin/ (chmod 644)
 │   └─ Copies x64_bin/* → /usr/local/bin/ on x86_64 (arm64_bin/ on aarch64)
 │   └─ [if --feature] Copies features/* → /usr/local/bin/ (asks before overwriting),
 │                      then sets the matching feature flag
@@ -335,12 +337,14 @@ All non-interactive `pos` commands log output to `~/.local/share/linux_post_inst
 | share | smb-server | `pos-share-smb-server` | Manage the Samba server (status, share/unshare exports, users, enable/disable) |  |  |
 | share | usb-server | `pos-share-usb-server` | USB Redirector server control (--ls, --share; prompts when args omitted) |  |  |
 | ssh | load-keys | `pos-ssh-load-keys` | Load all SSH keys into the agent |  |  |
+| system | alias | `pos-system-alias` | Manage persistent command aliases (wrapper scripts in ~/.local/bin/) |  |  |
 | system | backup | `pos-system-backup` | Encrypted (AES-256) folder snapshots (tar + gpg) | tar |  |
 | system | firewall | `pos-system-firewall` | Interactive UFW management |  |  |
 | system | health | `pos-system-health` | Host health dashboard (disk, RAM, services, backup age, fail2ban, docker); exit 1 if any FAIL |  |  |
 | system | schedule | `pos-system-schedule` | Scheduled jobs: run a command on a timer; notify on threshold/change/error/always or silently |  |  |
 | system | uninstall | `pos-system-uninstall` | Remove pos toolkit binaries, services, shell integration, config, and data |  |  |
 |  | ai | `pos-ai` | AI assistant: ask, chat, sessions, capture, models, providers |  |  |
+|  | bank | `pos-bank` | Persistent command bank for saving and running shell commands |  |  |
 |  | config | `pos-config` | Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry) |  |  |
 |  | tree | `pos-tree` | Show the pos CLI command tree: categories, commands, and subcommands |  |  |
 <!-- GEN:END dispatch -->
@@ -624,13 +628,14 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `lib/menu-lib.sh` | 362 | Category-neutral interactive menu primitives (`menu_guard` tty guard, `menu_run` looping boxed menu, `menu_pick` type-to-filter picker, `menu_ask_value` prompt-with-default via raw-mode bracketed-paste-safe `menu_read_value`; stderr render, fail-closed on non-tty/EOF) — sourced by `share-lib.sh`, open to any category |
 | `lib/registry.sh` | 199 | Shared query API for POS tool metadata headers (`# POS_*:`) — `reg_scan`/`reg_list`/`reg_lookup`/`reg_each`/config scope helpers; used by `pos-tree` and `gen-docs.sh` |
 | `lib/yt-lib.sh` | 50 | Shared YouTube helpers for `pos media yt *` (`yt_check_deps`, `yt_validate_url`, `yt_echo_cmd`, `classify_url`) — sourced by `yt-mp3`/`yt-mp4`/`yt-grab`/`yt-subtitles` |
+| `lib/bank-lib.sh` | 183 | Shared Command Bank storage helpers for `pos bank` (`bank_load`/`bank_save`/`bank_add`/`bank_remove`/`bank_update`, `{param}` template substitution, v2 `\n`-escaped multiline storage with backward-compat raw load; store `~/.config/linux_post_install/bank.env`) — sourced by `pos-bank` |
 | `bin/flag-reader` | 58 | Inspect flags (list/status/`--raw`) |
 | `bin/flag-set` | 21 | Set a flag (optionally with a value) |
 | `bin/flag-clear` | 21 | Unset a flag |
 | `features/autostart.sh` | 50 | Boot-time feature (moved from `bin/`, flag-gated service) |
 | `features/usb-automount.sh` | 138 | USB automount feature (udev rule + flag-gated service) |
 <!-- GEN:START filetable -->
-| `bin/pos` | 302 | CLI dispatcher with smart arg matching + logging + category help |
+| `bin/pos` | 310 | CLI dispatcher with smart arg matching + logging + category help |
 | `bin/pos-ai-alias` | 760 | manage AI agent aliases |
 | `bin/pos-ai-gemini` | 7 | Forward to pos ai --provider gemini (backward compat) |
 | `bin/pos-ai-hf` | 993 | Download AI models from Hugging Face (search, download, manage) |
@@ -674,15 +679,17 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-share-smb-server` | 441 | Manage the Samba server (status, share/unshare exports, users, enable/disable) |
 | `bin/pos-share-usb-server` | 362 | USB Redirector server control (--ls, --share; prompts when args omitted) |
 | `bin/pos-ssh-load-keys` | 31 | Load all SSH keys into the agent |
+| `bin/pos-system-alias` | 488 | Manage persistent command aliases (wrapper scripts in ~/.local/bin/) |
 | `bin/pos-system-backup` | 301 | Encrypted (AES-256) folder snapshots (tar + gpg) |
 | `bin/pos-system-firewall` | 325 | Interactive UFW management |
 | `bin/pos-system-health` | 209 | Host health dashboard (disk, RAM, services, backup age, fail2ban, docker); exit 1 if any FAIL |
 | `bin/pos-system-schedule` | 151 | Scheduled jobs: run a command on a timer; notify on threshold/change/error/always or silently |
-| `bin/pos-system-uninstall` | 517 | Remove pos toolkit binaries, services, shell integration, config, and data |
+| `bin/pos-system-uninstall` | 518 | Remove pos toolkit binaries, services, shell integration, config, and data |
 | `bin/pos-ai` | 714 | AI assistant: ask, chat, sessions, capture, models, providers |
+| `bin/pos-bank` | 311 | Persistent command bank for saving and running shell commands |
 | `bin/pos-config` | 80 | Interactive editor for the tools' runtime config (reads # POS_CONFIG: registry) |
 | `bin/pos-tree` | 118 | Show the pos CLI command tree: categories, commands, and subcommands |
-| `completions/pos.bash` | 316 | Dynamic bash completion |
+| `completions/pos.bash` | 331 | Dynamic bash completion |
 <!-- GEN:END filetable -->
 | `apps/install.sh` | 171 | App install/uninstall picker/orchestrator |

@@ -296,9 +296,23 @@ reported as "N videos require sign-in — skipped" (escape hatch:
 | `pos system health` | `bin/pos-system-health` | Host health dashboard: disk per mount, RAM/swap, failed systemd units, backup age, fail2ban, docker containers. Exits 1 if any check FAILs | Console-only reporter — health itself never sends notifications; forward the output with a wrapper (e.g. the Telegram/Matrix listener map `/status=pos system health`) or schedule it via `pos system schedule` with a `NOTIFY` policy. `HEALTH_BACKUP_MAX_AGE_DAYS` (default 2) and `BACKUP_SERVICE_ROOTS` come from `~/.config/linux_post_install/system.env`; `--help` shows the effective values |
 | `pos system schedule <cmd>` | `bin/pos-system-schedule` | Scheduled jobs — run a command on a timer, notify (or stay silent): `run [name\|all]`, `list`, `config`, `enable [name\|all]`, `disable [name\|all]`, `status`, `migrate`. Each job is a file in `~/.config/linux_post_install/schedule.d/<name>.env` with `INTERVAL` (`5m…59m`, `1h…23h`, `hourly`, `daily`, `weekly`, `OnCalendar=…`), `NOTIFY` policy, optional `MSG`, `RULE` (threshold only), and `COMMAND` = the literal rest of the line (pipes/quotes/`sudo` fine). Policies: `always` (full output every run), `onchange` (send when output differs from the last run; first run always sends), `onerror` (non-zero exit or empty output), `threshold` (first numeric output vs `RULE`, alert on false→true + one recovery — the old event-trigger behavior), `never` (side-effect jobs, no notify) | One systemd **user** timer pair per job (`pos-schedule-<name>.timer` + oneshot `.service`, `Persistent=true`), reconciled on `enable`/`disable`; the legacy single `pos-event-trigger` timer is auto-removed. `migrate` converts a pre-existing `event.env` rule set into `schedule.d/rule-N.env` threshold jobs. `config` is an interactive editor (add/edit/remove/enable/disable, validates interval + threshold); alerts via `lib/notify.sh`; `--dry-run` previews runs/writes/sends; jobs are arbitrary shell commands (chmod 600, same trust model as the Telegram map); starter jobs in `config/schedule.d/` auto-installed no-clobber by postinstall. Bare invocation on a terminal (or the `menu` subcommand) opens an interactive hub over these verbs (list, timer status, run-now, enable, disable, config editor) — a menu run-now asks y/N first and goes through the same `run <name>` path the systemd timers use |
 | `pos system uninstall` | `bin/pos-system-uninstall` | Safe, interactive uninstaller for the pos toolkit — scans and removes binaries, services, shell integration, config, and data in three tiers | Tier 1 (always): binaries in `/usr/local/bin/` (pos, pos-*, libs, ai-providers, entertainment plugins, prebuilt, features), systemd services (disable+remove) including runtime-created `~/.config/systemd/user/pos-*` user units, ScaleTail templates + feature-flag store under `/usr/local/share/linux_post_install/`, shell integration in `~/.bashrc` (PATH, completion, pos-ai-hook source), completion file. Tier 2 (`--config`): `~/.config/linux_post_install/` (.env files, schedule.d/, authorized_keys, rclone.conf). Tier 3 (`--data`): `~/.local/share/linux_post_install/` (ai sessions, logs, captured output). Flags: `--yes` (skip prompts, tier 1 only), `--config` (include tier 2), `--data` (include tier 3). Combine all three for nuclear removal. Git repo is never removed |
+| `pos system alias` | `bin/pos-system-alias` | Manage persistent command aliases — create, edit, remove, list, and show named aliases that map names to shell commands via executable wrapper scripts in `~/.local/bin/` | Aliases stored in `~/.config/linux_post_install/aliases.env` (pipe-delimited: `name\|command`). Each alias materializes as a wrapper script at `~/.local/bin/<name>` (chmod 755) that runs the mapped command with any arguments forwarded. Wrapper scripts are synced automatically on every invocation; changes are live immediately. Name validation: must start with a letter, then letters/digits/hyphens/underscores. Refuses name collisions with existing files on `~/.local/bin/` (unless pos-owned) and existing binaries on `PATH`. Requires `~/.local/bin` on `PATH` — a warning with a copy-paste fix appears when it isn't |

 A scheduled job is the recommended way to run the health dashboard on a timer: a `daily` job with `COMMAND=pos system health` and `NOTIFY=always` sends the dashboard output as the alert — no separate systemd unit needed (the old `pos-health.{service,timer}` units are gone; a legacy install may still have them failed/leftover — disable and remove them).

+`pos system alias` in detail:
+
+| Command | Behavior |
+|---------|----------|
+| `pos system alias` | Interactive menu: create / edit / remove / list aliases; shows the current alias table between picks |
+| `pos system alias create [name]` | Interactive 2-step wizard: alias name (must start with a letter, then letters/digits/-/_; unique — collisions with existing files on `~/.local/bin/` or binaries on `PATH` are refused), command (must not contain `\|`); confirms before saving |
+| `pos system alias edit [name]` | Edits an existing alias (pick from list or pass the name); shows current values, prompts for the new command (Enter keeps current); saves only if changed |
+| `pos system alias remove [name]` | Removes an alias (pick from list or pass the name); confirmation defaults to **no** — removal deletes the wrapper script and cannot be undone |
+| `pos system alias list` | Non-interactive: prints all aliases as a Name/Command table (commands truncated at 60 chars) |
+| `pos system alias show <name>` | Prints one alias's details: name, command, wrapper path, and how to test it |
+
+Alias storage & activation: records live in `~/.config/linux_post_install/aliases.env` — one `name\|command` line per alias, chmod 600, managed by the tool (do not hand-edit). **Activation needs no shell sourcing**: every `pos system alias` invocation syncs the ENV file against executable wrapper scripts at `~/.local/bin/<name>` (chmod 755) — missing or changed wrappers are atomically rewritten, wrappers pos owns but the ENV no longer lists are deleted, and hand-edited wrappers are healed. Wrapper scripts re-read their bytes on every run, so an edit is **live on the next invocation** (no reload), and the scripts work identically in interactive shells, scripts, cron, and non-login ssh sessions (`~/.local/bin` must stay on `PATH` — a loud warning with a copy-paste fix appears when it isn't). Create refuses name collisions: a foreign file at `~/.local/bin/<name>` and names resolving to another binary on `PATH` are never overwritten.
+
 ### ssh

 | Command | File | Purpose | Configuration |
@@ -520,6 +534,30 @@ Feature-flag management CLIs (see [SCRIPTS.md → lib/flags.sh](SCRIPTS.md#libfl
 | `flag-set <name> [value]` | Set a flag, optionally with a value (requires sudo) |
 | `flag-clear <name>` | Unset a flag (requires sudo) |

+### bank
+
+**File:** `bin/pos-bank`
+
+Persistent command bank for saving and running shell commands. Commands are stored in `~/.config/linux_post_install/bank.env` (pipe-delimited: `name|description|command`). Supports parameterized templates with `{param}` placeholders that are substituted at run time (quoted for safe shell evaluation).
+
+On a TTY with no arguments, `pos bank` opens an interactive menu (list / add / run / edit / remove).
+
+| Command | Purpose |
+|---------|---------|
+| `pos bank list` | List all saved commands |
+| `pos bank add <name> [desc] [cmd]` | Add a new command (interactive for missing args) |
+| `pos bank show <name>` | Show command details and detected parameters |
+| `pos bank run <name> [key=val …]` | Run a command (interactive for missing params) |
+| `pos bank edit <name>` | Edit an existing command |
+| `pos bank remove <name>` | Remove a command |
+
+Example with parameters:
+
+```
+pos bank add convert "Convert video" "ffmpeg -i {input} -crf {quality} {output}"
+pos bank run convert input=clip.mp4 quality=23 output=clip.mkv
+```
+
 ### config

 **File:** `bin/pos-config`
@@ -45,7 +45,7 @@ The phases:
 | # | Phase | Script/action |
 |---|-------|----------------|
 | 1 | preinstall | `preinstall.sh` — apt packages + yt-dlp |
-| 2 | scripts | Copies `bin/*` → `/usr/local/bin/` (755), `lib/common.sh` + `lib/flags.sh` + `lib/notify.sh` + `lib/entertainment-lib.sh` + `lib/entertainment-plugin-lib.sh` + `lib/scheduler-lib.sh` + `lib/config-ui.sh` + `lib/user-timers-lib.sh` + `lib/usb-lib.sh` + `lib/share-lib.sh` + `lib/menu-lib.sh` + `lib/registry.sh` → `/usr/local/bin/` (644). Copies precompiled arch binaries from `x64_bin/` (or `arm64_bin/`) → `/usr/local/bin/`. With `--feature`: also installs `features/*` (see below) |
+| 2 | scripts | Copies `bin/*` → `/usr/local/bin/` (755), `lib/common.sh` + `lib/flags.sh` + `lib/notify.sh` + `lib/entertainment-lib.sh` + `lib/entertainment-plugin-lib.sh` + `lib/scheduler-lib.sh` + `lib/config-ui.sh` + `lib/user-timers-lib.sh` + `lib/usb-lib.sh` + `lib/share-lib.sh` + `lib/menu-lib.sh` + `lib/registry.sh` + `lib/yt-lib.sh` + `lib/bank-lib.sh` → `/usr/local/bin/` (644). Copies precompiled arch binaries from `x64_bin/` (or `arm64_bin/`) → `/usr/local/bin/`. With `--feature`: also installs `features/*` (see below) |
 | 3 | postinstall | `postinstall.sh` — PATH, completion, SSH keys, systemd |
 | 4 | scalepoint | Shallow-clones ScaleTail templates to `/usr/local/share/linux_post_install/scale-tail` |
 | 5 (opt) | apps | `apps/install.sh` when `--apps` (interactive) or `--full` (all, non-interactive) |
@@ -245,6 +245,13 @@ Sourced by `bin/pos-tree` (tree rendering incl. the `[deps: …]` annotations) a

 ---

+## lib/yt-lib.sh — shared YouTube helpers
+
+**File:** `lib/yt-lib.sh` (installed to `/usr/local/bin/yt-lib.sh`)
+**Purpose:** shared helpers for yt-dlp-based media tools (`pos media yt *`). Provides `yt_check_deps` (dependency validation for yt-dlp/ffmpeg), `yt_validate_url` (return-1 URL checker, never exits — callers prefix errors), `yt_echo_cmd` (dry-run command display), and `classify_url` (URL type classification). Sourced by `bin/pos-media-yt-mp3`, `bin/pos-media-yt-mp4`, `bin/pos-media-yt-grab`, and `bin/pos-media-yt-subtitles` via the standard fallback chain.
+
+---
+
 ## features/autostart.sh — boot-time feature

 **File:** `features/autostart.sh` (installed to `/usr/local/bin/autostart.sh` by `./install.sh --feature`)
@@ -79,7 +79,7 @@ Restart=on-failure
 WantedBy=multi-user.target
 ```

-**Configuration:** socket at `/run/ssh-agent/socket` (world-readable/writable). `~/.bashrc` (set by `postinstall.sh`) exports `SSH_AUTH_SOCK` to it. Not gated on any feature flag.
+**Configuration:** socket at `/run/ssh-agent/socket` (world-readable/writable). `~/.bashrc` (set by `postinstall.sh`) exports `SSH_AUTH_SOCK` to it. Gated on the `ssh-agent` feature flag — only enabled when the flag is set (`./install.sh --feature` or `flag-set ssh-agent`).

 ---

@@ -124,7 +124,7 @@ SIGTERM. A oneshot job that happens to be running at shutdown gets SIGKILLed

 ## Feature-flag gating

-The systemd loop in `postinstall.sh` special-cases two units:
+The systemd loop in `postinstall.sh` special-cases three units:

 ```bash
 if [ "$svc_name" = "autostart.service" ] && ! flag_is_set autostart; then
@@ -135,10 +135,15 @@ if [ "$svc_name" = "usb-automount.service" ] && ! flag_is_set usb-automount; the
    warn "usb-automount feature not installed — skipping usb-automount.service (run ./install.sh --feature)"
    continue
 fi
+if [ "$svc_name" = "ssh-agent.service" ] && ! flag_is_set ssh-agent; then
+    warn "ssh-agent feature not installed — skipping ssh-agent.service (run ./install.sh --feature)"
+    continue
+fi
 ```

 - `autostart.service` is **enabled** only when the `autostart` feature flag is set (`./install.sh --feature` or `flag-set autostart`). See [SCRIPTS.md → lib/flags.sh](SCRIPTS.md#libflagssh--feature-flags).
 - `usb-automount.service` is **enabled** only when the `usb-automount` feature flag is set — same mechanism.
+- `ssh-agent.service` is **enabled** only when the `ssh-agent` feature flag is set — same mechanism.

 ---

@@ -1,10 +1,11 @@
 # How-To: `pos system`

-Host care: encrypted backups, firewall, health dashboard, and uninstall. Tools:
-`backup`, `firewall`, `health`, `uninstall`.
+Host care: encrypted backups, firewall, health dashboard, persistent aliases, and uninstall. Tools:
+`alias`, `backup`, `firewall`, `health`, `uninstall`.

 | Tool | What it does |
 |------|--------------|
+| `pos system alias` | Manage persistent command aliases (wrapper scripts in `~/.local/bin/`) |
 | `pos system health` | Host health dashboard (disk, RAM, services, backup age, fail2ban, docker) |
 | `pos system backup` | gpg-encrypted (AES-256) folder snapshots |
 | `pos system firewall` | Interactive UFW ("UFW POWER") management |
@@ -12,6 +13,122 @@ Host care: encrypted backups, firewall, health dashboard, and uninstall. Tools:

 ---

+## `pos system alias` — persistent command aliases
+
+Create named shortcuts for shell commands. Each alias becomes an executable
+wrapper script in `~/.local/bin/` that runs the mapped command with any
+arguments forwarded.
+
+### Quick start
+
+```bash
+pos system alias                     # interactive menu
+pos system alias list                # show all aliases
+pos system alias create              # interactive create wizard
+pos system alias show restart-dns    # show one alias's details
+```
+
+### Examples
+
+**Create an alias:**
+
+```bash
+pos system alias create restart-dns
+# Step 1: Alias name → restart-dns
+# Step 2: Command → sudo systemctl restart systemd-resolved
+# Confirm → [y]
+# Alias 'restart-dns' created.
+# Test it: restart-dns
+```
+
+**Create more aliases:**
+
+```bash
+pos system alias create exit-google
+# Command → pkill -f chrome
+
+pos system alias create update-all
+# Command → sudo apt update && sudo apt upgrade -y
+
+pos system alias create my-ip
+# Command → curl -s ifconfig.me
+```
+
+**Use them directly** (no `pos` needed — just the alias name):
+
+```bash
+restart-dns          # runs: sudo systemctl restart systemd-resolved
+exit-google          # runs: pkill -f chrome
+update-all           # runs: sudo apt update && sudo apt upgrade -y
+my-ip                # runs: curl -s ifconfig.me
+restart-dns 1.1.1.1  # arguments are forwarded to the command
+```
+
+**Edit an alias:**
+
+```bash
+pos system alias edit restart-dns
+# Shows current command, prompts for new value (Enter = keep current)
+```
+
+**Remove an alias:**
+
+```bash
+pos system alias remove restart-dns
+# Shows details, asks for confirmation (default: no)
+```
+
+**List all aliases:**
+
+```bash
+pos system alias list
+#   Name             Command
+#   ---------------- ----------------------------------------
+#   restart-dns      sudo systemctl restart systemd-resolved
+#   exit-google      pkill -f chrome
+```
+
+### How it works
+
+- Aliases are stored in `~/.config/linux_post_install/aliases.env`
+  (pipe-delimited: `name|command`, chmod 600).
+- Each alias is materialized as an executable wrapper at
+  `~/.local/bin/<name>` (chmod 755).
+- Wrappers are synced automatically on every `pos system alias` invocation
+  — edits are live on the next run.
+- Name validation: must start with a letter, then letters/digits/hyphens/
+  underscores. Collisions with existing files or PATH binaries are refused.
+
+### PATH requirement
+
+`~/.local/bin` must be on your `PATH` for alias scripts to resolve by name.
+If it isn't, you'll see a warning with a fix:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# Persist it:
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile
+```
+
+### Recipes
+
+- **DNS restart shortcut:** `pos system alias create restart-dns`
+  with command `sudo systemctl restart systemd-resolved`.
+- **Quick app launcher:** `pos system alias create open-code`
+  with command `code ~/projects`.
+- **Custom backup alias:** `pos system alias create snap-docs`
+  with command `pos system backup ~/Documents`.
+
+### Troubleshooting
+
+- `Alias 'X' already exists` → use `pos system alias edit X` instead.
+- `File '~/.local/bin/X' already exists` → pick a different name (pos
+  won't overwrite non-pos-owned files).
+- `~/.local/bin is not on your PATH` → add it to `~/.profile` (see above).
+- Alias name autocompletes stale after removal → run `hash -r`.
+
+---
+
 ## `pos system health` — host health dashboard

 ```bash
@@ -240,3 +357,4 @@ confirmation. The git repo is **never** removed — delete it manually if desire
 - Reference: [DOC/POS.md → system](../POS.md)
 - Notify platform config: [communication.md](communication.md)
 - Backup roots shared with health: `system.env` ([DOC/POS.md](../POS.md))
+- Alias storage: `~/.config/linux_post_install/aliases.env` ([DOC/POS.md → pos system alias](../POS.md#pos-system-alias-in-detail))
@@ -28,6 +28,9 @@ _pos_commands() {
 # ── Category list (sorted, filename-derived) ─────────────────────
 # Nested sub-tools (pos-<cat>-<a>-<b> where pos-<cat>-<a> exists) are
 # omitted from the cheat-sheet line — they are shown under their parent tool.
+# Category-less tools (pos-bank, pos-config, pos-tree) are emitted as their
+# own line with an empty subcommand column; a name already present as a
+# category (pos-ai vs the ai category built from pos-ai-*) is NOT duplicated.
 _pos_category_list() {
    local -A cats=()
    local cmd cat f
@@ -35,7 +38,10 @@ _pos_category_list() {
        [ -x "$f" ] || continue
        cmd="${f##*/pos-}"
        cat="${cmd%%-*}"
-        [ "$cat" = "$cmd" ] && continue
+        if [ "$cat" = "$cmd" ]; then
+            cats["$cmd"]="${cats[$cmd]:-}"
+            continue
+        fi
        cats["$cat"]+="${cmd#*-} "
    done
    local c subs joined s s2 top=() is_nested
@@ -208,6 +214,8 @@ EXAMPLES

  pos tree                                Show the command tree (categories + subcommands)

+  pos bank run <name>                     Run a saved command from the bank
+
  pos docker vbox create lab1              Create disposable Docker VM
  pos docker vbox create lab1 --dir .      Create VM using current directory
  pos docker vbox enter lab1               Shell into a Docker VM
@@ -266,7 +274,7 @@ MAIN_LOG="$LOG_DIR/pos.log"
 log_cmd() { echo "[$(date '+%Y-%m-%d %H:%M:%S')] $* → exit $2" >> "$MAIN_LOG"; }

 # Commands that read from stdin interactively — only log invocation
-INTERACTIVE_CMDS="docker-compose docker-vbox network-hotspot system-firewall media-mp4 media-yt-mp4 media-sync system-backup system-uninstall share-usb-server share-smb-server share-smb-client share-nfs-client share-nfs-server communication-telegram-listener communication-matrix-listener ai ai-gemini ai-openrouter ai-llamacpp ai-alias system-schedule entertainment-config config"
+INTERACTIVE_CMDS="bank docker-compose docker-vbox network-hotspot system-firewall media-mp4 media-yt-mp4 media-sync system-backup system-uninstall share-usb-server share-smb-server share-smb-client share-nfs-client share-nfs-server communication-telegram-listener communication-matrix-listener ai ai-gemini ai-openrouter ai-llamacpp ai-alias system-alias system-schedule entertainment-config config"

 for ((i=n-1; i>=0; i--)); do
    cmd="pos"
@@ -0,0 +1,311 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# POS: bank — Persistent command bank for saving and running shell commands
+# POS_SUBCMDS: list add show run edit remove
+
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+source "$(dirname "$0")/../lib/menu-lib.sh" 2>/dev/null || source "$(dirname "$0")/menu-lib.sh"
+source "$(dirname "$0")/../lib/bank-lib.sh" 2>/dev/null || source "$(dirname "$0")/bank-lib.sh"
+
+usage() {
+    cat <<'EOF'
+Usage: pos bank [subcommand] [args]
+
+Persistent command bank for saving and running shell commands.
+
+Subcommands:
+  list                  List all saved commands
+  add <name> [desc] [cmd]  Add a new command (interactive if args missing)
+  show <name>           Show command details
+  run <name> [key=val ...] Run a command (interactive for missing params)
+  edit <name>           Edit an existing command
+  remove <name>         Remove a command
+
+Interactive menu:
+  pos bank              (no args on a terminal)
+
+Examples:
+  pos bank add disk-info "Disk usage" "df -h && du -sh /mnt/12T"
+  pos bank run disk-info
+  pos bank run convert-video input=/path/to/video.mp4 quality=23 output=/path/out.mp4
+EOF
+    exit 0
+}
+
+case "${1:-}" in
+    -h|--help) usage ;;
+esac
+
+# ── Interactive command picker ───────────────────────────────────
+_pick_command() {
+    bank_load
+    local count="${#BANK_NAMES[@]}"
+    if [ "$count" -eq 0 ]; then
+        warn "Command bank is empty — add one with: pos bank add <name> \"desc\" \"cmd\""
+        return 1
+    fi
+    local -a items=()
+    local i
+    for ((i = 0; i < count; i++)); do
+        if [ -n "${BANK_DESCS[$i]}" ]; then
+            items+=("${BANK_NAMES[$i]} — ${BANK_DESCS[$i]}")
+        else
+            items+=("${BANK_NAMES[$i]}")
+        fi
+    done
+    local choice
+    choice="$(menu_pick "Pick command" "${items[@]}")" || return 1
+    echo "${BANK_NAMES[$((choice - 1))]}"
+}
+
+# ── cmd_list ─────────────────────────────────────────────────────
+cmd_list() {
+    bank_load
+    local count="${#BANK_NAMES[@]}"
+    if [ "$count" -eq 0 ]; then
+        log "Command bank is empty — add one with: pos bank add <name> \"desc\" \"cmd\""
+        return 0
+    fi
+    echo
+    echo "COMMAND BANK"
+    echo
+    local i
+    for ((i = 0; i < count; i++)); do
+        if [ -n "${BANK_DESCS[$i]}" ]; then
+            printf '  %-25s %s\n' "${BANK_NAMES[$i]}" "${BANK_DESCS[$i]}"
+        else
+            printf '  %s\n' "${BANK_NAMES[$i]}"
+        fi
+    done
+    echo
+}
+
+# ── cmd_add ──────────────────────────────────────────────────────
+cmd_add() {
+    local name="" desc="" cmd=""
+    case $# in
+        0) ;;
+        1) name="$1" ;;
+        2) name="$1"; desc="$2" ;;
+        *) name="$1"; desc="$2"; cmd="$3" ;;
+    esac
+    if [ -z "$name" ]; then
+        name="$(menu_ask_value "Name")" || return 0
+    fi
+    if [ -z "$desc" ]; then
+        desc="$(menu_ask_value "Description" "")" || return 0
+    fi
+    if [ -z "$cmd" ]; then
+        cmd="$(menu_read_value "Command")" || return 0
+    fi
+    bank_valid_name "$name" || err "Invalid name: $name (use letters, numbers, hyphens, underscores)"
+    [ -n "$cmd" ] || err "Command cannot be empty"
+    bank_load
+    local i
+    for ((i = 0; i < ${#BANK_NAMES[@]}; i++)); do
+        [[ "${BANK_NAMES[$i]}" == "$name" ]] && err "Command '$name' already exists (use 'pos bank edit' to modify)"
+    done
+    bank_add "$name" "$desc" "$cmd"
+    ok "Saved: $name"
+}
+
+# ── cmd_show ─────────────────────────────────────────────────────
+cmd_show() {
+    [ -n "${1:-}" ] || err "Usage: pos bank show <name>"
+    local name="$1"
+    bank_load
+    bank_find "$name" >/dev/null 2>&1 || err "Command not found: $name"
+    local cmd_name cmd_desc cmd_cmd
+    cmd_name="${BANK_NAMES[$BANK_IDX]}"
+    cmd_desc="${BANK_DESCS[$BANK_IDX]}"
+    cmd_cmd="${BANK_CMDS[$BANK_IDX]}"
+    echo
+    echo "Name: $cmd_name"
+    echo
+    echo "Description:"
+    if [ -n "$cmd_desc" ]; then
+        echo "$cmd_desc"
+    else
+        echo "  (none)"
+    fi
+    echo
+    echo "Command:"
+    echo
+    echo "$cmd_cmd"
+    local params
+    params="$(_extract_params "$cmd_cmd")"
+    if [ -n "$params" ]; then
+        echo
+        echo "Parameters:"
+        echo "$params" | while IFS= read -r p; do
+            echo "  $p"
+        done
+    fi
+    echo
+}
+
+# ── cmd_run ──────────────────────────────────────────────────────
+cmd_run() {
+    local name=""
+    local -a cli_params=()
+    if [ $# -eq 0 ]; then
+        name="$(_pick_command)" || return 0
+    else
+        name="$1"; shift
+        while [ $# -gt 0 ]; do
+            case "$1" in
+                *=*) cli_params+=("$1") ;;
+                *) err "Invalid parameter format: $1 (expected key=value)" ;;
+            esac
+            shift
+        done
+    fi
+    bank_load
+    bank_find "$name" >/dev/null 2>&1 || err "Command not found: $name"
+    local cmd_name cmd_desc cmd_cmd
+    cmd_name="${BANK_NAMES[$BANK_IDX]}"
+    cmd_desc="${BANK_DESCS[$BANK_IDX]}"
+    cmd_cmd="${BANK_CMDS[$BANK_IDX]}"
+    # Detect parameters
+    local params_str
+    params_str="$(_extract_params "$cmd_cmd")"
+    local -a params=()
+    if [ -n "$params_str" ]; then
+        while IFS= read -r p; do
+            params+=("$p")
+        done <<< "$params_str"
+    fi
+    # Build parameter values from CLI args
+    local -A param_values=()
+    for p in "${cli_params[@]}"; do
+        local key="${p%%=*}" val="${p#*=}"
+        param_values["$key"]="$val"
+    done
+    # Interactively prompt for missing parameters
+    local -a missing=()
+    for p in "${params[@]}"; do
+        [[ -z "${param_values[$p]+x}" ]] && missing+=("$p")
+    done
+    if [ ${#missing[@]} -gt 0 ]; then
+        for p in "${missing[@]}"; do
+            local val
+            val="$(menu_ask_value "$p" "")" || return 0
+            param_values["$p"]="$val"
+        done
+    fi
+    # Substitute parameters
+    local final_cmd="$cmd_cmd"
+    if [ ${#params[@]} -gt 0 ]; then
+        local -a sub_args=()
+        for p in "${params[@]}"; do
+            sub_args+=("${p}=${param_values[$p]:-}")
+        done
+        final_cmd="$(_substitute_params "$cmd_cmd" "${sub_args[@]}")"
+    fi
+    echo
+    log "Running: $final_cmd"
+    echo
+    eval "$final_cmd"
+    return $?
+}
+
+# ── cmd_edit ─────────────────────────────────────────────────────
+cmd_edit() {
+    local name="${1:-}"
+    if [ -z "$name" ]; then
+        name="$(_pick_command)" || return 0
+    fi
+    bank_load
+    bank_find "$name" >/dev/null 2>&1 || err "Command not found: $name"
+    local old_name old_desc old_cmd
+    old_name="${BANK_NAMES[$BANK_IDX]}"
+    old_desc="${BANK_DESCS[$BANK_IDX]}"
+    old_cmd="${BANK_CMDS[$BANK_IDX]}"
+    echo
+    log "Editing: $old_name"
+    echo
+    local new_name new_desc new_cmd
+    new_name="$(menu_ask_value "New name" "$old_name")" || return 0
+    new_desc="$(menu_ask_value "New description" "$old_desc")" || return 0
+    new_cmd="$(menu_read_value "New command")" || return 0
+    [ -z "$new_name" ] && new_name="$old_name"
+    [ -z "$new_desc" ] && new_desc="$old_desc"
+    [ -z "$new_cmd" ] && new_cmd="$old_cmd"
+    if [ "$new_name" != "$old_name" ]; then
+        bank_valid_name "$new_name" || err "Invalid name: $new_name"
+        local i found=0
+        for ((i = 0; i < ${#BANK_NAMES[@]}; i++)); do
+            [[ "${BANK_NAMES[$i]}" == "$new_name" ]] && found=1
+        done
+        [[ "$found" -eq 1 ]] && err "A command named '$new_name' already exists"
+        bank_remove "$old_name"
+        bank_add "$new_name" "$new_desc" "$new_cmd"
+    else
+        bank_update "$new_name" "$new_desc" "$new_cmd"
+    fi
+    ok "Updated: $new_name"
+}
+
+# ── cmd_remove ───────────────────────────────────────────────────
+cmd_remove() {
+    local name="${1:-}"
+    if [ -z "$name" ]; then
+        name="$(_pick_command)" || return 0
+    fi
+    bank_load
+    bank_find "$name" >/dev/null 2>&1 || err "Command not found: $name"
+    if [ -t 0 ]; then
+        confirm "Remove '$name'?" n || { log "Cancelled"; return 0; }
+    fi
+    bank_remove "$name"
+    ok "Removed: $name"
+}
+
+# ── Interactive menu ─────────────────────────────────────────────
+run_menu() {
+    menu_guard || exit 1
+    while true; do
+        local choice
+        choice="$(menu_run "Command Bank" \
+            "List commands" \
+            "Add command" \
+            "Run command" \
+            "Edit command" \
+            "Remove command")" || return 0
+        case "$choice" in
+            1) cmd_list ;;
+            2) cmd_add ;;
+            3) cmd_run ;;
+            4) cmd_edit ;;
+            5) cmd_remove ;;
+        esac
+    done
+}
+
+# ── Dispatch ─────────────────────────────────────────────────────
+if [ "${1:-}" = "menu" ]; then
+    run_menu
+    exit 0
+fi
+
+for arg in "$@"; do
+    case "$arg" in
+        -h|--help) usage ;;
+    esac
+done
+
+if [ $# -eq 0 ] && [ -t 0 ]; then
+    run_menu
+    exit 0
+fi
+
+case "${1:-}" in
+    list)   shift; cmd_list "$@" ;;
+    add)    shift; cmd_add "$@" ;;
+    show)   shift; cmd_show "$@" ;;
+    run)    shift; cmd_run "$@" ;;
+    edit)   shift; cmd_edit "$@" ;;
+    remove) shift; cmd_remove "$@" ;;
+    "")     usage ;;
+    *)      err "Unknown subcommand: $1 (see --help)" ;;
+esac
@@ -0,0 +1,488 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# POS: system alias — Manage persistent command aliases (wrapper scripts in ~/.local/bin/)
+# POS_SUBCMDS: create edit remove list show
+
+source "$(dirname "$0")/../lib/common.sh" 2>/dev/null || source "$(dirname "$0")/common.sh"
+source "$(dirname "$0")/../lib/menu-lib.sh" 2>/dev/null || source "$(dirname "$0")/menu-lib.sh"
+
+# ── Paths & constants ──────────────────────────────────────────
+ENV_FILE="${CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/linux_post_install}/aliases.env"
+
+# ── Core helpers ───────────────────────────────────────────────
+
+# Load aliases from ENV_FILE into parallel arrays.
+# Loop vars use _a* prefix to avoid dynamic-scope collisions with callers.
+_alias_load() {
+    _ALIAS_NAMES=(); _ALIAS_COMMANDS=()
+    [ -f "$ENV_FILE" ] || return 0
+    local _an _ac
+    while IFS='|' read -r _an _ac; do
+        [[ "$_an" =~ ^[[:space:]]*# ]] && continue
+        [[ -z "${_an// /}" ]] && continue
+        _an="${_an## }"; _an="${_an%% }"
+        [[ "$_an" =~ ^[a-zA-Z][a-zA-Z0-9_-]*$ ]] || continue
+        _ac="${_ac## }"; _ac="${_ac%% }"
+        _ALIAS_NAMES+=("$_an")
+        _ALIAS_COMMANDS+=("$_ac")
+    done < <(grep -v '^[[:space:]]*#' "$ENV_FILE" | grep -v '^[[:space:]]*$' || true)
+}
+
+# Save parallel arrays back to ENV_FILE (atomic overwrite).
+_alias_save() {
+    mkdir -p "$(dirname "$ENV_FILE")"
+    {
+        printf '%s\n' "# System aliases — managed by pos system alias (do not hand-edit)"
+        printf '%s\n' "# Format: alias_name|command"
+        local i
+        for ((i = 0; i < ${#_ALIAS_NAMES[@]}; i++)); do
+            printf '%s|%s\n' "${_ALIAS_NAMES[$i]}" "${_ALIAS_COMMANDS[$i]}"
+        done
+    } >"$ENV_FILE"
+    chmod 600 "$ENV_FILE"
+}
+
+# ── Wrapper scripts ────────────────────────────────────────────
+
+_wrapper_path() {
+    printf '%s/.local/bin/%s' "$HOME" "$1"
+}
+
+# Ownership test: line 2 must carry our generator marker.
+_alias_owned() {
+    [ -f "$1" ] && sed -n '2p' "$1" 2>/dev/null | grep -q 'Managed by pos system alias'
+}
+
+# Render one wrapper to stdout (args: name command).
+_wrapper_render() {
+    local name="$1" command="$2"
+    cat <<WRAPPER_EOF
+#!/usr/bin/env bash
+# Managed by pos system alias — regenerated automatically; hand-edits are overwritten.
+# Alias: ${name} | command: ${command}
+set -euo pipefail
+exec bash -c '${command} "\$@"' _ "\$@"
+WRAPPER_EOF
+}
+
+# Atomically install/refresh one wrapper. Skips when content matches.
+# Pre-commit validation: bash -n on the rendered file; failure keeps previous.
+_wrapper_install() {
+    local name="$1" command="$2" path tmp
+    path="$(_wrapper_path "$name")"
+    tmp="$(mktemp "${HOME}/.local/bin/.pos-alias.XXXXXX")"
+    _wrapper_render "$name" "$command" >"$tmp"
+    if cmp -s "$tmp" "$path" 2>/dev/null; then
+        rm -f "$tmp"
+        return 0
+    fi
+    if ! bash -n "$tmp" 2>/dev/null; then
+        warn "Wrapper for '$name' failed syntax check — keeping previous version" >&2
+        rm -f "$tmp"
+        return 1
+    fi
+    mv "$tmp" "$path"
+    chmod 755 "$path"
+}
+
+# rc 0 iff ~/.local/bin is on PATH.
+_alias_check_path() {
+    case ":$PATH:" in
+        *":$HOME/.local/bin:"*) return 0 ;;
+        *) return 1 ;;
+    esac
+}
+
+# Two-way reconciliation on every invocation:
+#   forward:  each ENV entry → render-diff-install
+#   reverse:  owned wrappers whose name is not in ENV → deleted
+#   plus: PATH guidance when owned wrappers exist but ~/.local/bin is absent
+_alias_sync() {
+    _alias_load
+    local bin_dir="${HOME}/.local/bin" i name f base match any=0
+    mkdir -p "$bin_dir"
+    for ((i = 0; i < ${#_ALIAS_NAMES[@]}; i++)); do
+        _wrapper_install "${_ALIAS_NAMES[$i]}" "${_ALIAS_COMMANDS[$i]}" || :
+    done
+    for f in "$bin_dir"/*; do
+        [ -f "$f" ] || continue
+        _alias_owned "$f" || continue
+        base="${f##*/}"
+        match=0
+        for name in ${_ALIAS_NAMES[@]+"${_ALIAS_NAMES[@]}"}; do
+            [ "$base" = "$name" ] && { match=1; break; }
+        done
+        [ "$match" -eq 1 ] || rm -f "$f"
+    done
+    if ! _alias_check_path; then
+        for f in "$bin_dir"/*; do
+            [ -f "$f" ] && _alias_owned "$f" && { any=1; break; }
+        done
+        if [ "$any" -eq 1 ]; then
+            warn "~/.local/bin is not on your PATH — alias scripts will not resolve by name."
+            warn "  Fix now:     export PATH=\"\$HOME/.local/bin:\$PATH\""
+            warn "  Persist it:  echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.profile"
+        fi
+    fi
+    return 0
+}
+
+_alias_find() {
+    local name="$1" i
+    for ((i = 0; i < ${#_ALIAS_NAMES[@]}; i++)); do
+        if [ "${_ALIAS_NAMES[$i]}" = "$name" ]; then
+            echo "$i"
+            return 0
+        fi
+    done
+    echo "-1"
+    return 0
+}
+
+_alias_name_valid() {
+    [[ "$1" =~ ^[a-zA-Z][a-zA-Z0-9_-]*$ ]]
+}
+
+# Truncate a command string for display (inline pipes, redirects).
+_command_truncate() {
+    local s="$1" max="${2:-42}"
+    s="${s//$'\n'/ }"
+    if [ ${#s} -gt "$max" ]; then
+        printf '%s…' "${s:0:max}"
+    else
+        printf '%s' "$s"
+    fi
+}
+
+# ── Non-interactive output ─────────────────────────────────────
+
+_alias_table() {
+    local count=${#_ALIAS_NAMES[@]} i
+    [ "$count" -eq 0 ] && return 0
+    printf '  %-16s %s\n' "Name" "Command"
+    printf '  %-16s %s\n' "----------------" "----------------------------------------"
+    for ((i = 0; i < count; i++)); do
+        printf '  %-16s %s\n' "${_ALIAS_NAMES[$i]}" "$(_command_truncate "${_ALIAS_COMMANDS[$i]}" 60)"
+    done
+}
+
+_alias_list() {
+    printf 'Aliases (%d):\n' "${#_ALIAS_NAMES[@]}"
+    _alias_table
+}
+
+_alias_show() {
+    local idx
+    idx="$(_alias_find "$1")"
+    [ "$idx" = "-1" ] && err "Alias '$1' not found"
+    local name="${_ALIAS_NAMES[$idx]}" command="${_ALIAS_COMMANDS[$idx]}"
+    printf '  %-12s %s\n' "Alias:" "$name"
+    printf '  %-12s %s\n' "Command:" "$command"
+    if _alias_check_path; then
+        printf '  %-12s %s\n' "Wrapper:" "$(_wrapper_path "$name")"
+    else
+        printf '  %-12s %s\n' "Wrapper:" "(not installed — ~/.local/bin not on PATH)"
+    fi
+    printf '  %-12s %s\n' "Test:" "$name"
+}
+
+# ── Interactive: main menu ─────────────────────────────────────
+
+_alias_menu() {
+    menu_guard || return 1
+    while true; do
+        {
+            _alias_load
+            if [ ${#_ALIAS_NAMES[@]} -eq 0 ]; then
+                echo "${YELLOW}[!] No aliases defined yet — create one with option 1.${RESET}"
+            else
+                _alias_table
+                printf '  %d alias(es)\n' "${#_ALIAS_NAMES[@]}"
+            fi
+            echo >&2
+        } >&2
+        local choice
+        choice="$(menu_run "System Aliases" "Create new alias" "Edit existing alias" \
+            "Remove alias" "List aliases")" || return 0
+        case "$choice" in
+            1) _alias_create ;;
+            2) _alias_edit ;;
+            3) _alias_remove ;;
+            4) : ;;  # List aliases — the loop's pre-render IS the current table
+        esac
+    done
+}
+
+# ── Interactive: create ────────────────────────────────────────
+
+_alias_create() {
+    local preset_name="${1:-}"
+    section "Create System Alias" >&2
+
+    # Step 1: Alias name
+    local name="$preset_name"
+    while true; do
+        if [ -z "$name" ]; then
+            step 1 2 "Alias Name" >&2
+            name="$(menu_ask_value "Alias name" "")" || return 0
+        fi
+        [ -z "$name" ] && { warn "Alias name cannot be empty" >&2; name=""; continue; }
+        if ! _alias_name_valid "$name"; then
+            warn "Invalid name '$name' — use letters, digits, hyphens, underscores (start with a letter)" >&2
+            name=""; continue
+        fi
+        _alias_load
+        local existing
+        existing="$(_alias_find "$name")"
+        if [ "$existing" != "-1" ]; then
+            warn "Alias '$name' already exists — use 'pos system alias edit $name' instead" >&2
+            [ -n "$preset_name" ] && return 1
+            name=""; continue
+        fi
+        # Collision: wrapper exists without our marker → refuse
+        local wpath
+        wpath="$(_wrapper_path "$name")"
+        if [ -e "$wpath" ]; then
+            _alias_owned "$wpath" || err "File '~/.local/bin/$name' already exists and was not created by pos system alias — pick another name"
+        fi
+        # Collision: name resolves to another binary on PATH → refuse
+        if command -v "$name" >/dev/null 2>&1; then
+            err "'$name' already exists on PATH as $(command -v "$name") — pick another name"
+        fi
+        break
+    done
+
+    # Step 2: Command
+    local command=""
+    while true; do
+        step 2 2 "Command" >&2
+        command="$(menu_ask_value "Command to execute" "")" || return 0
+        [ -z "$command" ] && { warn "Command cannot be empty" >&2; continue; }
+        [[ "$command" == *'|'* ]] || break
+        warn "Command must not contain '|' characters" >&2
+        command=""
+    done
+
+    # Confirmation
+    {
+        echo "────────────────────────────────────────────"
+        printf '  Create alias '\''%s'\''?\n' "$name"
+        printf '    Command: %s\n' "$command"
+        echo "────────────────────────────────────────────"
+    } >&2
+    if ! confirm "Create alias '$name'?" y; then
+        log "Aborted." >&2
+        return 0
+    fi
+
+    _alias_load
+    _ALIAS_NAMES+=("$name")
+    _ALIAS_COMMANDS+=("$command")
+    _alias_save
+    _alias_sync
+    log "Alias '$name' created." >&2
+    log "Test it: $name" >&2
+    log "Available immediately: $(_wrapper_path "$name")" >&2
+}
+
+# ── Interactive: edit ──────────────────────────────────────────
+
+_alias_edit() {
+    local preset_name="${1:-}"
+    _alias_load
+    if [ ${#_ALIAS_NAMES[@]} -eq 0 ]; then
+        warn "No aliases to edit — create one first" >&2
+        return 0
+    fi
+
+    local name="$preset_name"
+    if [ -z "$name" ]; then
+        section "Edit System Alias" >&2
+        local display_items=() i
+        for ((i = 0; i < ${#_ALIAS_NAMES[@]}; i++)); do
+            local c="${_ALIAS_COMMANDS[$i]}"
+            if [ ${#c} -gt 30 ]; then
+                c="${c:0:30}…"
+            fi
+            display_items+=("${_ALIAS_NAMES[$i]} → ${c}")
+        done
+        local picked
+        picked="$(menu_pick "Pick alias to edit" "${display_items[@]}")" || return 0
+        name="${_ALIAS_NAMES[$((picked - 1))]}"
+    fi
+
+    local idx
+    idx="$(_alias_find "$name")"
+    if [ "$idx" = "-1" ]; then
+        err "Alias '$name' not found"
+    fi
+
+    # Show current values
+    {
+        echo "  Current values for '$name':"
+        printf '    Command: %s\n' "${_ALIAS_COMMANDS[$idx]}"
+        echo >&2
+    } >&2
+
+    local new_command="${_ALIAS_COMMANDS[$idx]}"
+    local changed=0
+
+    # Edit command
+    step 1 1 "Command" >&2
+    local default_display="${_ALIAS_COMMANDS[$idx]}"
+    [ ${#default_display} -gt 60 ] && default_display="${default_display:0:60}…"
+    local tmp_command
+    tmp_command="$(menu_ask_value "Command to execute" "$default_display")" || return 0
+    if [ -n "$tmp_command" ]; then
+        if [[ "$tmp_command" == *'|'* ]]; then
+            warn "Command must not contain '|' characters" >&2
+            return 0
+        fi
+        if [ "$tmp_command" != "${_ALIAS_COMMANDS[$idx]}" ]; then
+            new_command="$tmp_command"
+            changed=1
+        fi
+    fi
+
+    # No changes?
+    if [ "$changed" -eq 0 ]; then
+        log "No changes — nothing to save." >&2
+        return 0
+    fi
+
+    # Show diff summary
+    {
+        echo "────────────────────────────────────────────"
+        printf '  Save changes to '\''%s'\''?\n' "$name"
+        local tag_c
+        [ "$new_command" = "${_ALIAS_COMMANDS[$idx]}" ] && tag_c="(unchanged)" || tag_c="(changed)"
+        printf '    Command: %s %s\n' "$new_command" "$tag_c"
+        echo "────────────────────────────────────────────"
+    } >&2
+    if ! confirm "Save changes to '$name'?" y; then
+        log "Discarded." >&2
+        return 0
+    fi
+
+    _alias_load
+    _ALIAS_COMMANDS[$idx]="$new_command"
+    _alias_save
+    _alias_sync
+    log "Alias '$name' updated — the change is live on next invocation." >&2
+}
+
+# ── Interactive: remove ────────────────────────────────────────
+
+_alias_remove() {
+    local preset_name="${1:-}"
+    _alias_load
+    if [ ${#_ALIAS_NAMES[@]} -eq 0 ]; then
+        warn "No aliases to remove" >&2
+        return 0
+    fi
+
+    local name="$preset_name"
+    if [ -z "$name" ]; then
+        section "Remove System Alias" >&2
+        local display_items=() i
+        for ((i = 0; i < ${#_ALIAS_NAMES[@]}; i++)); do
+            local c="${_ALIAS_COMMANDS[$i]}"
+            if [ ${#c} -gt 30 ]; then
+                c="${c:0:30}…"
+            fi
+            display_items+=("${_ALIAS_NAMES[$i]} → ${c}")
+        done
+        local picked
+        picked="$(menu_pick "Pick alias to remove" "${display_items[@]}")" || return 0
+        name="${_ALIAS_NAMES[$((picked - 1))]}"
+    fi
+
+    local idx
+    idx="$(_alias_find "$name")"
+    if [ "$idx" = "-1" ]; then
+        err "Alias '$name' not found"
+    fi
+
+    # Show alias detail
+    {
+        echo "  Alias:    $name"
+        printf '  Command:  %s\n' "${_ALIAS_COMMANDS[$idx]}"
+        echo >&2
+    } >&2
+
+    if ! confirm "Remove alias '$name'? This cannot be undone." n; then
+        log "Cancelled." >&2
+        return 0
+    fi
+
+    _alias_load
+    local new_names=() new_commands=() i
+    for ((i = 0; i < ${#_ALIAS_NAMES[@]}; i++)); do
+        if [ "${_ALIAS_NAMES[$i]}" != "$name" ]; then
+            new_names+=("${_ALIAS_NAMES[$i]}")
+            new_commands+=("${_ALIAS_COMMANDS[$i]}")
+        fi
+    done
+    _ALIAS_NAMES=("${new_names[@]+"${new_names[@]}"}")
+    _ALIAS_COMMANDS=("${new_commands[@]+"${new_commands[@]}"}")
+    _alias_save
+    _alias_sync
+    log "Alias '$name' removed — script deleted from $(_wrapper_path "$name")." >&2
+    log "If the name still autocompletes stale in this shell, run: hash -r" >&2
+}
+
+# ── Usage ──────────────────────────────────────────────────────
+
+usage() {
+    cat <<'EOF'
+Usage: pos system alias [subcommand] [args]
+
+Manage persistent command aliases — create, edit, remove, list, and show
+named aliases. Each alias maps a name to a shell command, materialized as
+an executable wrapper script in ~/.local/bin/.
+
+Subcommands:
+  (no args)         Interactive menu
+  create [name]     Create a new alias (interactive prompts)
+  edit [name]       Edit an existing alias (interactive, Enter = keep)
+  remove [name]     Remove an alias (with confirmation)
+  list              List all aliases (non-interactive, machine-readable)
+  show <name>       Show one alias's details
+
+Activation: every alias is materialized as an executable script at
+~/.local/bin/<name>, synced automatically on every invocation. Changes are
+live on the next invocation.
+
+Options:
+  -h|--help         Show this help.
+
+Examples:
+  pos system alias                     # interactive menu
+  pos system alias list                # show all aliases
+  pos system alias create              # interactive create
+  pos system alias create restart-dns   # create 'restart-dns' alias
+  pos system alias edit restart-dns     # edit the 'restart-dns' alias
+  pos system alias remove restart-dns   # remove 'restart-dns' (with confirm)
+  pos system alias show restart-dns     # show alias details
+EOF
+    exit 0
+}
+
+# ── Main dispatch ──────────────────────────────────────────────
+# Every subcommand syncs first: artifacts always equal ENV truth before any
+# subcommand logic runs.
+
+case "${1:-}" in
+    -h|--help) usage ;;
+    create)  shift; _alias_sync; _alias_create "${1:-}" ;;
+    edit)    shift; _alias_sync; _alias_edit "${1:-}" ;;
+    remove)  shift; _alias_sync; _alias_remove "${1:-}" ;;
+    list)    _alias_sync; _alias_list ;;
+    show)
+        [ -n "${2:-}" ] || err "Usage: pos system alias show <name>"
+        _alias_sync
+        _alias_show "$2"
+        ;;
+    "") _alias_sync; _alias_menu ;;
+    *)  err "Unknown subcommand '$1' (use -h for help)" ;;
+esac
@@ -55,7 +55,8 @@ done
 # ── pos-owned installed files (single source of truth, mirrors install.sh) ──
 # lib/*.sh list shipped by install.sh phase 2 to /usr/local/bin.
 POS_LIBS=(common.sh flags.sh notify.sh entertainment-lib.sh scheduler-lib.sh config-ui.sh \
-    user-timers-lib.sh entertainment-plugin-lib.sh usb-lib.sh share-lib.sh menu-lib.sh registry.sh)
+    user-timers-lib.sh entertainment-plugin-lib.sh usb-lib.sh share-lib.sh menu-lib.sh registry.sh \
+    yt-lib.sh bank-lib.sh)
 # Exact lines postinstall.sh appends to ~/.bashrc.
 PATH_LINE='export PATH="/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:$HOME/.local/bin:$PATH"'
 COMPLETION_LINE='source /usr/local/share/bash-completion/completions/pos.bash 2>/dev/null || true'
@@ -49,9 +49,11 @@ _pos_subcmds[share-nfs-client]="mount unmount list persist unpersist menu"
 _pos_subcmds[share-nfs-server]="status share unshare list reload enable disable menu"
 _pos_subcmds[share-smb-client]="mount unmount list persist unpersist menu"
 _pos_subcmds[share-smb-server]="status share unshare list adduser deluser reload enable disable menu"
+_pos_subcmds[system-alias]="create edit remove list show"
 _pos_subcmds[system-backup]="menu"
 _pos_subcmds[system-schedule]="run list config enable disable status migrate menu"
 _pos_subcmds[ai]="ask chat sessions capture models providers llamacpp alias gemini hf openrouter server"
+_pos_subcmds[bank]="list add show run edit remove"
 # GEN:END possubcmds
 # GEN:START posconfigscopes
 declare -a _pos_config_scopes=(ai compose entertainment grab matrix notify scrcpy system telegram ytsync)
@@ -113,7 +115,14 @@ _pos() {

    # ── Helpers ────────────────────────────────────────────────
    _pos_complete_categories() {
-        COMPREPLY=($(compgen -W "${!cat_cmds[*]} config" -- "$cur"))
+        local solos=()
+        for cmd in "${all_cmds[@]}"; do
+            local cat_c="${cmd%%-*}"
+            if [ "$cat_c" = "$cmd" ] && [ -z "${cat_cmds[$cmd]:-}" ]; then
+                solos+=("$cmd")
+            fi
+        done
+        COMPREPLY=($(compgen -W "${!cat_cmds[*]} ${solos[*]}" -- "$cur"))
    }

    _pos_complete_subcats() {
@@ -229,7 +238,13 @@ _pos() {
        3)
            case "${words[1]}" in
                config) _pos_config_scopes ;;
-                *) _pos_complete_subcats ;;
+                *)
+                    if [[ "${words[1]}" == *-* ]]; then
+                        _pos_complete_subcats
+                    else
+                        _pos_complete_tool "${words[1]}"
+                    fi
+                    ;;
            esac
            ;;
        4)
@@ -175,7 +175,7 @@ if should_run 2 scripts; then
    done
    lib_count=0
    lib_names=""
-    for lf in common.sh flags.sh notify.sh entertainment-lib.sh scheduler-lib.sh config-ui.sh user-timers-lib.sh entertainment-plugin-lib.sh usb-lib.sh share-lib.sh menu-lib.sh registry.sh; do
+    for lf in common.sh flags.sh notify.sh entertainment-lib.sh scheduler-lib.sh config-ui.sh user-timers-lib.sh entertainment-plugin-lib.sh usb-lib.sh share-lib.sh menu-lib.sh registry.sh yt-lib.sh bank-lib.sh; do
        run sudo install -m 644 "lib/$lf" "/usr/local/bin/$lf"
        lib_count=$((lib_count + 1))
        lib_names+="$lf "
@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# lib/bank-lib.sh — shared storage helpers for the Command Bank.
+# Sourced by bin/pos-bank. Uses err() from lib/common.sh.
+#
+# Storage: ~/.config/linux_post_install/bank.env
+# Format:  name|description|command
+# v2: commands with real newlines are saved with \\ (backslash) and \n
+#     (newline) escapes; files written by v1 have no marker and load raw.
+#
+# Contracts:
+#   * Defines ONLY bank_* functions — sourcing never clobbers a tool's helpers.
+#   * Requires common.sh to be sourced by the CALLER.
+#   * NEVER exits — return codes only.
+#   * Performs NO interactive prompts (those stay in bin/pos-bank).
+
+CONFIG_DIR="${CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/linux_post_install}"
+BANK_FILE="${BANK_FILE:-${CONFIG_DIR}/bank.env}"
+
+# ── Load ────────────────────────────────────────────────────────
+# Populate parallel arrays: BANK_NAMES, BANK_DESCS, BANK_CMDS.
+bank_load() {
+    BANK_NAMES=(); BANK_DESCS=(); BANK_CMDS=()
+    [ -f "$BANK_FILE" ] || return 0
+
+    local line name desc cmd v2=0
+    while IFS= read -r line; do
+        [[ "$line" =~ ^[[:space:]]*# ]] && { [[ "$line" == *"BANK_VERSION: 2"* ]] && v2=1; continue; }
+        [[ -z "${line// /}" ]] && continue
+        IFS='|' read -r name desc cmd <<< "$line"
+        [[ -z "$name" ]] && continue
+        [ "$v2" -eq 1 ] && cmd="$(printf '%b' "$cmd")"
+        BANK_NAMES+=("$name")
+        BANK_DESCS+=("${desc:-}")
+        BANK_CMDS+=("${cmd:-}")
+    done < "$BANK_FILE"
+}
+
+# ── Save ────────────────────────────────────────────────────────
+# Atomic overwrite from parallel arrays.
+bank_save() {
+    local dir
+    dir="$(dirname "$BANK_FILE")"
+    mkdir -p "$dir"
+    local tmp
+    tmp="$(mktemp "${dir}/.bank.XXXXXX")"
+    {
+        printf '%s\n' "# Command Bank — managed by pos bank (do not hand-edit)"
+        printf '%s\n' "# Format: name|description|command (\\n = escaped newline in command)"
+        printf '%s\n' "# BANK_VERSION: 2"
+        local i
+        for ((i = 0; i < ${#BANK_NAMES[@]}; i++)); do
+            local cmd="${BANK_CMDS[$i]}"
+            # Escape: every backslash → \\, every real newline → \n (keeps one record per physical line)
+            cmd="${cmd//\\/\\\\}"
+            cmd="${cmd//$'\n'/\\n}"
+            printf '%s|%s|%s\n' "${BANK_NAMES[$i]}" "${BANK_DESCS[$i]}" "$cmd"
+        done
+    } > "$tmp"
+    chmod 600 "$tmp"
+    mv "$tmp" "$BANK_FILE"
+}
+
+# ── Add ─────────────────────────────────────────────────────────
+bank_add() {
+    local name="$1" desc="$2" cmd="$3"
+    bank_load
+    local i
+    for ((i = 0; i < ${#BANK_NAMES[@]}; i++)); do
+        [[ "${BANK_NAMES[$i]}" == "$name" ]] && return 1
+    done
+    BANK_NAMES+=("$name")
+    BANK_DESCS+=("$desc")
+    BANK_CMDS+=("$cmd")
+    bank_save
+}
+
+# ── Remove ──────────────────────────────────────────────────────
+bank_remove() {
+    local name="$1"
+    bank_load
+    local found=0 i
+    for ((i = 0; i < ${#BANK_NAMES[@]}; i++)); do
+        if [[ "${BANK_NAMES[$i]}" == "$name" ]]; then
+            unset 'BANK_NAMES[i]'
+            unset 'BANK_DESCS[i]'
+            unset 'BANK_CMDS[i]'
+            found=1
+            break
+        fi
+    done
+    [[ "$found" -eq 1 ]] || return 1
+    # Re-index arrays (unset leaves gaps)
+    BANK_NAMES=("${BANK_NAMES[@]}")
+    BANK_DESCS=("${BANK_DESCS[@]}")
+    BANK_CMDS=("${BANK_CMDS[@]}")
+    bank_save
+}
+
+# ── Update ──────────────────────────────────────────────────────
+bank_update() {
+    local name="$1" desc="$2" cmd="$3"
+    bank_load
+    local i
+    for ((i = 0; i < ${#BANK_NAMES[@]}; i++)); do
+        if [[ "${BANK_NAMES[$i]}" == "$name" ]]; then
+            BANK_DESCS[$i]="$desc"
+            BANK_CMDS[$i]="$cmd"
+            bank_save
+            return 0
+        fi
+    done
+    return 1
+}
+
+# ── Find (by name) ──────────────────────────────────────────────
+# Sets BANK_IDX. Returns 0 if found, 1 if not.
+bank_find() {
+    local name="$1"
+    bank_load
+    local i
+    for ((i = 0; i < ${#BANK_NAMES[@]}; i++)); do
+        if [[ "${BANK_NAMES[$i]}" == "$name" ]]; then
+            BANK_IDX=$i
+            return 0
+        fi
+    done
+    return 1
+}
+
+# ── Get (by name) ───────────────────────────────────────────────
+# Outputs: name\tdescription\tcommand (tab-separated).
+bank_get() {
+    local name="$1"
+    bank_find "$name" || return 1
+    printf '%s\t%s\t%s\n' "${BANK_NAMES[$BANK_IDX]}" "${BANK_DESCS[$BANK_IDX]}" "${BANK_CMDS[$BANK_IDX]}"
+}
+
+# ── List names ──────────────────────────────────────────────────
+bank_list_names() {
+    bank_load
+    local i
+    for ((i = 0; i < ${#BANK_NAMES[@]}; i++)); do
+        printf '%s\n' "${BANK_NAMES[$i]}"
+    done
+}
+
+# ── Count ───────────────────────────────────────────────────────
+bank_count() {
+    bank_load
+    echo "${#BANK_NAMES[@]}"
+}
+
+# ── Validate name ───────────────────────────────────────────────
+bank_valid_name() {
+    [[ "$1" =~ ^[a-zA-Z][a-zA-Z0-9_-]*$ ]]
+}
+
+# ── Extract {param} names from a command template ───────────────
+_extract_params() {
+    local cmd="$1"
+    grep -oE '\{[a-zA-Z_][a-zA-Z0-9_]*\}' <<< "$cmd" 2>/dev/null | \
+        sed 's/[{}]//g' | \
+        awk '!seen[$0]++' || true
+}
+
+# ── Substitute {param} with quoted values ───────────────────────
+# Usage: _substitute_params "cmd template" "key1=val1" "key2=val2" ...
+# Uses awk to build quoted replacements safely, avoiding bash quote-nesting.
+_substitute_params() {
+    local cmd="$1"; shift
+    # Build a sed expression: for each key=val, replace {key} with "val"
+    local sed_expr=""
+    while [ $# -gt 0 ]; do
+        local key="${1%%=*}"
+        local val="${1#*=}"
+        # Escape sed special chars in the value
+        val="${val//\\/\\\\}"
+        val="${val//\//\\/}"
+        sed_expr+="s/{${key}}/\"${val}\"/g; "
+        shift
+    done
+    [ -n "$sed_expr" ] && printf '%s' "$cmd" | sed "$sed_expr" || printf '%s' "$cmd"
+}
@@ -0,0 +1,22 @@
+# Decision: lib-registration standard is a 3-surface symmetry (install.sh + POS_LIBS + docs)
+
+## Finding (2026-09-12, MAINTENANCE_COMPLETE)
+
+lib/bank-lib.sh (added 41efc91 feat: pos bank) was never registered in install.sh's
+phase-2 lib copy list, bin/pos-system-uninstall's POS_LIBS, or the hand-maintained docs.
+lib/yt-lib.sh had been added to install.sh (0b76d4d) but missed POS_LIBS. Result: after
+`./install.sh`, `pos bank` failed with `/usr/local/bin/bank-lib.sh: No such file or directory`,
+and uninstall would leave stale yt-lib.sh. The symmetry gate tests/t-uninstall-manifest.sh
+(set-equality of the two lists) was failing.
+
+## Established standard (restored)
+
+Every lib/ file sourced by a bin/ tool MUST be registered in all THREE places:
+1. install.sh phase-2 lib copy loop (`for lf in …; do`) → ships to /usr/local/bin,
+2. bin/pos-system-uninstall `POS_LIBS` array (same set, backslash-continuation style),
+3. hand-maintained docs: DOC/SCRIPTS.md phase-2 table row + DOC/AGENT_Context_Project.md
+   phase-2 lib list AND its hand-maintained filetable row (above GEN:START filetable,
+   with real `wc -l` count).
+
+Validator: tests/t-uninstall-manifest.sh (must stay green; it enforces set equality and
+that every listed lib exists). Never edit GEN:START/GEN:END blocks by hand — run make gen.
@@ -156,6 +156,11 @@ if [ -d systemd ] && [ -n "$(ls -A systemd/*.service 2>/dev/null)" ]; then
            warn "usb-automount feature not installed — skipping usb-automount.service (run ./install.sh --feature)"
            continue
        fi
+        # ssh-agent.service — gated on ssh-agent flag
+        if [ "$svc_name" = "ssh-agent.service" ] && ! flag_is_set ssh-agent; then
+            warn "ssh-agent feature not installed — skipping ssh-agent.service (run ./install.sh --feature)"
+            continue
+        fi
        run sudo systemctl enable --now "$svc_name" 2>/dev/null || \
            run sudo systemctl enable "$svc_name"
        log "service enabled: $svc_name"
@@ -56,4 +56,5 @@ silently.
 | `t-install-version.sh` | install.sh version gate: match→skip, mismatch→proceed, --force bypass, dry-run variant, flag write, numeric comparison |
 | `t-share-mountpoint.sh` | share-client `ask_mountpoint` UX: existing/new/declined/rejected paths, confirm gate, mkdir side effects, non-TTY stdin contract, static `n`→`t` guards |
 | `t-pos-media-yt.sh` | unified `pos media yt` suite: dispatcher + forwarder resolution, shared yt-lib helpers, yt-mp3/mp4/grab/subtitles flags, dry-run deps, `YT_OUT_DIR` seam, `GRAB_DEFAULT` config, negative controls (unsafe-URL no-expansion, `--lang en,ar` single arg, txt timestamp-stripping) |
-| `t-telegram-listener-singleton.sh` | Telegram listener single-instance guard: first `--run` acquires the flock, second `--run` fails fast with the exact message, lock auto-releases so the next start is clean, `--status` reports the lock state |
+| `t-telegram-listener-singleton.sh` | Telegram listener single-instance guard: first `--run` acquires the flock, second `--run` fails fast with the exact message, lock auto-releases so the next start is clean, `--status` reports the lock state |
+| `t-bank.sh` | Command Bank: bank-lib.sh unit tests (add/remove/update/find/get/list/count/valid/extract_params/substitute_params, multiline `\n` storage round-trip, literal-`\n` escape round-trip, v1 backward compat) + pos-bank CLI integration (help, list, add, show, run, remove, params, invalid name, multiline show/run) |
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# tests/bank-test-helper.sh — minimal shim that sources bank-lib.sh for unit
+# testing.  Provides a stub `err()` so bank-lib.sh can load without the full
+# common.sh / menu-lib.sh dependency chain.
+set -euo pipefail
+
+# Stub err() — bank-lib.sh is contractually "never exits" but bank_valid_name
+# callers sometimes chain via `|| err …`.  This version returns 1 so the test
+# harness can assert rc.
+err() { printf 'ERROR: %s\n' "$*" >&2; return 1; }
+
+# Source the library under test.
+source "$ROOT/lib/bank-lib.sh"
@@ -0,0 +1,467 @@
+#!/usr/bin/env bash
+set -euo pipefail
+# t-bank.sh — Command Bank feature: bank-lib.sh unit tests + pos-bank CLI
+# integration tests.
+#
+# Storage contract: pipe-delimited name|description|command in $BANK_FILE.
+# Parameter syntax: {param} placeholders in command templates.
+
+run_test() {
+    local sandbox helper
+    sandbox="$(mksandbox bank)"
+    helper="$sandbox/helper.sh"
+
+    # ── Build a sourced helper that gives us bank-lib functions ──
+    cat > "$helper" <<'HELPER'
+source "$ROOT/tests/bank-test-helper.sh"
+HELPER
+
+    # ═══════════════════════════════════════════════════════════════
+    # Part A: bank-lib.sh unit tests
+    # ═══════════════════════════════════════════════════════════════
+
+    # A1: bank_add + bank_load — add two entries, verify arrays
+    (
+        BANK_FILE="$sandbox/a1.bank.env"
+        : > "$BANK_FILE"
+        source "$helper"
+        bank_add "deploy" "Deploy to prod" "ssh prod 'cd /app && git pull'"
+        bank_add "backup" "Backup database" "pg_dump mydb | gzip > /tmp/db.sql.gz"
+        bank_load
+        # Check arrays
+        [ "${#BANK_NAMES[@]}" -eq 2 ] || { echo "FAIL A1: expected 2 names, got ${#BANK_NAMES[@]}"; exit 1; }
+        [ "${BANK_NAMES[0]}" = "deploy" ] || { echo "FAIL A1: name[0] mismatch"; exit 1; }
+        [ "${BANK_DESCS[0]}" = "Deploy to prod" ] || { echo "FAIL A1: desc[0] mismatch"; exit 1; }
+        [ "${BANK_CMDS[1]}" = "pg_dump mydb | gzip > /tmp/db.sql.gz" ] || { echo "FAIL A1: cmd[1] mismatch"; exit 1; }
+        echo "PASS A1: bank_add + bank_load populates arrays correctly"
+    ) && printf '  PASS  bank_add + bank_load populates arrays\n' \
+      || printf '  FAIL  bank_add + bank_load populates arrays\n'
+
+    # A2: bank_add duplicate — returns rc 1
+    (
+        BANK_FILE="$sandbox/a2.bank.env"
+        printf 'old|Old cmd|echo old\n' > "$BANK_FILE"
+        source "$helper"
+        bank_add "old" "New desc" "echo new"
+        exit $?
+    )
+    check_rc "bank_add duplicate returns rc 1" 1 $?
+
+    # A3: bank_remove — remove entry, verify gone
+    (
+        BANK_FILE="$sandbox/a3.bank.env"
+        printf 'aaa|desc a|cmd a\nbbb|desc b|cmd b\nccc|desc c|cmd c\n' > "$BANK_FILE"
+        source "$helper"
+        bank_remove "bbb"
+        bank_load
+        [ "${#BANK_NAMES[@]}" -eq 2 ] || { echo "FAIL A3: expected 2, got ${#BANK_NAMES[@]}"; exit 1; }
+        [ "${BANK_NAMES[0]}" = "aaa" ] || { echo "FAIL A3: name[0] mismatch"; exit 1; }
+        [ "${BANK_NAMES[1]}" = "ccc" ] || { echo "FAIL A3: name[1] mismatch"; exit 1; }
+        # Verify file on disk
+        grep -q '^bbb|' "$BANK_FILE" && { echo "FAIL A3: bbb still in file"; exit 1; }
+        echo "PASS A3: bank_remove"
+    ) && printf '  PASS  bank_remove removes entry\n' \
+      || printf '  FAIL  bank_remove removes entry\n'
+
+    # A4: bank_remove missing — returns rc 1
+    (
+        BANK_FILE="$sandbox/a4.bank.env"
+        printf 'xxx|desc|cmd\n' > "$BANK_FILE"
+        source "$helper"
+        bank_remove "nonexistent"
+        exit $?
+    )
+    check_rc "bank_remove missing returns rc 1" 1 $?
+
+    # A5: bank_update — update entry, verify changed
+    (
+        BANK_FILE="$sandbox/a5.bank.env"
+        printf 'mycmd|old desc|old cmd\n' > "$BANK_FILE"
+        source "$helper"
+        bank_update "mycmd" "new desc" "new cmd"
+        bank_load
+        [ "${BANK_DESCS[0]}" = "new desc" ] || { echo "FAIL A5: desc mismatch"; exit 1; }
+        [ "${BANK_CMDS[0]}" = "new cmd" ] || { echo "FAIL A5: cmd mismatch"; exit 1; }
+        # Verify on disk
+        grep -q 'new desc|new cmd' "$BANK_FILE" || { echo "FAIL A5: not persisted"; exit 1; }
+        echo "PASS A5: bank_update"
+    ) && printf '  PASS  bank_update updates entry\n' \
+      || printf '  FAIL  bank_update updates entry\n'
+
+    # A6: bank_update missing — returns rc 1
+    (
+        BANK_FILE="$sandbox/a6.bank.env"
+        printf 'exists|desc|cmd\n' > "$BANK_FILE"
+        source "$helper"
+        bank_update "nope" "desc" "cmd"
+        exit $?
+    )
+    check_rc "bank_update missing returns rc 1" 1 $?
+
+    # A7: bank_find — found sets BANK_IDX, not-found returns 1
+    (
+        BANK_FILE="$sandbox/a7.bank.env"
+        printf 'alpha|d1|c1\nbeta|d2|c2\ngamma|d3|c3\n' > "$BANK_FILE"
+        source "$helper"
+        bank_find "beta"
+        [ "${BANK_IDX:-}" = "1" ] || { echo "FAIL A7: expected BANK_IDX=1, got ${BANK_IDX:-unset}"; exit 1; }
+        bank_find "nonexistent" && { echo "FAIL A7: should return 1 for missing"; exit 1; }
+        echo "PASS A7: bank_find"
+    ) && printf '  PASS  bank_find sets BANK_IDX / returns 1\n' \
+      || printf '  FAIL  bank_find sets BANK_IDX / returns 1\n'
+
+    # A8: bank_get — returns tab-separated output
+    (
+        BANK_FILE="$sandbox/a8.bank.env"
+        printf 'mytool|My Tool|echo hello\n' > "$BANK_FILE"
+        source "$helper"
+        local out
+        out="$(bank_get "mytool")"
+        [ "$out" = "mytool	My Tool	echo hello" ] || { echo "FAIL A8: unexpected output [$out]"; exit 1; }
+        echo "PASS A8: bank_get"
+    ) && printf '  PASS  bank_get returns tab-separated output\n' \
+      || printf '  FAIL  bank_get returns tab-separated output\n'
+
+    # A9: bank_list_names — lists all names
+    (
+        BANK_FILE="$sandbox/a9.bank.env"
+        printf 'one|x|y\ntwo|a|b\nthree|c|d\n' > "$BANK_FILE"
+        source "$helper"
+        local names
+        names="$(bank_list_names)"
+        local expected
+        expected="$(printf 'one\ntwo\nthree')"
+        [ "$names" = "$expected" ] || { echo "FAIL A9: expected [$expected] got [$names]"; exit 1; }
+        echo "PASS A9: bank_list_names"
+    ) && printf '  PASS  bank_list_names lists all names\n' \
+      || printf '  FAIL  bank_list_names lists all names\n'
+
+    # A10: bank_count — returns correct count
+    (
+        BANK_FILE="$sandbox/a10.bank.env"
+        printf 'a|1|2\nb|3|4\nc|5|6\nd|7|8\n' > "$BANK_FILE"
+        source "$helper"
+        local cnt
+        cnt="$(bank_count)"
+        [ "$cnt" -eq 4 ] || { echo "FAIL A10: expected 4, got $cnt"; exit 1; }
+        echo "PASS A10: bank_count"
+    ) && printf '  PASS  bank_count returns correct count\n' \
+      || printf '  FAIL  bank_count returns correct count\n'
+
+    # A11: bank_count — empty file returns 0
+    (
+        BANK_FILE="$sandbox/a11.bank.env"
+        : > "$BANK_FILE"
+        source "$helper"
+        local cnt
+        cnt="$(bank_count)"
+        [ "$cnt" -eq 0 ] || { echo "FAIL A11: expected 0, got $cnt"; exit 1; }
+        echo "PASS A11: bank_count empty"
+    ) && printf '  PASS  bank_count returns 0 for empty file\n' \
+      || printf '  FAIL  bank_count returns 0 for empty file\n'
+
+    # A12: bank_valid_name — valid names pass
+    (
+        source "$helper"
+        local fail=0
+        for n in "deploy" "my-cmd" "test_123" "A" "z9"; do
+            bank_valid_name "$n" || { fail=1; printf 'FAIL A12: %s should be valid\n' "$n" >&2; }
+        done
+        [ "$fail" -eq 0 ] || exit 1
+        echo "PASS A12: bank_valid_name accepts valid names"
+    ) && printf '  PASS  bank_valid_name accepts valid names\n' \
+      || printf '  FAIL  bank_valid_name accepts valid names\n'
+
+    # A13: bank_valid_name — invalid names fail
+    (
+        source "$helper"
+        local fail=0
+        for n in "" "1abc" "-start" "_under" "has space" "special!"; do
+            bank_valid_name "$n" && { fail=1; printf 'FAIL A13: %s should be invalid\n' "$n" >&2; }
+        done
+        [ "$fail" -eq 0 ] || exit 1
+        echo "PASS A13: bank_valid_name rejects invalid names"
+    ) && printf '  PASS  bank_valid_name rejects invalid names\n' \
+      || printf '  FAIL  bank_valid_name rejects invalid names\n'
+
+    # A14: _extract_params — extracts {param} names from template
+    (
+        source "$helper"
+        local params
+        params="$(_extract_params "echo {name} {path}")"
+        local expected
+        expected="$(printf 'name\npath')"
+        [ "$params" = "$expected" ] || { echo "FAIL A14: expected [$expected] got [$params]"; exit 1; }
+        echo "PASS A14: _extract_params"
+    ) && printf '  PASS  _extract_params extracts param names\n' \
+      || printf '  FAIL  _extract_params extracts param names\n'
+
+    # A15: _extract_params — no params returns empty
+    (
+        source "$helper"
+        local params
+        params="$(_extract_params "echo hello world")"
+        [ -z "$params" ] || { echo "FAIL A15: expected empty, got [$params]"; exit 1; }
+        echo "PASS A15: _extract_params empty"
+    ) && printf '  PASS  _extract_params returns empty for no params\n' \
+      || printf '  FAIL  _extract_params returns empty for no params\n'
+
+    # A16: _extract_params — deduplicates repeated params
+    (
+        source "$helper"
+        local params
+        params="$(_extract_params "cp {src} {dst} && ls {src}")"
+        local count
+        count="$(printf '%s' "$params" | grep -c '^src$' || true)"
+        [ "$count" -eq 1 ] || { echo "FAIL A16: expected 1 occurrence of src, got $count"; exit 1; }
+        echo "PASS A16: _extract_params deduplicates"
+    ) && printf '  PASS  _extract_params deduplicates\n' \
+      || printf '  FAIL  _extract_params deduplicates\n'
+
+    # A17: _substitute_params — replaces {param} with quoted values
+    (
+        source "$helper"
+        local result
+        result="$(_substitute_params "scp {file} user@host:{dest}" "file=/tmp/data.csv" "dest=/var/data")"
+        local expected='scp "/tmp/data.csv" user@host:"/var/data"'
+        [ "$result" = "$expected" ] || { echo "FAIL A17: expected [$expected] got [$result]"; exit 1; }
+        echo "PASS A17: _substitute_params"
+    ) && printf '  PASS  _substitute_params replaces params\n' \
+      || printf '  FAIL  _substitute_params replaces params\n'
+
+    # A18: bank_load — comments and blank lines are skipped
+    (
+        BANK_FILE="$sandbox/a18.bank.env"
+        cat > "$BANK_FILE" <<'BANK'
+# Command Bank — managed by pos bank (do not hand-edit)
+# Format: name|description|command
+
+real|Real command|echo real
+# another comment
+
+  # indented comment
+  
+BANK
+        source "$helper"
+        bank_load
+        [ "${#BANK_NAMES[@]}" -eq 1 ] || { echo "FAIL A18: expected 1, got ${#BANK_NAMES[@]}"; exit 1; }
+        [ "${BANK_NAMES[0]}" = "real" ] || { echo "FAIL A18: name mismatch"; exit 1; }
+        echo "PASS A18: bank_load skips comments and blanks"
+    ) && printf '  PASS  bank_load skips comments and blank lines\n' \
+      || printf '  FAIL  bank_load skips comments and blank lines\n'
+
+    # A19: multiline command storage round-trip — escapes \n, single record line
+    (
+        BANK_FILE="$sandbox/a19.bank.env"
+        : > "$BANK_FILE"
+        source "$helper"
+        script="$(cat <<'SCRIPT'
+#!/usr/bin/env bash
+for tag in one two; do
+    out="$(printf '%s' "$tag" | tr 'a-z' 'A-Z')"
+    echo "tag=${tag} out=${out} done"
+done
+SCRIPT
+)"
+        bank_add "ml" "Multiline demo" "$script"
+        bank_load
+        [ "${#BANK_NAMES[@]}" -eq 1 ] || { echo "FAIL A19: expected 1 entry, got ${#BANK_NAMES[@]}"; exit 1; }
+        [ "${BANK_CMDS[0]}" = "$script" ] || { echo "FAIL A19: command bytes differ"; exit 1; }
+        rec_lines="$(grep -c '^ml|' "$BANK_FILE" || true)"
+        [ "$rec_lines" -eq 1 ] || { echo "FAIL A19: expected 1 record line, got $rec_lines"; exit 1; }
+        [ "$(wc -l < "$BANK_FILE")" -eq 4 ] || { echo "FAIL A19: file has bogus physical lines"; exit 1; }
+        grep -q '\\n' "$BANK_FILE" || { echo "FAIL A19: missing \\n escape in file"; exit 1; }
+        echo "PASS A19: multiline round-trip"
+    ) && printf '  PASS  multiline storage round-trip (one record line, \\n escapes)\n' \
+      || printf '  FAIL  multiline storage round-trip (one record line, \\n escapes)\n'
+
+    # A20: literal \n (backslash-n) in command round-trips literally — NOT a real newline
+    (
+        BANK_FILE="$sandbox/a20.bank.env"
+        : > "$BANK_FILE"
+        source "$helper"
+        esc="$(printf '%s' "printf 'a\\nb'")"
+        bank_add "esc" "Escapes" "$esc"
+        bank_load
+        [ "${BANK_CMDS[0]}" = "$esc" ] || { echo "FAIL A20: literal \\n not preserved [${BANK_CMDS[0]}]"; exit 1; }
+        case "${BANK_CMDS[0]}" in
+            *$'\n'*) echo "FAIL A20: decoded literal \\n into a real newline"; exit 1 ;;
+        esac
+        echo "PASS A20: literal \\n round-trip"
+    ) && printf '  PASS  literal \\n command round-trips literally\n' \
+      || printf '  FAIL  literal \\n command round-trips literally\n'
+
+    # A21: old-format file (no BANK_VERSION marker) keeps raw backslashes — no %b decode
+    (
+        BANK_FILE="$sandbox/a21.bank.env"
+        cat > "$BANK_FILE" <<'BANK'
+# Command Bank — managed by pos bank (do not hand-edit)
+# Format: name|description|command
+raw|Raw echo|echo 'a\b'
+BANK
+        source "$helper"
+        bank_load
+        expected="$(printf '%s' "echo 'a\\b'")"
+        [ "${BANK_CMDS[0]}" = "$expected" ] || { echo "FAIL A21: raw backslash changed [${BANK_CMDS[0]}]"; exit 1; }
+        echo "PASS A21: old-format raw backslash"
+    ) && printf '  PASS  old-format file keeps raw backslash (no decode)\n' \
+      || printf '  FAIL  old-format file keeps raw backslash (no decode)\n'
+
+    # A22: old-format entry survives a re-save byte-identically (escape + decode round-trip)
+    (
+        BANK_FILE="$sandbox/a22.bank.env"
+        cat > "$BANK_FILE" <<'BANK'
+# Command Bank — managed by pos bank (do not hand-edit)
+# Format: name|description|command
+ts-google|Tailscale Google|tailscale status --json >/tmp/ts.json && grep -q '"ExitNodeStatus":null' /tmp/ts.json && tailscale set --exit-node=google || tailscale set --exit-node=
+BANK
+        source "$helper"
+        bank_load
+        orig="${BANK_CMDS[0]}"
+        bank_add "new-cmd" "New entry" "echo ok"
+        bank_load
+        [ "${#BANK_NAMES[@]}" -eq 2 ] || { echo "FAIL A22: expected 2 entries, got ${#BANK_NAMES[@]}"; exit 1; }
+        [ "${BANK_CMDS[0]}" = "$orig" ] || { echo "FAIL A22: old entry changed after re-save"; exit 1; }
+        [ "${BANK_CMDS[1]}" = "echo ok" ] || { echo "FAIL A22: new entry missing"; exit 1; }
+        echo "PASS A22: old-format re-save round-trip"
+    ) && printf '  PASS  old-format entry round-trips through re-save\n' \
+      || printf '  FAIL  old-format entry round-trips through re-save\n'
+
+    # ═══════════════════════════════════════════════════════════════
+    # Part B: pos-bank CLI integration tests
+    # ═══════════════════════════════════════════════════════════════
+
+    local pos_bank="$ROOT/bin/pos-bank"
+
+    # B1: pos bank --help shows usage
+    test_run env BANK_FILE="$sandbox/b1.bank.env" "$pos_bank" --help
+    check_rc "pos bank --help exits 0" 0 "$TR_RC"
+    check_contains "pos bank --help shows Usage" "Usage:" "$TR_OUT"
+    check_contains "pos bank --help mentions subcommands" "Subcommands:" "$TR_OUT"
+
+    # B2: pos bank list on empty bank shows empty message
+    : > "$sandbox/b2.bank.env"
+    test_run env BANK_FILE="$sandbox/b2.bank.env" "$pos_bank" list
+    check_rc "pos bank list empty exits 0" 0 "$TR_RC"
+    check_contains "pos bank list empty message" "Command bank is empty" "$TR_OUT"
+
+    # B3: pos bank add — adds a command, verify in bank.env
+    : > "$sandbox/b3.bank.env"
+    test_run env BANK_FILE="$sandbox/b3.bank.env" "$pos_bank" add "disk-usage" "Check disk usage" "df -h"
+    check_rc "pos bank add exits 0" 0 "$TR_RC"
+    check_contains "pos bank add confirms" "Saved: disk-usage" "$TR_OUT"
+    # Verify the file
+    if grep -q '^disk-usage|Check disk usage|df -h$' "$sandbox/b3.bank.env"; then
+        printf '  PASS  pos bank add persists to bank.env\n'
+    else
+        printf '  FAIL  pos bank add did not persist to bank.env\n'
+    fi
+
+    # B4: pos bank add duplicate — fails
+    test_run env BANK_FILE="$sandbox/b3.bank.env" "$pos_bank" add "disk-usage" "dup" "echo dup"
+    check_not_contains "pos bank add duplicate errors" "0" "$TR_RC"
+    check_contains "pos bank add duplicate message" "already exists" "$TR_OUT"
+
+    # B5: pos bank show — shows command details
+    test_run env BANK_FILE="$sandbox/b3.bank.env" "$pos_bank" show "disk-usage"
+    check_rc "pos bank show exits 0" 0 "$TR_RC"
+    check_contains "pos bank show shows name" "Name: disk-usage" "$TR_OUT"
+    check_contains "pos bank show shows description" "Check disk usage" "$TR_OUT"
+    check_contains "pos bank show shows command" "df -h" "$TR_OUT"
+
+    # B6: pos bank show missing — fails
+    test_run env BANK_FILE="$sandbox/b3.bank.env" "$pos_bank" show "nonexistent"
+    check_not_contains "pos bank show missing exits non-zero" "0" "$TR_RC"
+    check_contains "pos bank show missing message" "not found" "$TR_OUT"
+
+    # B7: pos bank list after add — shows the entry
+    test_run env BANK_FILE="$sandbox/b3.bank.env" "$pos_bank" list
+    check_rc "pos bank list populated exits 0" 0 "$TR_RC"
+    check_contains "pos bank list shows header" "COMMAND BANK" "$TR_OUT"
+    check_contains "pos bank list shows entry" "disk-usage" "$TR_OUT"
+
+    # B8: pos bank remove — removes a command
+    test_run env BANK_FILE="$sandbox/b3.bank.env" "$pos_bank" remove "disk-usage"
+    check_rc "pos bank remove exits 0" 0 "$TR_RC"
+    check_contains "pos bank remove confirms" "Removed: disk-usage" "$TR_OUT"
+    # Verify gone
+    if grep -q '^disk-usage|' "$sandbox/b3.bank.env"; then
+        printf '  FAIL  pos bank remove did not delete from bank.env\n'
+    else
+        printf '  PASS  pos bank remove deletes from bank.env\n'
+    fi
+
+    # B9: pos bank remove missing — fails
+    : > "$sandbox/b9.bank.env"
+    test_run env BANK_FILE="$sandbox/b9.bank.env" "$pos_bank" remove "ghost"
+    check_not_contains "pos bank remove missing exits non-zero" "0" "$TR_RC"
+    check_contains "pos bank remove missing message" "not found" "$TR_OUT"
+
+    # B10: pos bank add with parameters — show lists them
+    : > "$sandbox/b10.bank.env"
+    test_run env BANK_FILE="$sandbox/b10.bank.env" "$pos_bank" add "convert" "Convert video" "ffmpeg -i {input} -q:v {quality} {output}"
+    check_rc "pos bank add with params exits 0" 0 "$TR_RC"
+    test_run env BANK_FILE="$sandbox/b10.bank.env" "$pos_bank" show "convert"
+    check_contains "show lists input param" "input" "$TR_OUT"
+    check_contains "show lists quality param" "quality" "$TR_OUT"
+    check_contains "show lists output param" "output" "$TR_OUT"
+
+    # B11: pos bank add invalid name — fails
+    : > "$sandbox/b11.bank.env"
+    test_run env BANK_FILE="$sandbox/b11.bank.env" "$pos_bank" add "1bad" "desc" "cmd"
+    check_not_contains "pos bank add invalid name exits non-zero" "0" "$TR_RC"
+    check_contains "pos bank add invalid name message" "Invalid name" "$TR_OUT"
+
+    # B12: pos bank run — executes a saved command (no params)
+    # Negative control: the old `local name="" -a cli_params=()` declaration
+    # crashed at line 150 before any output (rc != 0, no "Running:" line).
+    : > "$sandbox/b12.bank.env"
+    test_run env BANK_FILE="$sandbox/b12.bank.env" "$pos_bank" add "greet" "Greet" "echo bank-run-ok"
+    check_rc "pos bank add for run exits 0" 0 "$TR_RC"
+    test_run env BANK_FILE="$sandbox/b12.bank.env" "$pos_bank" run "greet"
+    check_rc "pos bank run executes saved command" 0 "$TR_RC"
+    check_contains "pos bank run logs the command" "Running: echo bank-run-ok" "$TR_OUT"
+    check_contains "pos bank run executes output" "bank-run-ok" "$TR_OUT"
+
+    # B13: pos bank run missing command — fails
+    test_run env BANK_FILE="$sandbox/b12.bank.env" "$pos_bank" run "ghost"
+    check_not_contains "pos bank run missing exits non-zero" "0" "$TR_RC"
+    check_contains "pos bank run missing message" "Command not found" "$TR_OUT"
+
+    # B14: pos bank run with params — CLI key=val substitution, no interactive prompt
+    : > "$sandbox/b14.bank.env"
+    test_run env BANK_FILE="$sandbox/b14.bank.env" "$pos_bank" add "echo-param" "Echo param" "echo hi {who}"
+    check_rc "pos bank add param exits 0" 0 "$TR_RC"
+    test_run env BANK_FILE="$sandbox/b14.bank.env" "$pos_bank" run "echo-param" "who=there"
+    check_rc "pos bank run with params exits 0" 0 "$TR_RC"
+    check_contains "pos bank run substitutes param" 'Running: echo hi "there"' "$TR_OUT"
+    check_contains "pos bank run executes substituted command" "hi there" "$TR_OUT"
+
+    # B15: pos bank add multiline + show — cmd_show retrieves the FULL script via arrays
+    # Negative control: bank_get + cut -f3 truncated the command at the first newline.
+    # (Brace-free script: {param} template detection would prompt on run in a non-TTY.)
+    : > "$sandbox/b15.bank.env"
+    ml_script="$(cat <<'SCRIPT'
+#!/usr/bin/env bash
+n=0
+while [ "$n" -lt 2 ]; do
+    n=$((n + 1))
+    echo "round $n: $(printf 'ok')"
+done
+SCRIPT
+)"
+    test_run env BANK_FILE="$sandbox/b15.bank.env" "$pos_bank" add "ml-demo" "Multiline demo" "$ml_script"
+    check_rc "pos bank add multiline exits 0" 0 "$TR_RC"
+    test_run env BANK_FILE="$sandbox/b15.bank.env" "$pos_bank" show "ml-demo"
+    check_rc "pos bank show multiline exits 0" 0 "$TR_RC"
+    check_contains "pos bank show prints script shebang" '#!/usr/bin/env bash' "$TR_OUT"
+    check_contains "pos bank show prints loop line" 'while [ "$n" -lt 2 ]; do' "$TR_OUT"
+    check_contains "pos bank show prints arithmetic line" 'n=$((n + 1))' "$TR_OUT"
+    check_contains "pos bank show prints substitution echo" 'echo "round $n: $(printf' "$TR_OUT"
+
+    # B16: pos bank run multiline — executes the WHOLE script via eval of the full command
+    test_run env BANK_FILE="$sandbox/b15.bank.env" "$pos_bank" run "ml-demo"
+    check_rc "pos bank run multiline exits 0" 0 "$TR_RC"
+    check_contains "pos bank run multiline output line 1" "round 1: ok" "$TR_OUT"
+    check_contains "pos bank run multiline output line 2" "round 2: ok" "$TR_OUT"
+}
Author	SHA1	Message	Date
Your Name	59d834a71c	chore: note pos bank multiline fix in AGENT_TODO Done gates / consistency-and-conventions (push) Successful in 20s Details	2026-09-12 08:27:12 -04:00
Your Name	11b4a679a8	fix: store and execute multiline commands in pos bank gates / consistency-and-conventions (push) Successful in 20s Details bank.env is line-oriented (name\|description\|command) so commands with real newlines spanned records: bank_load truncated the command to its first line and the remaining script lines became bogus entries. The bank_get+cut -f3 retrieval path also truncated at embedded tabs. - lib/bank-lib.sh: v2 format escapes backslash->\\ and newline->\\n in the command field, writes # BANK_VERSION: 2; bank_load decodes with printf %b only for v2 files, so existing v1 files load raw (backward compatible, verified against the real ts-google entry). - bin/pos-bank: cmd_show/cmd_run/cmd_edit now read fields from the BANK_* arrays via bank_find instead of bank_get+cut. - tests/t-bank.sh: +13 checks (71 total) - multiline round-trip exact bytes, literal backslash-n, v1 raw-backslash compat, v1+re-save byte-identical, CLI show/run full script.	2026-09-12 08:25:40 -04:00
Your Name	e23d57e551	fix: include category-less tools in pos tab completion gates / consistency-and-conventions (push) Successful in 23s Details _pos_complete_categories offered only hyphenated categories plus a hardcoded 'config', so 'pos <TAB>' never showed bank/tree. Category-less tools are now discovered from the executable scan, and the words==3 dispatch routes no-hyphen tools to _pos_complete_tool so 'pos bank <TAB>' offers list/add/show/run/edit/remove.	2026-09-12 07:29:30 -04:00
Your Name	c5d501ad25	fix: show Command Bank in main pos menu; fix pos bank run crash gates / consistency-and-conventions (push) Successful in 27s Details - bin/pos: _pos_category_list now emits category-less tools (pos-bank, pos-config, pos-tree) as sorted menu entries with an empty subcommand column, deduped against real categories (pos-ai). bank previously never appeared in the bare 'pos' menu. - bin/pos-bank: fixed invalid 'local name="" -a cli_params=()' at cmd_run (line 150) — bash rejected '-a' after an assignment, crashing every 'pos bank run' with 'local: -a: not a valid identifier'. Split into 'local name=""' + 'local -a cli_params=()'. - tests/t-bank.sh: added B12-B14 covering cmd_run (no-params, missing-command, param substitution) — would have caught the crash. - AGENT_TODO.md: bank feature moved to Done.	2026-09-12 05:20:20 -04:00
Your Name	73d15a26b4	fix: register bank-lib.sh (and yt-lib.sh) in install/uninstall lib manifests gates / consistency-and-conventions (push) Successful in 19s Details lib/bank-lib.sh was added for pos bank but never registered in install.sh's phase-2 lib copy list, so it never reached /usr/local/bin and pos bank failed after install. Also restored yt-lib.sh to POS_LIBS (pre-existing gap: uninstall left it behind). Symmetry gate tests/t-uninstall-manifest.sh now passes.	2026-09-12 03:28:15 -04:00
Your Name	41efc91cf0	feat: add pos bank — persistent command bank with parameterized templates gates / consistency-and-conventions (push) Successful in 29s Details	2026-09-12 03:02:20 -04:00
Your Name	0b76d4d29e	fix: add lib/yt-lib.sh to install.sh library list gates / consistency-and-conventions (push) Successful in 17s Details The yt-lib.sh library was missing from the install script's library list, causing pos-media-yt-subtitles (and other yt-* tools) to fail with 'No such file or directory' when run from /usr/local/bin/. This adds yt-lib.sh to the install list and updates documentation to reflect the change.	2026-09-11 13:00:14 -04:00
Your Name	2c77e73799	. gates / consistency-and-conventions (push) Successful in 17s Details	2026-09-11 12:47:42 -04:00