Linux_post_install/AgentsReport/designer/2026-08-26_ai-alias-ux.md

# UI/UX Specification: `pos ai alias`

**Date:** 2026-08-26
**Author:** Designer
**Status:** DESIGN_READY

---

## TL;DR

| Aspect | Decision |
|--------|----------|
| Main menu | `menu_run` with 4 items; alias table rendered above the box |
| Create flow | 4-step wizard using `step()` headers; name validated in a loop |
| Edit flow | Pick → show current values → per-field prompt with Enter=keep |
| Remove flow | Pick → detail display → `confirm … n` (default=NO) |
| List output | Column-formatted table to stdout, 80-col safe |
| Long prompts | Single-line via `menu_ask_value`; full value stored; display truncated |
| Error UX | `warn` + re-prompt (recoverable) or `err` + exit (fatal) |
| First-run | Auto-create `.env`+`.sh` on first write; show "No aliases yet" |
| Color | CYAN box, GREEN success, YELLOW warn, RED error — same as all `pos` tools |

**Key design decisions:**

1. **Edit uses Enter-to-keep** — each field defaults to current value; empty = keep.
2. **Remove defaults to NO** — irreversible action gets `confirm … n`.
3. **No multi-line prompt input** — `menu_ask_value` is single-line; matches every other `pos` tool.
4. **Table preview** shows provider + session + truncated prompt — enough to distinguish at a glance.

---

## Step 1: Main Menu — `pos ai alias` (no args)

### Screen Purpose
Entry point. Shows existing aliases and offers all actions.

### ASCII Mockup — With Aliases

```
════════════════════════════════════════════
  AI Agent Aliases
════════════════════════════════════════════
  1) Create new alias
  2) Edit existing alias
  3) Remove alias
  4) List aliases
  0) Exit
----------------------------------------
Choose:
```

Above the menu box (also on stderr), render the alias table:

```
  Name         Provider      Session       Prompt
  ─────────── ─────────────  ─────────────  ──────────────────────────
  devbot       gemini         devbot         You are a Linux dev ass…
  code         openrouter     code           You are a code reviewer…
  ─────────── ─────────────  ─────────────  ──────────────────────────
  2 alias(es)
```

### ASCII Mockup — Empty (No Aliases Yet)

```
════════════════════════════════════════════
  AI Agent Aliases
════════════════════════════════════════════
  1) Create new alias
  2) Edit existing alias
  3) Remove alias
  4) List aliases
  0) Exit
----------------------------------------
Choose:
```

With a line above the box:

```
  [!] No aliases defined yet — create one with option 1.
```

### Table Column Spec

```
Column      Width   Alignment   Truncation
─────────   ─────   ─────────   ─────────────────────────────────
Indent      2       —           —
Name        12      left        hard-cut (alias names max ~20 by validation)
Provider    12      left        as-is (short: gemini, openrouter)
Session     12      left        as-is
Prompt      42      left        ${prompt:0:40}…  (if > 42 chars)
```

**Total width:** 2 + 12 + 1 + 12 + 1 + 12 + 1 + 42 = **83 cols** (safe for 80-col with minor overflow on rare cases; alternatively reduce prompt to 40 → 81).

**Empty prompt cell:** Show `${DIM}(default)${RESET}` in dim.

**Row limit:** If > 5 aliases, show first 4 + a final row: `  … and N more`.

### Behavior

| Condition | Behavior |
|-----------|----------|
| Zero aliases | No table; dim warning line; menu options still shown (user can create immediately). |
| 1+ aliases | Table above menu box. |
| EOF / non-tty | `menu_guard` fails → prints to stderr, rc 1. |
| `0`/`q`/`Q` on menu | Clean exit rc 0 (standard `menu_run` behavior). |

---

## Step 2: Create Flow

### Entry Points
- `pos ai alias` → menu → option 1
- `pos ai alias create` (no name arg — full interactive)
- `pos ai alias create <name>` (pre-fills name, skips step 1)

