diff --git a/DOC/AGENT_Context_Project.md b/DOC/AGENT_Context_Project.md index 4c670a6..3ee2b8b 100644 --- a/DOC/AGENT_Context_Project.md +++ b/DOC/AGENT_Context_Project.md @@ -208,7 +208,7 @@ User runs: ./install.sh [--apps|--full|--feature|--dry-run|--skip |--step │ ├─ Phase 2: install.sh (requires root) │ └─ Copies bin/* → /usr/local/bin/ (chmod 755) -│ └─ Copies lib/*.sh (common, flags, notify, entertainment-lib, +│ └─ 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) │ └─ Copies x64_bin/* → /usr/local/bin/ on x86_64 (arm64_bin/ on aarch64) diff --git a/DOC/DEV.md b/DOC/DEV.md index 73358d5..b333181 100644 --- a/DOC/DEV.md +++ b/DOC/DEV.md @@ -31,7 +31,7 @@ Each phase is independent and runs only if the corresponding script exists. |-----------|---------|-------------| | `bin/` | Daily-use CLI tools and wrappers | `/usr/local/bin/` | | `apps//` | Optional desktop app installers | run on demand | -| `lib/` | Shared libraries: `common.sh` (helpers), `flags.sh` (feature flags), `notify.sh` (multi-platform alerting), `entertainment-lib.sh` (entertainment scheduling + last-run state), `entertainment-plugin-lib.sh` (message-safe plugin helpers), `scheduler-lib.sh` (system scheduler), `user-timers-lib.sh` (shared systemd user timer machinery), `config-ui.sh` (interactive config UI), `menu-lib.sh` (category-neutral menu primitives: guard/looping menu/filter picker/prompt), `share-lib.sh` (share-suite domain probes/listings + compat shims to menu-lib) | sourced at build time | +| `lib/` | Shared libraries: `common.sh` (helpers), `flags.sh` (feature flags), `notify.sh` (multi-platform alerting), `registry.sh` (shared query API for POS tool metadata headers), `entertainment-lib.sh` (entertainment scheduling + last-run state), `entertainment-plugin-lib.sh` (message-safe plugin helpers), `scheduler-lib.sh` (system scheduler), `user-timers-lib.sh` (shared systemd user timer machinery), `config-ui.sh` (interactive config UI), `menu-lib.sh` (category-neutral menu primitives: guard/looping menu/filter picker/prompt), `share-lib.sh` (share-suite domain probes/listings + compat shims to menu-lib) | sourced at build time | | `config/` | Gitignored user config files | `~/.config//` (via postinstall) | | `entertainment/` | Public-API plugins for the entertainment module | `/usr/local/bin` (via install.sh Phase 2) | | `compose/` | ScaleTail templates (git submodule) | `/usr/local/share/linux_post_install/scale-tail` | @@ -128,8 +128,10 @@ esac # POS: — one-line description rendered by `make gen` # POS_FLAGS: --flag1 --flag2 # ONLY for flag-style tools # POS_SUBCMDS: sub1 sub2 # ONLY for multi-command tools + # POS_DEPS: binary1 binary2 # Optional: runtime deps (space-separated binary names) + # POS_EXAMPLES: pos | Description # Optional: usage examples ``` - The description feeds the dispatch table, bin tree and file table in `DOC/AGENT_Context_Project.md`; `POS_FLAGS` feeds flag completion and `POS_SUBCMDS` feeds subcommand completion in `completions/pos.bash` (both update via `make gen`). `make gen` only reads the text after the first `— ` — the ` ` words before it are convention-only (for nested tools, keep the full path there, e.g. `# POS: communication telegram-listener — …`). + The description feeds the dispatch table, bin tree and file table in `DOC/AGENT_Context_Project.md`; `POS_FLAGS` feeds flag completion and `POS_SUBCMDS` feeds subcommand completion in `completions/pos.bash` (both update via `make gen`). `POS_DEPS` lists runtime binary names that `command -v` would check — use when the tool requires specific binaries beyond what `preinstall.sh` installs. `POS_EXAMPLES` provides curated usage examples (one per line, pipe-delimited `command | description`) shown in `pos tree` and future help views. Both are optional and degrade gracefully when absent. `make gen` only reads the text after the first `— ` — the ` ` words before it are convention-only (for nested tools, keep the full path there, e.g. `# POS: communication telegram-listener — …`). - **Category-less vs categorized:** most tools are `bin/pos--`. Use category-less `bin/pos-` (e.g. `pos-config`, `pos-tree`) only for dispatcher/dev-level commands that fit no category — they dispatch and document like any tool but show with an empty category in the generated tables. - Nested tools (e.g. `bin/pos-communication-telegram-listener`) are auto-detected from filenames: the trailing segment (`listener`) is offered as a subcommand of the parent tool (`communication-telegram`) in `pos --help` and tab-completion, instead of appearing as a flat sibling (`telegram-listener`). The flat dash-form (`pos communication telegram-listener`) still dispatches. - Optionally add an EXAMPLES line in `bin/pos` `usage()` to showcase the tool in `pos --help`. diff --git a/DOC/POS.md b/DOC/POS.md index 98df2b5..6949c2a 100644 --- a/DOC/POS.md +++ b/DOC/POS.md @@ -70,6 +70,14 @@ Category-less tools (`config`, `tree`) live outside any category and are documen | `pos ai providers` | Lists available providers, their config status, and the active provider | | `pos ai --model …` | Overrides the model for one invocation | | `pos ai --provider …` | Selects the provider for one invocation (gemini\|openrouter) | +| `pos ai alias` | Interactive alias manager (`bin/pos-ai-alias`): menu loop (create / edit / remove / list) that shows the alias table (Name/Provider/Session/Prompt, prompts truncated) between picks | +| `pos ai alias create [name]` | Interactive 4-step wizard: alias name (leading letter, then letters/digits/-/_; unique across aliases), provider pick (from installed `lib/ai-providers/*.sh` adapters), session name (defaults to the alias name), optional system prompt (must not contain `\|`; warns above 500 chars); confirm defaults to yes, then the alias is saved | +| `pos ai alias edit [name]` | Edits an existing alias (pick from list or pass the name): provider/session/prompt are re-prompted pre-filled with the current values — Enter keeps the current value; a per-field changed/unchanged summary is confirmed (default yes) before saving; nothing is written if nothing changed | +| `pos ai alias remove [name]` | Removes an alias (pick from list or pass the name); the confirmation defaults to **no** and removal cannot be undone | +| `pos ai alias list` | Non-interactive: prints all aliases as a Name/Provider/Session/Prompt table (prompts truncated at 42 chars) | +| `pos ai alias show ` | Prints one alias's details including the resolved command: `pos ai ask --session [ --system '']` | + +Alias storage: records live in `~/.config/linux_post_install/ai-aliases.env` — one `name\|provider\|session\|system_prompt` line per alias, chmod 600, managed by the tool (do not hand-edit). Every create/edit/remove also rewrites `~/.config/linux_post_install/ai-aliases.sh` (chmod 644), which defines one shell alias per record — `alias ='pos ai ask --session [ --system '']'`. An empty session falls back to the alias name, prompts are single-quote-escaped, and the generated file is syntax-checked before it replaces the previous version. Source this file from your shell rc (e.g. `.bashrc`) to activate the aliases in new shells. Backward compatibility: `pos ai gemini` and `pos ai openrouter` still work as shorthands for `pos ai --provider gemini` and `pos ai --provider openrouter`.