# Architect Report — Self-Describing Command Registry for POS

**Date:** 2026-08-26
**Status:** DECISION_READY

---

## TL;DR

- **Decision:** Add a thin `lib/registry.sh` library that parses `# POS_*:` headers into a queryable API; two new optional headers (`# POS_DEPS:`, `# POS_EXAMPLES:`) extend existing conventions; no framework, no new abstraction layer.
- **Key insight:** The existing header system is already 80% of a registry. The missing piece is a shared parsing library so every consumer stops reimplementing `sed` + `grep` header reading.
- **Scope:** `lib/registry.sh` (new), `scripts/gen-docs.sh` (extend), `bin/pos-tree` (use registry), `templates/pos-tool.sh` (document new headers), docs. All existing tools keep working unchanged.
- **Migration:** Zero-downtime — new headers are optional. Tools add `# POS_DEPS:` and `# POS_EXAMPLES:` incrementally. Registry degrades gracefully when headers are absent.
- **Open items:** `pos help` and `pos menu` are future consumers (not in this phase). Dashboard is out of scope.

---

## Decision 1: Header Format — Extend, Don't Replace

### Problem

The spec asks for dependencies, curated examples, and a shared query API. Currently, each consumer (`pos tree`, `pos <category> --help`, `gen-docs.sh`, `pos config`) independently implements `sed`/`grep` header parsing with its own logic.

### Decision

Add two new optional `# POS_*:` header lines. Keep all existing headers unchanged.

### Exact Syntax

```bash
# POS_DEPS: <binary1> [binary2 ...]
# POS_EXAMPLES: <command> | <description>
```

**Rules:**
- All new headers are **optional** — tools that don't declare them simply won't expose that metadata. Progressive metadata preserved.
- `# POS_DEPS:` is space-separated binary names (what `command -v` checks, not apt package names).
- `# POS_EXAMPLES:` can appear on multiple lines — each is `<command> | <description>` (pipe-delimited, max one `|`).
- Headers must appear between the shebang/strict-mode block (lines 1–6) and the first non-comment line.
- Gen-docs and lint only parse headers from the first ~10 lines of each file.

**Existing headers (unchanged):**

```bash
# POS: <category> <command> — <description>
# POS_FLAGS: --flag1 --flag2
# POS_SUBCMDS: sub1 sub2 sub3
# POS_CONFIG: <scope> | <env-file> | <KEY>=<flags>:<desc> | ...
```

**New headers (optional):**

```bash
# POS_DEPS: docker nmap jq
# POS_EXAMPLES: pos network scan 192.168.1.0/24 | Scan a /24 CIDR
# POS_EXAMPLES: pos network scan 10.0.0.0/28 --full | Full scan with OS detection
```

### Example: Minimal Tool (No Change Needed)

```bash
#!/usr/bin/env bash
set -euo pipefail
# POS: ssh load-keys — Load all SSH keys into the agent
# ... rest of script
```

### Example: Rich Tool

```bash
#!/usr/bin/env bash
set -euo pipefail
# POS: network download — aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits)
# POS_SUBCMDS: start stop status add torrent metalink list info files peers pause resume remove purge move limit set watch restart retry replace menu
# POS_FLAGS: --dir --out --split --seed --force --upload --gid --tmux
# POS_DEPS: aria2c jq curl
# POS_EXAMPLES: pos network download add https://example.com/file.zip | Download a file
# POS_EXAMPLES: pos network download status | Show download queue status
# POS_EXAMPLES: pos network download --tmux start aria2 daemon with live view
```

### Rationale

| Option | Architecture | Advantages | Costs | Risks | When to choose |
|--------|-------------|------------|-------|-------|----------------|
| **A: Extend existing headers** | Add `# POS_DEPS:` and `# POS_EXAMPLES:` alongside existing headers | Backward compatible, zero migration cost, progressive metadata, consistent with existing patterns | Two new header formats to parse | Low — optional headers degrade gracefully | **Chosen** — smallest sufficient design |
| B: Unified YAML frontmatter | Replace all `# POS_*:` with a YAML block in each file | Richer structure, easier to extend | Breaks all existing consumers, requires migration of 40+ tools, adds YAML dependency | High — YAML parser availability in bash, migration burden | Only if the header system were fundamentally inadequate |
| C: Separate registry file | `registry/<tool>.yaml` per tool | Clean separation, richer metadata | Duplicates what headers already provide, extra files to maintain, sync risk between header and registry | Medium — source of truth drift | Only if headers couldn't hold the metadata |