### ASCII Mockup — Full Interactive Create

```
════════════════════════════════════════════
  Create AI Agent Alias
════════════════════════════════════════════

  [1/4] Alias Name
  ─────────────────────────────────────────
Alias name: devbot

  [2/4] Provider
  ─────────────────────────────────────────
-- 2 available --
  1) gemini
  2) openrouter
  0) Back
----------------------------------------
Pick provider [1-2], text=filter, 0=back 1

  [3/4] Session Name
  ─────────────────────────────────────────
Session name [devbot]:

  [4/4] System Prompt
  ─────────────────────────────────────────
System prompt (empty = use built-in): You are a Linux dev assistant.

────────────────────────────────────────────
  Create alias 'devbot'?
    Provider:  gemini
    Session:   devbot
    Prompt:    You are a Linux dev assistant.
────────────────────────────────────────────
Create alias 'devbot'? [Y/n]: y

  [+] Alias 'devbot' created.
      Reload shell: source ~/.bashrc
```

### Step-by-Step Behavior

#### Step 1: Alias Name

| Input | Behavior |
|-------|----------|
| Prompt | `menu_ask_value "Alias name" ""` — mandatory, no default |
| Empty input | `warn "Alias name cannot be empty"` → re-prompt (loop) |
| Invalid format | `warn "Invalid name '$input' — use letters, digits, hyphens, underscores (start with a letter)"` → re-prompt |
| Duplicate name | `warn "Alias '$input' already exists — use 'pos ai alias edit $input' instead"` → re-prompt |
| `<name>` arg given | Validate format + uniqueness; fatal `err` if invalid (non-interactive) |
| **Valid name** | Break out of loop, proceed to step 2 |

**Validation regex:** `^[a-zA-Z][a-zA-Z0-9_-]*$`

#### Step 2: Provider

| Input | Behavior |
|-------|----------|
| Source | Discover from `$PROVIDER_DIR/*.sh` (pattern: `bin/pos-ai` lines 17-18) |
| Picker | `menu_pick "Pick provider" "${providers[@]}"` |
| Zero providers | `err "No AI providers installed — run 'pos ai' setup first"` → exit 1 |
| Single provider | Auto-select, log: `"Using provider: ${provider}"` (skip picker) |
| User picks 0/back | Return to main menu (rc 1 from `menu_pick`) |

#### Step 3: Session Name

| Input | Behavior |
|-------|----------|
| Prompt | `menu_ask_value "Session name" "<alias_name>"` — default = alias name |
| Empty (Enter) | Accepts default = alias name (the common path) |
| Invalid format | `warn` + re-prompt with current default |
| **Valid** | Proceed |

**Design decision:** Default session = alias name. 90%+ of users want 1:1 mapping. The bracket default `[alias_name]` makes this obvious.

#### Step 4: System Prompt

| Input | Behavior |
|-------|----------|
| Prompt | `menu_ask_value "System prompt (empty = use built-in)" ""` |
| Empty | Stores empty string → `--system` flag omitted in generated alias |
| Contains `\|` | `warn "System prompt must not contain '|' characters"` → re-prompt |
| > 500 chars | `warn "Prompt is ${#input} chars — consider keeping it concise"` → still accepts |
| Single quotes, `$`, backticks | **Accepted** — `_regen_aliases()` handles escaping |

**Design decision: single-line only.** `menu_ask_value` uses `read -rp`. Multi-line input is not supported and would require external deps (dialog/whiptail). Users paste prompts on one line — this is consistent with every other `pos` tool.

#### Confirmation

| Aspect | Behavior |
|--------|----------|
| Display | `section`-style box with all 4 values; prompt truncated to 50 chars in display |
| Confirm | `confirm "Create alias '<name>'?" y` — **default YES** (constructive action) |
| User declines | `log "Aborted."` → return to main menu |
| User confirms | `_write_env_file()` + `_regen_aliases()` → `log "Alias '<name>' created."` |

