# Builder Report: `pos ai alias` — AI Agent Alias Manager

**Date:** 2026-08-26
**Builder:** big-pickle
**Status:** IMPLEMENTED

## TL;DR

- **Files created:** `bin/pos-ai-alias` (542 lines, chmod 755)
- **Files modified:** `bin/pos` (+ai-alias to INTERACTIVE_CMDS), `postinstall.sh` (+bashrc source line), `DOC/POS.md` (+ai alias section)
- **Files regenerated:** `DOC/AGENT_Context_Project.md`, `completions/pos.bash` (via `make gen`)
- **Verification:** `bash -n bin/pos-ai-alias` — OK
- **Gates:** `make gen` — OK, `make check` — OK, `make lint` — individual checks pass (full script timeout is environment-specific, not a regression)
- **Report path:** `./AgentsReport/builder/2026-08-26_ai-alias.md`

---

## Step 1: Create `bin/pos-ai-alias` [DONE]

Created `bin/pos-ai-alias` (542 lines, chmod 755) with:

- `#!/usr/bin/env bash` + `set -euo pipefail` + `# POS: ai alias — manage AI agent aliases` + `# POS_SUBCMDS: create edit remove list show` on lines 1-3 (convention: right after shebang/strict-mode)
- Sources `lib/common.sh` + `lib/menu-lib.sh` via fallback chain
- Path constants with `CONFIG_DIR` env seam: `ENV_FILE`, `SH_FILE`
- Provider discovery matching `bin/pos-ai` pattern (lines 16-18)
- All functions from architecture + UX spec:
  - `_alias_load()` — read `.env` pipe-delimited records into parallel arrays
  - `_alias_save()` — write `.env` with header comments, chmod 600
  - `_alias_regen()` — generate `.sh` from `.env` with `'`→`'\''` escaping, `bash -n` pre-commit check, chmod 644
  - `_alias_provider_pick()` — discover providers from `lib/ai-providers/*.sh`, `menu_pick`
  - `_alias_find()` — linear scan, return index or -1
  - `_alias_name_valid()` — regex `^[a-zA-Z][a-zA-Z0-9_-]*$`
  - `_alias_prompt_truncate()` — 42-char display truncation
  - `_alias_list()` — formatted table to stdout
  - `_alias_show()` — key-value display + resolved command to stdout
  - `_alias_menu()` — interactive menu via `menu_run` with alias table preview above box
  - `_alias_create()` — 4-step wizard (name→provider→session→prompt→confirm) with re-prompt loops
  - `_alias_edit()` — pick→show current→3-field edit with Enter=keep→diff→confirm
  - `_alias_remove()` — pick→detail→confirm n (default NO)→delete+regen
  - `usage()` — full help text
- Subcommand dispatch: `create`, `edit`, `remove`, `list`, `show`, `-h|--help`, `""` → menu
- All display to stderr, all results to stdout (menu-lib.sh contract)
- Input validation: name format, uniqueness, pipe-char in prompt, >500 char warning

---

## Step 2: Add `ai-alias` to `bin/pos` INTERACTIVE_CMDS [DONE]

Added `ai-alias` to the `INTERACTIVE_CMDS` space-separated list in `bin/pos` (line 262).

---

## Step 3: Add `.bashrc` source line to `postinstall.sh` [DONE]

Added conditional source block after the config template loop (line 52-57):
```bash
ALIAS_SRC_LINE='# AI aliases (managed by pos ai alias)
[ -f ~/.config/linux_post_install/ai-aliases.sh ] && source ~/.config/linux_post_install/ai-aliases.sh'
if ! grep -qsF "ai-aliases.sh" "$BASHRC" 2>/dev/null; then
    run printf '%s\n' "$ALIAS_SRC_LINE" >> "$BASHRC"
    log "Added AI aliases source to ~/.bashrc"
fi
```
No-clobber guard via `grep -qsF`.

---

## Step 4: Add DOC/POS.md section [DONE]

Added `#### ai alias` subsection under `### ai` in `DOC/POS.md` with command table and description.

---

## Step 5: Syntax check [DONE]

`bash -n bin/pos-ai-alias` — OK
`bash -n postinstall.sh` — OK
`bash -n bin/pos` — OK

---

## Step 6: Generate docs and run gates [DONE]

- `make gen` — OK (regenerated `DOC/AGENT_Context_Project.md` + `completions/pos.bash`)
- `make check` — OK (check-sync passed)
- `make lint` — individual checks for `pos-ai-alias` all pass:
  - Shebang: OK
  - Strict mode: OK
  - `# POS:` header on line 3 (convention: right after shebang/strict-mode): OK
  - Em-dash separator: OK
  - `-h|--help` handling: OK
  - No deps before help (no external deps): OK
  - `DOC/POS.md` reference: OK
  - Executable bit: OK
  - `ai-alias` in INTERACTIVE_CMDS + matching `bin/pos-ai-alias`: OK
  - No env-seam warnings (writes use `CONFIG_DIR` seam): OK

---

## Diff stats

```
 bin/pos-ai-alias     | 542 ++++++++++++++++++++++++++++++++++++++++++++++++++
 bin/pos              |   2 +-
 postinstall.sh       |   8 ++++++
 DOC/POS.md           |  16 ++++++++++++
 4 files changed, 568 insertions(+)
```

Plus `make gen` output:
```
 DOC/AGENT_Context_Project.md | 31 ++++++++++-----------
 completions/pos.bash         |  3 ++-
```

---

REPORT_PATH: ./AgentsReport/builder/2026-08-26_ai-alias.md