**Option A wins** because the existing header system already works, is already the source of truth for gen-docs output, and the new metadata (deps, examples) fits naturally into the comment-header format.

### Constraints for Builder

- `# POS_DEPS:` line: `sed -n '/^# POS_DEPS: /{s/^# POS_DEPS: //;p;q}' <file>` — space-separated tokens.
- `# POS_EXAMPLES:` lines: `grep '^# POS_EXAMPLES:' <file | sed 's/^# POS_EXAMPLES:[[:space:]]*//'` — one per line, `|`-delimited command|description.
- The `# POS:` header line **must remain the first metadata line** after shebang/strict-mode. New headers go after existing headers, before any code.

[DECIDED]

---

## Decision 2: Registry Library — `lib/registry.sh`

### Problem

Four consumers independently parse tool headers with their own `sed`/`grep` patterns:
- `bin/pos` `_pos_category_help()` (lines 68–123): reads `# POS:` and `# POS_SUBCMDS:` per tool
- `bin/pos-tree` (lines 47–68): reads `# POS:` and `# POS_SUBCMDS:` per tool
- `scripts/gen-docs.sh` (lines 30–46): reads `# POS:`, `# POS_FLAGS:`, `# POS_SUBCMDS:`, `# POS_CONFIG:` per tool
- `lib/config-ui.sh` (lines 50–57): reads `# POS_CONFIG:` per tool

Each reimplements the same header-reading pattern. Adding new headers means updating every consumer.

### Decision

Create `lib/registry.sh` — a thin library (target ~180 lines) that provides a shared API for querying tool metadata from `# POS_*:` headers.

### Data Structures

All data lives in bash associative arrays and indexed arrays, populated by a single `reg_scan` call.

```bash
# Indexed array — all tool keys, sorted (LC_ALL=C)
declare -a _reg_tools=()

# Associative arrays — keyed by tool key (e.g., "network-download", "config")
declare -A _reg_cat=()        # tool → category ("" for category-less)
declare -A _reg_desc=()       # tool → description (text after "— ")
declare -A _reg_flags=()      # tool → raw POS_FLAGS value
declare -A _reg_subcmds=()    # tool → raw POS_SUBCMDS value
declare -A _reg_deps=()       # tool → raw POS_DEPS value
declare -A _reg_examples=()   # tool → newline-joined POS_EXAMPLES lines

# Config is special: multiple headers per tool, multiple fields per header.
# Stored as pipe-delimited lines keyed by scope (not tool).
declare -a _reg_config_scopes=()  # unique scope names, sorted
declare -A _reg_config_keys=()    # scope → newline-joined key|flags|desc lines
```

**Why not store everything in one mega-array?** Bash associative arrays can't hold structured records. Separate arrays per field keep lookups O(1) and code readable.

### Tool Key Convention

Tool keys match the existing filename convention:
- `bin/pos-network-download` → key `network-download`, category `network`
- `bin/pos-config` → key `config`, category `""` (category-less)
- `bin/pos-ai-alias` → key `ai-alias`, category `ai`

### API

```bash
# ── Initialization ──────────────────────────────────────────────

reg_scan [dir]
    Scan all pos-* files in dir (default: auto-detect from BASH_SOURCE).
    Populates _reg_tools, _reg_cat, _reg_desc, _reg_flags, _reg_subcmds,
    _reg_deps, _reg_examples, _reg_config_scopes, _reg_config_keys.
    Must be called before any other reg_* function.
    Uses LC_ALL=C for deterministic sort.

# ── Discovery ───────────────────────────────────────────────────

reg_list
    Echo sorted list of all tool keys, one per line.

reg_categories
    Echo sorted unique category names (empty string for category-less tools).

reg_tools_in <category>
    Echo sorted tool keys belonging to <category>.
    Pass "" for category-less tools.

# ── Lookup ──────────────────────────────────────────────────────

reg_lookup <tool> <field>
    Echo a field's value for a tool. Fields:
      cat, desc, flags, subcmds, deps, examples
    Returns empty string if field not set or tool not found.
    Exit code: 0 if tool found, 1 if not.

reg_config_scopes
    Echo sorted list of unique config scope names.

reg_config_keys <scope>
    Echo key|flags|description lines for a scope (newline-delimited).

reg_config_envfile <scope>
    Echo the env-file basename for a scope.
    Exit code: 0 if found, 1 if not.

# ── Iteration ───────────────────────────────────────────────────

reg_each <callback>
    Call <callback> for each tool, passing:
      <callback> <category> <tool_key> <description>
    Category is empty for category-less tools.

# ── Convenience (for common patterns) ──────────────────────────

reg_tool_exists <tool>
    Exit 0 if tool is registered, 1 otherwise.

reg_tools_for_category <category>
    Alias for reg_tools_in. Kept for clarity.
```