---

## Step 3: Edit Flow

### Entry Points
- `pos ai alias` → menu → option 2
- `pos ai alias edit` (interactive picker)
- `pos ai alias edit <name>` (edit specific alias)

### ASCII Mockup — Full Interactive Edit

```
════════════════════════════════════════════
  Edit AI Agent Alias
════════════════════════════════════════════

-- 3 available --
  1) devbot     [gemini]     You are a Linux dev assistant.
  2) code       [openrouter] You are a code reviewer.
  3) dev        [gemini]     Dev assistant
  0) Back
----------------------------------------
Pick alias to edit [1-3], text=filter, 0=back 1

  Current values for 'devbot':
    Provider:  gemini
    Session:   devbot
    Prompt:    You are a Linux dev assistant.

  [1/3] Provider
  ─────────────────────────────────────────
-- 2 available --
  1) gemini
  2) openrouter
  0) Back
----------------------------------------
Pick provider [1-2], text=filter, 0=back 1

  [2/3] Session Name
  ─────────────────────────────────────────
Session name [devbot]:

  [3/3] System Prompt
  ─────────────────────────────────────────
System prompt [You are a Linux dev assistant.]:

────────────────────────────────────────────
  Save changes to 'devbot'?
    Provider:  gemini       (unchanged)
    Session:   devbot       (unchanged)
    Prompt:    You are a dev assistant
────────────────────────────────────────────
Save changes? [Y/n]: y

  [+] Alias 'devbot' updated.
```

### Step-by-Step Behavior

#### Alias Picker

| Condition | Behavior |
|-----------|----------|
| No aliases | `warn "No aliases to edit — create one first"` → return to main menu |
| Picker | `menu_pick "Pick alias to edit" "${display_items[@]}"` |
| Items format | `"${name} [${provider}] ${prompt_preview}"` (prompt preview = first 30 chars) |
| `<name>` arg given | Validate existence; `err` if not found, exit 1 |

#### Show Current Values

After picking, display a summary block (to stderr):

```
  Current values for 'devbot':
    Provider:  gemini
    Session:   devbot
    Prompt:    You are a Linux dev assistant.
```

This gives the user a reference before editing.

#### Per-Field Editing (3 steps)

| Field | Mechanism | Default | Validation |
|-------|-----------|---------|------------|
| **Provider** | `menu_pick` from installed providers | Current shown in list header | Must pick valid provider; 0/back = keep current |
| **Session** | `menu_ask_value "Session name" "<current>"` | Current value | Regex; warn + re-prompt on invalid |
| **Prompt** | `menu_ask_value "System prompt" "<current>"` | Current value (truncated in display if > 60 chars) | `\|` rejected; > 500 chars warning |

**Provider edit detail:** `menu_pick` doesn't support pre-selection. Current provider is shown in the header: `"Current provider: gemini"`. If user picks 0/back, current is kept — clean "skip to keep" pattern.

**Prompt edit detail:** If current prompt > 80 chars, default display is truncated: `[You are a Linux dev assistant. You reply with c…]`. The full value is preserved in the stored default regardless.

**Step count:** 3 steps (not 4) because alias name cannot be changed — it's the record key.

#### Save Confirmation

| Condition | Behavior |
|-----------|----------|
| **No changes detected** (all values identical) | `log "No changes — nothing to save."` → return to main menu (skip write) |
| Changes exist | Show diff summary with `(changed)` / `(unchanged)` tags |
| **Confirm** | `confirm "Save changes to '<name>'?" y` — **default YES** |
| User declines | `log "Discarded."` → return to main menu |
| User confirms | Rewrite `.env` entry, regenerate `.sh`, `log "Alias '<name>' updated."` |

**Diff summary format:**

```
────────────────────────────────────────────
  Save changes to 'devbot'?
    Provider:  gemini       (unchanged)
    Session:   mybot        (changed)
    Prompt:    You are a dev assistant
────────────────────────────────────────────
```

---

## Step 4: Remove Flow

### Entry Points
- `pos ai alias` → menu → option 3
- `pos ai alias remove` (interactive picker)
- `pos ai alias remove <name>` (remove specific alias)

### ASCII Mockup

```
════════════════════════════════════════════
  Remove AI Agent Alias
════════════════════════════════════════════

-- 3 available --
  1) devbot     [gemini]     You are a Linux dev assistant.
  2) code       [openrouter] You are a code reviewer.
  3) dev        [gemini]     Dev assistant
  0) Back
----------------------------------------
Pick alias to remove [1-3], text=filter, 0=back 1

  Alias:    devbot
  Provider: gemini
  Session:  devbot
  Prompt:   You are a Linux dev assistant.

Remove alias 'devbot'? This cannot be undone. [y/N]: n

  [--] Cancelled.
```

### Behavior

| Condition | Behavior |
|-----------|----------|
| No aliases | `warn "No aliases to remove"` → return to main menu |
| Picker | Same format as edit picker |
| `<name>` arg | Validate existence; `err` if not found, exit 1 |
| Detail display | Show all fields in full (no truncation) before confirmation |
| **Confirm** | `confirm "Remove alias '<name>'? This cannot be undone." n` — **default NO** |
| User declines | `log "Cancelled."` → return to main menu |
| User confirms | Remove from `.env`, regenerate `.sh`, `log "Alias '<name>' removed."` |

**Design decision: default=n.** Irreversible destructive action. `confirm` with default `n` means pressing Enter is safe — user must explicitly type `y`.

---

## Step 5: List / Show (Non-Interactive)

### `pos ai alias list`

#### ASCII Mockup

```
Aliases (3):
  Name         Provider      Session       Prompt
  ─────────── ─────────────  ─────────────  ──────────────────────────────
  devbot       gemini         devbot         You are a Linux dev assistant.
  code         openrouter     code           You are a code reviewer. Be concise.
  dev          gemini         devbot         Dev assistant
```

| Aspect | Spec |
|--------|------|
| Format | `printf "  %-12s %-12s %-12s %s\n"` |
| Prompt truncation | Full up to 60 chars; longer → append `…` |
| Zero aliases | Print `Aliases (0):` with nothing below, exit 0 |
| Header | `Aliases (N):` — count included for scripting |
| Output | stdout, no color (pipeable) |

### `pos ai alias show <name>`

#### ASCII Mockup

```
  Alias:    devbot
  Provider: gemini
  Session:  devbot
  Prompt:   You are a Linux dev assistant.
  Command:  pos ai gemini ask --session devbot --system 'You are a Linux dev assistant.'
```

| Aspect | Spec |
|--------|------|
| `<name>` required | Missing → `err "Usage: pos ai alias show <name>"` exit 1 |
| Name not found | `err "Alias '<name>' not found"` exit 1 |
| Full values | No truncation on any field |
| `Command` field | Exact alias expansion: `pos ai <provider> ask --session <session> [--system '<prompt>']` |
| Single quotes in prompt | Display escaped as `'\''` to show actual alias content |
| Empty prompt | `Command` omits `--system` entirely |
| Output | stdout, no color |

---

## Step 6: Error States — Complete Catalog