### Source Pattern

```bash
# lib/registry.sh — no shebang (library, not executable)
# Sourced opt-in by consumers that need tool metadata.

# Common.sh helpers (guarded fallback — mirrors lib/config-ui.sh pattern)
declare -F log  >/dev/null || log()  { echo "[+] $*"; }
declare -F warn >/dev/null || warn() { echo "[!] $*"; }
declare -F err  >/dev/null || err()  { echo "ERROR: $*" >&2; exit 1; }

# ── Tool directory detection ────────────────────────────────────
# Repo:   lib/registry.sh → ../bin
# Install: /usr/local/bin/registry.sh → /usr/local/bin (same dir)
_reg_tools_dir() {
    local dir
    dir="$(cd "$(dirname "${BASH_SOURCE[0]}")/../bin" 2>/dev/null && pwd)"
    if [ -d "$dir" ] && ls "$dir"/pos-* &>/dev/null; then
        echo "$dir"
    else
        dirname "${BASH_SOURCE[0]}"
    fi
}

# ── Data stores ─────────────────────────────────────────────────
declare -a _reg_tools=()
declare -A _reg_cat=()
declare -A _reg_desc=()
declare -A _reg_flags=()
declare -A _reg_subcmds=()
declare -A _reg_deps=()
declare -A _reg_examples=()
declare -a _reg_config_scopes=()
declare -A _reg_config_keys=()

# ── reg_scan ────────────────────────────────────────────────────
reg_scan() {
    local dir="${1:-$(_reg_tools_dir)}" f
    local old LC_ALL_PREV="$LC_ALL"
    export LC_ALL=C

    _reg_tools=()
    # Clear all associative arrays
    for key in "${!_reg_cat[@]:-}"; do
        unset "_reg_cat[$key]" "_reg_desc[$key]" "_reg_flags[$key]"
        unset "_reg_subcmds[$key]" "_reg_deps[$key]" "_reg_examples[$key]"
    done
    _reg_config_scopes=()
    for scope in "${!_reg_config_keys[@]:-}"; do
        unset "_reg_config_keys[$scope]"
    done

    local -A scope_seen=()

    for f in "$dir"/pos-*; do
        [ -x "$f" ] || continue
        local name="${f##*/pos-}"
        local key cat sub
        if [[ "$name" == *-* ]]; then
            cat="${name%%-*}"
            sub="${name#*-}"
        else
            cat=""
            sub="$name"
        fi
        key="$sub"

        _reg_tools+=("$key")
        _reg_cat["$key"]="$cat"

        # POS: — description (text after first "— ")
        local pos_line
        pos_line="$(sed -n '/^# POS: /{s/^# POS: //;p;q}' "$f" 2>/dev/null)"
        _reg_desc["$key"]="${pos_line#*— }"

        # POS_FLAGS:
        _reg_flags["$key"]="$(sed -n '/^# POS_FLAGS: /{s/^# POS_FLAGS: //;p;q}' "$f" 2>/dev/null)"

        # POS_SUBCMDS:
        _reg_subcmds["$key"]="$(sed -n '/^# POS_SUBCMDS: /{s/^# POS_SUBCMDS: //;p;q}' "$f" 2>/dev/null)"

        # POS_DEPS:
        _reg_deps["$key"]="$(sed -n '/^# POS_DEPS: /{s/^# POS_DEPS: //;p;q}' "$f" 2>/dev/null)"

        # POS_EXAMPLES: (may appear multiple times — join with newlines)
        local examples=""
        examples="$(sed -n '/^# POS_EXAMPLES: /{s/^# POS_EXAMPLES: //;p}' "$f" 2>/dev/null)"
        _reg_examples["$key"]="$examples"

        # POS_CONFIG: (may appear multiple lines per file)
        local line
        while IFS= read -r line; do
            [ -n "$line" ] || continue
            line="${line#*POS_CONFIG:}"
            local scope="${line%%|*}"
            scope="${scope// }"
            [ -n "$scope" ] || continue
            _reg_config_keys["$scope"]+="${_reg_config_keys[$scope]:+$'\n'}$line"
            if [ -z "${scope_seen[$scope]:-}" ]; then
                scope_seen["$scope"]=1
                _reg_config_scopes+=("$scope")
            fi
        done < <(grep '^# POS_CONFIG:' "$f" 2>/dev/null || true)
    done

    # Sort tools
    mapfile -t _reg_tools < <(printf '%s\n' "${_reg_tools[@]}" | sort)
    # Sort config scopes
    mapfile -t _reg_config_scopes < <(printf '%s\n' "${_reg_config_scopes[@]}" | sort -u)

    export LC_ALL="$LC_ALL_PREV"
}

# ── Discovery ───────────────────────────────────────────────────
reg_list() { printf '%s\n' "${_reg_tools[@]}"; }

reg_categories() {
    local -A cats=()
    local t
    for t in "${_reg_tools[@]}"; do
        cats["${_reg_cat[$t]}"]=1
    done
    printf '%s\n' "${!cats[@]}" | sort
}

reg_tools_in() {
    local cat="$1" t
    for t in "${_reg_tools[@]}"; do
        [ "${_reg_cat[$t]}" = "$cat" ] && echo "$t"
    done
}

# ── Lookup ──────────────────────────────────────────────────────
reg_lookup() {
    local tool="$1" field="$2"
    case "$field" in
        cat)     echo "${_reg_cat[$tool]:-}" ;;
        desc)    echo "${_reg_desc[$tool]:-}" ;;
        flags)   echo "${_reg_flags[$tool]:-}" ;;
        subcmds) echo "${_reg_subcmds[$tool]:-}" ;;
        deps)    echo "${_reg_deps[$tool]:-}" ;;
        examples) echo "${_reg_examples[$tool]:-}" ;;
        *)       return 1 ;;
    esac
}

reg_config_scopes() { printf '%s\n' "${_reg_config_scopes[@]}"; }

reg_config_keys() {
    local scope="$1"
    echo "${_reg_config_keys[$scope]:-}"
}

reg_config_envfile() {
    local scope="$1" line
    line="$(echo "${_reg_config_keys[$scope]:-}" | head -1)"
    [ -n "$line" ] || return 1
    line="${line#*|}"   # drop scope
    local env="${line%%|*}"
    echo "${env// }"
}

# ── Iteration ───────────────────────────────────────────────────
reg_each() {
    local cb="$1" t
    for t in "${_reg_tools[@]}"; do
        "$cb" "${_reg_cat[$t]}" "$t" "${_reg_desc[$t]}"
    done
}

# ── Convenience ─────────────────────────────────────────────────
reg_tool_exists() {
    [ -n "${_reg_desc[$1]+x}" ]
}
```

### Rationale

| Option | Architecture | Advantages | Costs | Risks | When to choose |
|--------|-------------|------------|-------|-------|----------------|
| **A: Regenerate-on-source library** | `reg_scan` parses all files into bash arrays on first call | O(1) lookups after scan, no external deps, works from /usr/local/bin, bash-native | ~180 lines of code, scan cost at startup (~5ms for 40 tools) | Low — scan is fast enough for interactive use | **Chosen** — matches project's bash-only, no-framework philosophy |
| B: Cached JSON file | `make gen` produces `registry.json`, consumers parse with `jq` | Fast lookups, rich queries | Requires `jq` at runtime (currently a dep, but adds coupling), extra build step, staleness risk | Medium — JSON dependency for all consumers | Only if performance of header parsing became a bottleneck (it won't for 40 tools) |
| C: Per-tool .meta files | Each tool has a sidecar `pos-<tool>.meta` | Clean separation, rich format | Duplicates header data, extra files to maintain, sync drift risk | Medium — two sources of truth | Only if headers were fundamentally limited |

**Option A wins** because:
1. Headers are already the source of truth — no sync risk.
2. The scan takes ~5ms for 40 tools — no performance concern.
3. Works from `/usr/local/bin/` (all libs live there after install).
4. Matches the project's "no unnecessary framework" philosophy.
5. Follows the pattern established by `lib/config-ui.sh`.

### Source Chain

```bash
# In any consumer:
source "$(dirname "$0")/../lib/registry.sh" 2>/dev/null || source "$(dirname "$0")/registry.sh"
reg_scan
# ... use reg_list, reg_lookup, etc.
```

[DECIDED]

---

## Decision 3: Consumer Integration

### Problem

Four consumers need to use the registry. Each has different requirements:
- `bin/pos-tree` needs tree-building from tool data
- `bin/pos` `_pos_category_help()` needs category → tool listing
- `scripts/gen-docs.sh` needs all metadata for code generation
- `lib/config-ui.sh` needs config scopes and keys

### Decision

Migrate consumers to `lib/registry.sh` in this order (highest value first):

#### 3.1: `bin/pos-tree` (Priority: HIGH)

**Current state** (lines 47–68): Scans `pos-*` files independently, reads `# POS:` and `# POS_SUBCMDS:` via `sed`.

**After migration:**
```bash
source "$(dirname "$0")/../lib/registry.sh" 2>/dev/null || source "$(dirname "$0")/registry.sh"
reg_scan

# Build tree from registry instead of scanning files
for tool in $(reg_list); do
    cat="$(reg_lookup "$tool" cat)"
    desc="$(reg_lookup "$tool" desc)"
    deps="$(reg_lookup "$tool" deps)"
    # ... add to tree, annotate with deps if present
done
```

**Enhancement:** When `# POS_DEPS:` is present, show it in the tree view:
```
├── docker ps                    # Enhanced container overview (health, IPs, ports, uptime)
│   [deps: docker]
```

This is the highest-value consumer change — it proves the registry works at runtime and shows the immediate benefit of new metadata.

**Implementation note:** Keep the existing `add()` / `render()` tree-building logic. Replace only the data-collection loop (lines 47–68) with registry calls. The tree structure is already correct from filenames + `POS_SUBCMDS`.

#### 3.2: `scripts/gen-docs.sh` (Priority: HIGH)

**Current state** (lines 30–46): Collects tools into a pipe-delimited array via direct `sed` calls.

**After migration:**
```bash
# In the tools collection loop, use registry for new fields
# Keep the existing collection pattern for backward compatibility
# (gen-docs.sh has its own sorting and rendering logic)

# Add deps and examples to the tools array format
tools+=("$cat|$sub|$desc|$flags|$subcmds|$deps|$examples")
```

**New gen blocks:**
- Add `deps` and `examples` columns to `gen_tree()`, `gen_dispatch()`, `gen_filetable()`.
- These become visible in `DOC/AGENT_Context_Project.md` once tools add the new headers.

**Important:** The existing `gen_*` functions use their own `tools` array (not the registry) because they need specific formatting. The registry provides the raw data; gen-docs formats it. This avoids tight coupling between the generator and the library.

**Alternative considered:** Have gen-docs source the registry directly. Rejected because gen-docs needs the data in a specific format (pipe-delimited array) and the registry's data structure is an implementation detail. Keeping the data flow explicit (`registry → gen-docs tools array → gen_* functions`) is cleaner.

#### 3.3: `bin/pos` `_pos_category_help()` (Priority: MEDIUM)

**Current state** (lines 68–123): Scans `pos-<cat>-*` files, reads `# POS:` and `# POS_SUBCMDS:` per file.

**After migration:**
```bash
_pos_category_help() {
    local cat="$1"
    source "$(dirname "$0")/../lib/registry.sh" 2>/dev/null || source "$(dirname "$0")/registry.sh"
    reg_scan
    
    echo "pos $cat — $cat tools"
    echo
    echo "USAGE"
    echo "  pos $cat <command> [args]"
    echo
    echo "COMMANDS"
    for tool in $(reg_tools_in "$cat"); do
        local desc deps
        desc="$(reg_lookup "$tool" desc)"
        deps="$(reg_lookup "$tool" deps)"
        printf '  %-28s%s' "$tool" "$desc"
        [ -n "$deps" ] && printf '  [deps: %s]' "$deps"
        echo
        # ... subcommands from reg_lookup "$tool" subcmds
    done
    echo
    echo "Run 'pos $cat <command> --help' for details on a command."
    exit 0
}
```

**Trade-off:** This adds a `reg_scan` call every time `pos <category>` runs. For 40 tools, the scan takes ~5ms — negligible for interactive use. If profiling shows this matters, `pos` could cache the scan in a temp file (but this is premature optimization).

**Alternative considered:** Keep `_pos_category_help()` using direct `sed` (no registry dependency). Rejected because the whole point is to centralize header parsing. The 5ms scan cost is acceptable.

#### 3.4: `lib/config-ui.sh` (Priority: LOW — separate decision)

**Current state** (lines 50–203): Has its own header parsing for `# POS_CONFIG:` and `# POS_KEYS:`. The config library is already a mature, working abstraction.

**Decision: Do NOT integrate config-ui.sh with the registry in this phase.**

**Rationale:**
1. config-ui.sh already works correctly and is well-tested.
2. Its parsing is specialized (multi-line key fields, `*plugins` expansion, `*providers` expansion).
3. Integrating it with the registry would require the registry to handle all config-ui's edge cases, bloating the library.
4. config-ui.sh's `cfg_headers()` / `cfg_scopes()` / `cfg_scope_keys()` API is already the "registry" for config consumers.

**Future:** When config-ui.sh needs maintenance, it could source the registry for its initial scan. But this is not needed now.

### Rationale

| Option | Architecture | Advantages | Costs | Risks | When to choose |
|--------|-------------|------------|-------|-------|----------------|
| **A: Incremental migration** | Migrate tree + gen-docs first, then pos, defer config-ui | Lowest risk, proves value early, no breaking changes | Some consumers still use direct sed during transition | Low — transition period is harmless | **Chosen** — smallest risky step |
| B: Big-bang migration | Rewrite all consumers at once | Consistent from day one | High risk, many things can break, hard to review | High — one bad refactor breaks everything | Only if the codebase were much smaller |
| C: No migration — just add the library | Create registry.sh but don't change any consumers | Library exists for future use | No immediate value, consumers still duplicate logic | Low — but pointless | Only if the task were just "create a library" |

[DECIDED]

---

## Decision 4: Migration Strategy — Zero-Downtime Incremental

### Problem

40+ tools exist. All must keep working. The new headers are optional. No tool should require changes to function.

### Decision

**Phase 1 (this implementation):**
1. Create `lib/registry.sh` with full API.
2. Update `scripts/gen-docs.sh` to parse new headers (degrades gracefully when absent).
3. Migrate `bin/pos-tree` to use registry (proves runtime value).
4. Update `templates/pos-tool.sh` to document new headers.
5. Update `DOC/DEV.md` and `DOC/AGENT_Context_Project.md` with new header format.

**Phase 2 (future, out of scope):**
1. Migrate `bin/pos` `_pos_category_help()` to use registry.
2. Enhance `pos help` to show registry metadata (deps, examples).
3. Add `# POS_DEPS:` and `# POS_EXAMPLES:` to tools incrementally (start with 3–5 representative tools per category).

**Phase 3 (future, out of scope):**
1. `pos menu` — interactive menu from registry (new tool).
2. `pos dashboard` — status dashboard from registry (new tool).

### Incremental Adoption for Tool Authors

1. Add `# POS_DEPS: docker jq` to your tool's header block. Done — deps appear in registry.
2. Add `# POS_EXAMPLES: pos <tool> <args> | Description` lines. Done — examples appear in registry.
3. No other changes required. The tool keeps working exactly as before.
4. When you run `make gen`, the new metadata appears in generated docs.

### Tool Template Update

`templates/pos-tool.sh` gets new header documentation:

```bash
# ────────────────────────────────────────────────────────────────
# TEMPLATE — new `pos` CLI tool
#
#  1. Copy:     cp templates/pos-tool.sh bin/pos-<category>-<command>
#  2. Header:   add a `# POS:` line right after the shebang/strict-mode
#               lines (single source of truth for generated docs):
#                 # POS: <category> <command> — one-line description
#                 # POS_FLAGS: --flag1 --flag2   (flag-style tools only)
#                 # POS_SUBCMDS: sub1 sub2       (multi-command tools only)
#                 # POS_DEPS: binary1 binary2    (runtime deps, optional)
#                 # POS_EXAMPLES: pos <tool> <args> | Description  (optional)
#  3. ...
```

### Lint Gate Update

`scripts/lint-conventions.sh` gets a new WARN check:
- If `# POS_DEPS:` is present, validate that each token looks like a binary name (no spaces, no special chars). This is a soft check — WARN on malformed deps, not FAIL.

[DECIDED]

---

## Decision 5: Scope Boundaries

### Approved Scope

```text
In scope:
  lib/registry.sh                        — NEW FILE, ~180 lines
  scripts/gen-docs.sh                    — Extend tools array, add deps/examples to gen_* functions
  bin/pos-tree                           — Migrate to use registry (replace file-scanning loop)
  templates/pos-tool.sh                  — Document new headers in template comments
  DOC/DEV.md                             — Document new header format and registry usage
  DOC/AGENT_Context_Project.md           — Update line count table for lib/registry.sh, gen blocks updated by make gen
  scripts/lint-conventions.sh            — Optional: WARN for malformed POS_DEPS

Not in scope:
  bin/pos _pos_category_help()           — Phase 2 (future)
  pos help enhancements                  — Phase 2 (future)
  pos menu (new tool)                    — Phase 3 (future)
  pos dashboard (new tool)               — Phase 3 (future)
  Adding POS_DEPS/POS_EXAMPLES to existing tools — Individual tool authors, incremental
  lib/config-ui.sh integration          — Deferred (already works, specialized parsing)
  completions/pos.bash changes          — No new completion data needed (deps/examples aren't completable)
  install.sh changes                    — registry.sh is installed with existing lib/* loop
```

### What Builder Must NOT Do

1. Do NOT add `# POS_DEPS:` or `# POS_EXAMPLES:` to any existing tool in this PR (that's incremental migration, separate commits).
2. Do NOT change the `# POS:` header format or the em-dash convention.
3. Do NOT change `bin/pos` dispatch logic or `INTERACTIVE_CMDS`.
4. Do NOT add any new files beyond `lib/registry.sh`.
5. Do NOT modify the completion script (`completions/pos.bash`).
6. Do NOT refactor `lib/config-ui.sh` to use the registry.
7. Do NOT add a shebang to `lib/registry.sh` (it's a library, not executable).
8. Do NOT break `make gen && make check && make lint`.

[DECIDED]

---

## Decision 6: Risk Analysis

### Risk 1: `make gen` output changes break `git diff --exit-code` in CI

**Impact:** HIGH — blocks PRs.

**Cause:** Adding deps/examples parsing to gen-docs.sh changes the `tools` array format. The gen_* functions that consume this array will produce different output if any tool has the new headers. But since no tools have them yet, the output should be identical.

**Mitigation:** 
- The gen_* functions must produce **identical output** when no tools have `# POS_DEPS:` or `# POS_EXAMPLES:` headers.
- Test: run `make gen && git diff --exit-code` before committing. Zero diff = safe.
- The tools array format change (adding `$deps|$examples` fields) is internal to gen-docs.sh — the gen_* functions that render output must not use the new fields when they're empty.

### Risk 2: `reg_scan` performance degrades with many tools

**Impact:** LOW — current tool count is ~40.

**Cause:** Each tool file is read 4–6 times by `sed` during scan. For 40 tools, this is ~200 process spawns.

**Mitigation:**
- At current scale, scan completes in ~5ms. Even 100 tools would be ~15ms.
- If it ever becomes an issue, `reg_scan` could read each file once and parse all headers in a single `awk` pass. This is a future optimization, not needed now.

### Risk 3: Registry library conflicts with existing sourcing patterns

**Impact:** MEDIUM — could break tools that source both common.sh and registry.sh.

**Cause:** `registry.sh` declares guarded fallbacks for `log`, `warn`, `err` (same pattern as `config-ui.sh`). If both are sourced, the second source is a no-op because the functions already exist.

**Mitigation:**
- Use the same guarded-declaration pattern as `config-ui.sh`: `declare -F log >/dev/null || log() { ... }`.
- `registry.sh` does NOT define `run`, `spawn`, `confirm`, or any other common.sh functions.
- `registry.sh` does NOT call `err` during normal operation — only if `reg_scan` is called with an invalid directory (which won't happen in practice).

### Risk 4: `bin/pos-tree` migration breaks tree output

**Impact:** HIGH — visible to users.

**Cause:** The tree-building logic in `pos-tree` is tightly coupled to the current data collection. Replacing the collection loop might subtly change tree structure.

**Mitigation:**
- Keep the existing `add()`, `render()` functions unchanged.
- Replace ONLY the data-collection loop (lines 47–68) with registry calls.
- Test: run `bin/pos-tree` before and after, diff the output. Must be identical (for existing headers).
- The only visible change should be when a tool has `# POS_DEPS:` — deps appear in the tree.

### Risk 5: `pos <category>` performance regression

**Impact:** LOW — adds ~5ms per invocation.

**Cause:** `_pos_category_help()` would source and call `reg_scan` on every invocation.

**Mitigation:**
- Phase 2 only (not in this implementation).
- If needed, cache scan results in a temp file: `reg_scan` writes to `/tmp/.pos-registry-<hash>` and consumers check for freshness. This is premature — implement only if profiling shows a problem.

### Risk 6: New headers malformed, breaking parsing

**Impact:** LOW — malformed headers produce empty values, not crashes.

**Cause:** A tool author writes `# POS_DEPS` (missing colon) or `# POS_EXAMPLES foo bar` (missing pipe).

**Mitigation:**
- `reg_scan` uses strict pattern matching: `sed -n '/^# POS_DEPS: /{...}'`. Missing colon = no match = empty value. Graceful degradation.
- Add a lint WARN (not FAIL) for `# POS_DEPS:` lines without space-separated tokens.
- Add lint WARN for `# POS_EXAMPLES:` lines without `|` delimiter.
- Document the expected format clearly in DEV.md.

[DECIDED]

---

## Verification Plan

### Gate 1: Syntax

```bash
bash -n lib/registry.sh           # Must pass (no syntax errors)
bash -n scripts/gen-docs.sh       # Must pass (after modifications)
bash -n bin/pos-tree              # Must pass (after modifications)
```

### Gate 2: Gen Drift

```bash
make gen && git diff --exit-code   # Zero diff (no tools have new headers yet)
```

### Gate 3: Self-Consistency

```bash
make check    # Must pass (syntax + exec bits + doc/code sync + dispatch smoke)
```

### Gate 4: Convention Lint

```bash
make lint     # Must pass (0 FAIL, 0 WARN)
```

### Gate 5: Functional

```bash
# Registry works standalone
bash -c 'source lib/registry.sh; reg_scan; reg_list; reg_lookup docker ps desc'

# pos tree produces identical output
bin/pos-tree > /tmp/tree-before.txt
# ... apply changes ...
bin/pos-tree > /tmp/tree-after.txt
diff /tmp/tree-before.txt /tmp/tree-after.txt  # Must be empty

# pos category help works
bin/pos docker --help   # Must show docker tools
bin/pos network --help  # Must show network tools
```

### Gate 6: Regression

```bash
# All existing commands still dispatch
bin/pos --help
bin/pos docker --help
bin/pos network --help
bin/pos help network scan
```

---

## Implementation Guidance for Builder

### Step-by-step

1. **Create `lib/registry.sh`** (~180 lines). Start from the API spec in Decision 2. Use `lib/config-ui.sh` as a structural reference for the guarded fallbacks and source pattern.

2. **Update `scripts/gen-docs.sh`**. In the tools collection loop (lines 30–46):
   - Add `deps` and `examples` fields to the `tools` array format: `"$cat|$sub|$desc|$flags|$subcmds|$deps|$examples"`
   - Parse new headers with the same `sed` pattern as existing ones.
   - In `gen_tree()`, `gen_dispatch()`, `gen_filetable()`: add deps/examples columns ONLY when non-empty. Empty fields = identical output to current.

3. **Migrate `bin/pos-tree`**. Replace lines 47–68 (the file-scanning loop) with registry calls. Keep `add()`, `render()`, and the rest unchanged. Test that output is identical for existing tools.

4. **Update `templates/pos-tool.sh`**. Add `# POS_DEPS:` and `# POS_EXAMPLES:` to the header documentation block. Add them after the existing `# POS_FLAGS:` example.

5. **Update `DOC/DEV.md`**. In "Adding a New CLI Tool → Make it discoverable":
   - Document the new `# POS_DEPS:` and `# POS_EXAMPLES:` headers.
   - Explain when to use each (deps: list runtime binaries; examples: show 1–3 representative usages).

6. **Update `lib/registry.sh` line count** in `DOC/AGENT_Context_Project.md` filetable (the hand-maintained rows above the GEN marker).

7. **Run gates:** `make gen && make check && make lint`. Verify 0 FAIL, 0 WARN.

### Critical Constraints

- `lib/registry.sh` must NOT have a shebang (library, not executable).
- `lib/registry.sh` must be added to the `lib_names` list in `install.sh` Phase 2 (line 143).
- `reg_scan` must set `LC_ALL=C` for deterministic sort.
- gen-docs.sh changes must produce zero diff when no tools have new headers.
- `pos-tree` output must be byte-identical before/after migration (for existing headers).

---

## Open Questions (for Orchestrator)

1. Should `pos <category> --help` (in `bin/pos`) be migrated in this phase or deferred to Phase 2? **Recommendation: defer to Phase 2** — lower risk, and the category help is already working.

2. Should the lint gate enforce that `# POS_DEPS:` tokens are valid binary names? **Recommendation: WARN only, not FAIL** — some deps might be shell builtins or paths, not just binary names.

3. Should `reg_scan` support a `--cached` mode? **Recommendation: no, not yet** — premature optimization for 40 tools.

---

*Report written by Architect agent. Next recommended agent: **Builder** (to implement the approved scope).*