| Scenario | Message | Type | Behavior |
|----------|---------|------|----------|
| **First run (no .env)** | Silent auto-create on first write | — | `_load_aliases()` returns empty; menu shows "No aliases" |
| **Alias name empty** | `warn "Alias name cannot be empty"` | Recoverable | Re-prompt (create) |
| **Alias name invalid** | `warn "Invalid name '<input>' — use letters, digits, hyphens, underscores"` | Recoverable | Re-prompt |
| **Alias name duplicate (create)** | `warn "Alias '<input>' already exists — use 'pos ai alias edit <input>' instead"` | Recoverable | Re-prompt |
| **Alias not found (edit/remove)** | `err "Alias '<name>' not found"` | Fatal | Exit 1 |
| **Invalid provider** | `err "Unknown provider '<input>'"` | Fatal | Exit 1 (impossible in interactive — menu_pick) |
| **No providers installed** | `err "No AI providers installed — run 'pos ai' setup first"` | Fatal | Exit 1 |
| **Pipe char in prompt** | `warn "System prompt must not contain '\|' characters"` | Recoverable | Re-prompt |
| **Long prompt (> 500 chars)** | `warn "Prompt is <N> chars — consider keeping it concise"` | Advisory | Accepts, continues |
| **No aliases to edit** | `warn "No aliases to edit — create one first"` | Info | Return to main menu |
| **No aliases to remove** | `warn "No aliases to remove"` | Info | Return to main menu |
| **Non-tty / EOF** | `[!] Interactive menu needs a terminal — use a subcommand instead (see --help).` | Fatal | Exit 1 |
| **Confirm declined (create)** | `log "Aborted."` | Info | Return to main menu |
| **Confirm declined (remove)** | `log "Cancelled."` | Info | Return to main menu |
| **Confirm declined (edit)** | `log "Discarded."` | Info | Return to main menu |
| **No changes in edit** | `log "No changes — nothing to save."` | Info | Return to main menu |

### Message Convention

| Helper | Use For | Destination |
|--------|---------|-------------|
| `log` | Success, info | stdout |
| `warn` | Recoverable problems, advisory | stderr |
| `err` | Fatal errors | stderr + exit 1 |
| `section` / `step` | Visual structure | stderr (display) |

---

## Step 7: Color & Formatting Conventions

### Color Palette

| Element | Color | Source |
|---------|-------|--------|
| Section/box borders | CYAN | `section()`, `menu_run()` |
| Step numbers | BOLD | `step()` |
| Step underlines | BLUE | `step()` |
| Success messages | GREEN | `log()` |
| Warnings | YELLOW | `warn()` |
| Errors | RED | `err()` |
| Dim/placeholder text | DIM | inline `${DIM}...${RESET}` |
| Table headers | Plain (no color) | — |
| Default values in prompts | Plain | shown in brackets `[value]` |

### Box Style

All section boxes use the existing double-line Unicode style — the project standard from `section()` in `common.sh`:

```
════════════════════════════════════════════
  Title
════════════════════════════════════════════
```

### 80-Column Safety

Final column layout for table output:

```
Indent:    2
Name:     12
Gap:       1
Provider: 12
Gap:       1
Session:  12
Gap:       1
Prompt:   42
─────────────────────
Total:    83 cols (1 col over 80 — acceptable for modern terminals)
```

For strict 80-col: prompt = 40 → total = 81. **Decision: use 42 for prompt width; 83 cols is acceptable** — the project targets 80-col as a guideline, not a hard wall. All other content (menus, prompts, messages) is well within 80.

---

## Step 8: Implementation Guidance for Builder

### Function Map

| Function | Responsibility | Est. Lines |
|----------|---------------|------------|
| `_load_aliases()` | Read `.env` → parallel arrays `_ALIAS_NAMES[]`, `_ALIAS_PROVIDERS[]`, `_ALIAS_SESSIONS[]`, `_ALIAS_PROMPTS[]` | ~20 |
| `_find_alias <name>` | Linear scan; return index or -1 | ~8 |
| `_write_env_file()` | Write arrays → `.env` (with header comments) | ~15 |
| `_regen_aliases()` | `.env` → `.sh` with `'`→`'\''` escaping + `bash -n` pre-commit check | ~30 |
| `_list_aliases()` | `printf` table to stdout | ~15 |
| `_show_alias <name>` | Key-value display to stdout | ~10 |
| `_create_alias [name]` | 4-step wizard (name→provider→session→prompt→confirm) | ~60 |
| `_edit_alias [name]` | Pick→show→3 field prompts→diff→confirm→write | ~70 |
| `_remove_alias [name]` | Pick→detail→confirm(n)→remove+regen | ~30 |
| `_main_menu()` | `menu_run` loop dispatching to above | ~30 |
| `usage()` | Help text | ~20 |

### Critical Implementation Patterns

1. **All display to stderr, all results to stdout** — `menu-lib.sh` contract. `menu_run`/`menu_pick`/`menu_ask_value` already do this; `_create_alias`/`_edit_alias`/`_remove_alias` must follow the same pattern for their `section()`/`step()` output.

2. **Re-prompt loops** — use `while true` with validation inside; `continue` on `warn`, `break` on valid input. Name validation loops until valid. Provider/session/prompt validation loops until valid.

3. **Edit diff detection** — compare new values against loaded values before writing; skip the write entirely if all identical. This avoids unnecessary `.sh` regeneration.

4. **Provider discovery** — copy pattern from `bin/pos-ai` lines 17-18:
   ```bash
   PROVIDER_DIR="$(dirname "$0")/../lib/ai-providers"
   [ -d "$PROVIDER_DIR" ] || PROVIDER_DIR="$(dirname "$0")/ai-providers"
   ```

5. **Pipe char in prompt** — validate in `_create_alias` and `_edit_alias` prompt steps, NOT in `_regen_aliases()` (which trusts its input after validation).

6. **Generated .sh syntax check** — `bash -n "$sh_file"` before `mv "$tmp" "$sh_file"`; on failure, `warn` and `rm -f "$tmp"` (keep old `.sh`).

7. **INTERACTIVE_CMDS** — add `ai-alias` to the space-separated list in `bin/pos`.

### State Transition Diagram

```
pos ai alias (no args)
  │
  ├─ _main_menu()
  │   ├─ [1] → _create_alias()
  │   │         ├─ Step 1: name validation loop
  │   │         ├─ Step 2: provider picker (or auto if single)
  │   │         ├─ Step 3: session (default = alias name)
  │   │         ├─ Step 4: prompt (default = empty)
  │   │         ├─ confirm → _write_env_file() + _regen_aliases()
  │   │         └─ return to _main_menu()
  │   │
  │   ├─ [2] → _edit_alias()
  │   │         ├─ picker (or use arg)
  │   │         ├─ show current values
  │   │         ├─ Step 1: provider picker (0=back = keep)
  │   │         ├─ Step 2: session (enter = keep)
  │   │         ├─ Step 3: prompt (enter = keep)
  │   │         ├─ diff check → confirm → write
  │   │         └─ return to _main_menu()
  │   │
  │   ├─ [3] → _remove_alias()
  │   │         ├─ picker (or use arg)
  │   │         ├─ show detail
  │   │         ├─ confirm n (default = no)
  │   │         ├─ remove + regen
  │   │         └─ return to _main_menu()
  │   │
  │   ├─ [4] → _list_aliases() (stdout, then return to _main_menu)
  │   │
  │   └─ [0] → exit 0
  │
  ├─ pos ai alias create [name]  → _create_alias "$name"
  ├─ pos ai alias edit [name]    → _edit_alias "$name"
  ├─ pos ai alias remove [name]  → _remove_alias "$name"
  ├─ pos ai alias list           → _list_aliases(); exit 0
  ├─ pos ai alias show <name>    → _show_alias "$name"; exit 0
  └─ -h|--help                   → usage(); exit 0
```

---

## Out of Scope

- Multi-line prompt editor (no `dialog`/`whiptail` dependency)
- Alias import/export
- Alias categories or tags
- Alias usage statistics
- `pos config` integration (architecture Decision 4: explicitly rejected)
- Alias renaming (name is the record key; remove + create is the path)

---

## Open Design Questions

None. All decisions resolved from architecture doc + existing primitives.

---

**End of UX specification.**