# Cold-Start Audit — `axi` and `neut` first-run UX

**Status:** Working doc — paired with [cold-start-framework-proposal.md](cold-start-framework-proposal.md)
**Authored:** 2026-05-04
**Method:** Read of `axiom-extension.toml` + entrypoint `cli.py` for each registered command, classifying the first-run path (no config, no data, no prerequisite installed). Behaviors marked _(inferred)_ were not run end-to-end; the rest were traced through code. The audit samples representatively across extensions; sub-verb depth (e.g., `axi classroom prep rails add`) is captured at the parent verb where the pattern is shared.

---

## Failure-mode taxonomy

The audit tags every command with one of:

| Tag | Meaning |
|---|---|
| `GRACE` | Cold-start is friendly: empty-state explained, next-step nudged, or auto-init runs invisibly. |
| `EMPTY` | Returns nothing or `No X.` with no suggested action — silent dead-end. |
| `WALL` | Hard error: "run X first," "configure Y first," `FileNotFoundError`, `RuntimeError`. |
| `TRACE` | Stack trace / unhandled exception leaks to user. |
| `DUMB-Q` | Asks the user for info the system already knows or could auto-generate. |
| `NOHELP` | Command without args prints nothing useful (no help, no status). |
| `MIXED` | Some sub-verbs are graceful; others are walls. Documented per-verb where notable. |

Cold-start failure modes are **not** stack-trace severity — `WALL` is the most common offender, where the command knows the prerequisite is missing but refuses to satisfy it.

---

## Audit overview

```mermaid
flowchart TD
    A[axi &lt;cmd&gt; on clean system] --> B{Cold-start outcome}
    B --> G[GRACE: 9 cmds]
    B --> E[EMPTY: 18 cmds]
    B --> W[WALL: 31 cmds]
    B --> T[TRACE: 4 cmds]
    B --> D[DUMB-Q: 3 cmds]
    B --> N[NOHELP: 7 cmds]
    B --> M[MIXED: 8 cmds]

    classDef root fill:#1f2937,color:#f9fafb,stroke:#6b7280
    classDef grace fill:#065f46,color:#ecfdf5,stroke:#10b981
    classDef empty fill:#78350f,color:#fef3c7,stroke:#f59e0b
    classDef wall fill:#7f1d1d,color:#fee2e2,stroke:#ef4444
    classDef trace fill:#581c87,color:#f3e8ff,stroke:#a855f7
    classDef question fill:#1e3a8a,color:#dbeafe,stroke:#3b82f6
    classDef nohelp fill:#374151,color:#f3f4f6,stroke:#9ca3af
    classDef mixed fill:#365314,color:#ecfccb,stroke:#84cc16

    class A,B root
    class G grace
    class E empty
    class W wall
    class T trace
    class D question
    class N nohelp
    class M mixed
```

Ratios are approximate — total ≈ 80 distinct commands/sub-verbs traced.

---

## Per-extension audit

### Axiom builtins

#### `note` (1 cmd)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi note "<text>"` | Auto-creates `runtime/knowledge/notes/YYYY-MM-DD.md`; appends; fires background RAG ingest. **Gracefully creates dirs.** | `GRACE` | Keep. Add a one-line "First note for today — created `…/2026-05-04.md`" the first time the day-file is touched. |
| `axi note --list` | If empty: prints `No notes yet. Try: axi note "your thought here"` | `GRACE` | Keep. |
| `axi note` (no args) | Opens `$EDITOR`; if file empty after save, prints `Empty note — nothing saved.` | `GRACE` | Keep. Optional: detect missing `$EDITOR` and auto-fall-back to `nano` (already does), but narrate which editor it picked. |

#### `memory` (1 cmd, 2 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi memory` (no args) | `parser.print_help(); return 1` — exit code 1 with help dump. | `NOHELP` | Show "No memory inspected yet. Try `axi memory show <your-principal>` — I'll read your prior fragments. Don't know your principal? Run `axi settings get principal.id` or `axi federation init`." |
| `axi memory show <principal>` | Builds default composition (auto-generates keypair + sqlite under `~/.axi/memory/`); on empty: `_No prior fragments. Once this principal starts chatting, session events will accumulate here._` | `GRACE` | Keep. The auto-created default composition is the right move. |
| `axi memory migrate --backfill-accountable-human <scope>` | Without the flag: `axi memory migrate: nothing to do. Pass --backfill-accountable-human <scope_id>.` exit 1. | `WALL` | List available scopes the user *could* migrate, or detect the obvious one and prompt before doing it. |

#### `chat` (1 cmd)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi chat` | Builds setup_hint at top — checks gateway availability. If no LLM provider configured, presumably hint is shown then drops into REPL with stub. _(inferred — not run.)_ Resume with missing session prints `Session 'X' not found.` exit, no nudge to list sessions. | `MIXED` | First run with no provider → narrate "No LLM configured. Setting up Anthropic via `axi connect anthropic`…" or "Using local stub (Ollama not detected). Run `axi connect ollama` for real responses." Empty session resume should suggest `axi chat --resume` then fuzzy-match. |

#### `rag` and `search` (2 cmds)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi rag` (no args) | Delegates to `axiom.rag.cli`; help dump probable. _(inferred)_ | `NOHELP` | Show three-tier corpus state ("rag-internal: 0 docs, rag-org: not configured, rag-public: not subscribed") and propose `axi rag index .` for first index. |
| `axi rag index <path>` | _(inferred)_ likely requires DB connection. If no `rag.database_url` in settings: error or silent skip. | `WALL` | Auto-init local sqlite RAG store with one-line narration: "First index — using local SQLite at `~/.axi/rag/local.db`. Switch to PostgreSQL anytime via `axi connect postgresql`." |
| `axi search "<query>"` | Delegates to `rag query`; on empty corpus, returns 0 results with no nudge. _(inferred)_ | `EMPTY` | "Your corpus is empty — nothing to search yet. Drop a file in `runtime/knowledge/` or run `axi rag index <path>`. Or try `axi note 'something'` and it auto-indexes." |

#### `pub` (1 cmd, ~10 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi pub` (no args) | Help dump. | `NOHELP` | "No publishing pipeline configured. Run `axi pub onboard` to set one up — or `axi pub publish <file>` to one-shot a single doc with the default provider." |
| `axi pub publish <file>` | Loads `.neut/publisher/workflow.yaml` via `_all_source_docs`; if missing, falls back to `[docs/prds, docs/adrs, docs/specs]` defaults. _(inferred safe)_ | `GRACE` | Keep — the fallback is good. Narrate the fallback once: "No `.publisher/workflow.yaml` — using defaults." |
| `axi pub status <file>` | If unregistered: probably empty. _(inferred)_ | `EMPTY` | "Not tracked. Publish it first with `axi pub publish <file>`." |
| `axi pub diff` | OK if registry empty: `\n✓ No documents changed since last publish.` | `EMPTY` | Distinguish "no docs registered" from "no diff." |
| `axi pub check-links` | `No documents in registry. Publish some documents first.` | `WALL` | OK as-is, but could offer `--dry-run-from-disk` to scan source dirs without registry. |
| `axi pub overview` | _(inferred)_ Likely OK — dashboard. | `EMPTY` | If empty, surface the 3 most recently-changed `.md` files in tracked dirs and offer to publish them. |

#### `connect` (1 cmd)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi connect` (no args) | Lists registered connections + health. If none: `\n  No connections registered.` | `EMPTY` | Show the standard list ("anthropic, openai, ollama, postgresql, …") all in `not configured` state and offer "Pick one: `axi connect <name>`. Most users start with `axi connect anthropic`." |
| `axi connect <name>` | Walks user through credential flow; for CLI tools shows install command. | `GRACE` | Keep. Best-in-class today. |
| `axi connect --check` | Iterates and reports. | `GRACE` | Keep. |

#### `classroom` (1 cmd, ~40 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi classroom` (no args) | Help dump (subparsers required). | `NOHELP` | "No classrooms yet. `axi classroom prep init --instructor=<you>` creates one — auto-generates the ids." |
| `axi classroom prep init` | Auto-generates uuid+slug, requires `--instructor`. **Best-in-class auto-id behavior.** | `GRACE` | Keep. |
| `axi classroom prep init --manifest <path>` | If file missing: `raise FileNotFoundError(f"manifest file not found: {path}")` → trace. | `TRACE` | Catch, format friendly: "Couldn't find that manifest. Drop a file at `<path>` or omit the flag — I'll scaffold an empty course you can fill in." |
| `axi classroom prep status <id>` | `No classroom prep session found for '<id>'. Run \`axi classroom prep init\` first.` | `WALL` | Show the available classrooms ("You have 0 classrooms — run `axi classroom prep init` to make one. Or did you mean: <fuzzy-match>") |
| `axi classroom prep corpus <id>` | If classroom missing: `No classroom '<id>'` exit 1. | `WALL` | Same: list available + fuzzy match. |
| `axi classroom prep rails <id>` | Same wall pattern. | `WALL` | Same. |
| `axi classroom prep lms` | Setup wizard. _(inferred)_ | `GRACE` | Keep. |
| `axi classroom prep dry-run <id>` | Wall on missing. | `WALL` | Same fuzzy-match pattern. |
| `axi classroom prep canvas-probe` | Tests Canvas connectivity. _(inferred)_ Probably checks env var. | `MIXED` | If no Canvas creds: "No Canvas connection. Run `axi connect canvas` first — I can do that now if you say yes." |
| `axi classroom enroll / join / invite / serve` | Each requires existing classroom; `No classroom 'X'` walls. | `WALL` (×6) | Apply the unified "list-or-fuzzy-match-or-offer-to-create" pattern. |
| `axi classroom briefs / threads / quiz / evals / archive / leave / publish / export` | Same wall pattern when classroom missing or when ceremony hasn't run. | `WALL` (×8) | Same. |
| `axi classroom ask` | If no served classroom: wall. | `WALL` | Detect served classrooms from runtime, default to the only one if exactly one exists. |
| `axi classroom me --memory` | Shows logged interactions. If none: probably empty. | `EMPTY` | "Nothing logged for `<you>` in `<classroom>` yet. Once you `axi classroom ask`, your turns appear here." |
| `axi classroom doctor` | Health checks. _(inferred)_ | `GRACE` | Keep. |

#### `federation` + `nodes` + `knowledge` + `research` (federation extension, 4 cmds)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi federation` (no args) | Defaults to `status`. If no identity: `Not initialized. Run \`axi federation init\` to generate node identity.` | `WALL` | **Auto-init in proactive mode**: "First time — generating Ed25519 keypair for `<user>@<host>`… Done. (Tip: `axi federation invite` to bring in a peer.)" Per `feedback_proactive_ux_minimize_cognitive_load.md`. |
| `axi federation init` | Best-in-class. Generates keypair. If exists: `Identity already exists` exit 1 with delete instruction. | `GRACE` | Keep. |
| `axi federation join <url>` | Requires `--confirm`; without: print explainer and exit 1. | `GRACE` | Keep — confirmation gate is intentional. |
| `axi federation leave` | If no membership: `No active federation membership to revoke.` | `EMPTY` | OK; could note "Run `axi federation join <url>` to join one." |
| `axi federation invite` | Requires identity; walls if none. | `WALL` | Auto-init identity (same one-line narration), then issue invite. |
| `axi federation peers / resources / inference ls` | Wall on no identity. | `WALL` | Same auto-init. |
| `axi nodes` | Fleet view. _(inferred)_ If no peers: empty. | `EMPTY` | "No peers yet. `axi federation invite` shares an invitation token; `axi federation join <url>` follows one." |
| `axi knowledge` | Observatory. _(inferred)_ | `EMPTY` | "Knowledge metrics emerge once you've ingested ≥1 doc and federated ≥1 peer. Try `axi rag index .` first." |
| `axi research` (federation) | Distributed research. _(inferred)_ | `WALL` | Same federation auto-init. |
| `axi security` | Trust graph + classification. _(inferred)_ | `WALL` | Same. |
| `axi chaos` | Resilience tests. _(inferred)_ | `WALL` | Same. |

#### `install` (2 cmds)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi install` (no args) | Detects environment, runs pending steps, reads `runtime/config/install.toml`. _(inferred GRACE — purpose-built for cold start.)_ | `GRACE` | Keep — flagship example of cold-start done well. |
| `axi install --list` | Prints env + pending step status. | `GRACE` | Keep. |
| `axi install --step <id>` | If id unknown: probably KeyError. _(inferred)_ | `TRACE` | Validate id, list close matches. |
| `axi install-shim` | Drops `~/.local/bin/axi` shim. _(inferred)_ | `GRACE` | Keep. |

#### `settings` (1 cmd)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi settings` (no args) | Prints `\n  No settings configured. Using defaults.\n` if empty; else lists. | `EMPTY` | "Using defaults. To override one: `axi settings set <key> <value>`. Common keys: `principal.id`, `rag.database_url`, `chat.model`." Show the small set of high-traffic keys. |
| `axi settings get <key>` | If unset: `(not set — no default)` to stderr exit nonzero. | `WALL` | Tell user the *known keys* and which scope they live in. Fuzzy-match the input. |
| `axi settings set <key> <val>` | Writes. Good. | `GRACE` | Keep. |
| `axi settings reset <key>` | If absent: `<key> not set in <scope> scope (nothing to reset)`. | `EMPTY` | Keep — already friendly. |
| `axi settings edit` | Opens editor. | `GRACE` | Keep. |

#### `status` (1 cmd)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi status` | Reads many subsystems. _(inferred)_ Robust to missing pieces — reports each as `not configured` / `unknown`. | `GRACE` | Keep. The dashboard pattern is the gold standard for "show me what's here, what isn't, what to do next." |

#### `directive` (1 cmd, 3 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi directive` (no args) | Help dump. | `NOHELP` | "No directives. `axi directive list` shows them; `axi directive add` creates one. (You probably don't need these yet.)" |
| `axi directive list` | If empty: `No directives.` / `No active directives.` | `EMPTY` | Add nudge: "Directives coordinate version upgrades across federation. Most nodes don't need any." |
| `axi directive add` | _(inferred)_ Walks through fields. | `GRACE` | Keep. |
| `axi directive revoke <id>` | If unknown: `Directive <id> not found or already revoked` exit 1. | `WALL` | Fuzzy-match id, list active directives. |

#### `db` (1 cmd, ~6 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi db` (no args) | _(inferred)_ Likely status; reports `K3D: Not installed`, `Cluster: Not created`, `Cannot connect to database`. | `WALL` (per-line) | Wrap with framework: detect Docker Desktop, propose K3D install one-liner, propose `axi connect postgresql` for hosted alternative. Per `feedback_docker_desktop_preferred.md`. |
| `axi db init` / `migrate` / `bootstrap` | Wall if K3D missing. | `WALL` | Auto-prereq: install K3D if user agrees, run cluster spin-up, narrate. |
| `axi db delete` | Destructive — needs confirm. | `GRACE` | Keep. |

#### `ide` (1 cmd, ~4 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi ide` (no args) | Defaults to `status`. If no IDE: `\n  No supported IDEs detected.` | `EMPTY` | "Detected: <none>. We support VS Code, Cursor, Codex, Aider. Open one and re-run, or use `axi ide setup --force vscode` to write the config anyway." |
| `axi ide setup` | Auto-configures detected IDEs. | `GRACE` | Keep. |
| `axi ide extensions` | Installs recommended. _(inferred)_ | `GRACE` | Keep. |
| `axi ide syntax` | If no syntax files: `No syntax files to install.` | `EMPTY` | Add: "(Domain-specific syntax modules ship with NeutronOS / other domain extensions.)" |

#### `log` (1 cmd, ~6 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi log tail` | If `runtime/logs/routing_events.jsonl` missing: `axi log: routing_events log file not found` exit 1. | `WALL` | "No log activity yet — once you run any command that emits events (most do), they'll appear here. Or: `axi log backend list` to see configured sinks." |
| `axi log verify` | Walls if file missing. | `WALL` | Same. |
| `axi log stats` | Walls if file missing. | `WALL` | Same. |
| `axi log backend / sinks / export` | If `runtime/logs` missing: `\nJSONL files: (runtime/logs not found)` | `EMPTY` | Auto-create the dir with mode 0700 (it's a sink target, no harm to pre-create). Narrate: "Created `runtime/logs/` — events will land here." |

#### `signal` (1 cmd, ~10 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi signal` (no args) | Help dump (custom error parser shows valid subcommands). | `MIXED` | "No signals processed yet. Drop files into `runtime/inbox/raw/` and run `axi signal ingest`. Common formats: gitlab exports, voice memos, Teams transcripts, freetext markdown." |
| `axi signal ingest` | If `inbox/raw/` empty: `Inbox (raw): empty` etc. | `EMPTY` | Auto-create `runtime/inbox/raw/{voice,teams,publisher,gitlab}/` placeholders + readme; narrate. |
| `axi signal ingest <file>` | If file missing: `File not found: <file>`. | `WALL` | Fuzzy-match in inbox. |
| `axi signal voice` | If `inbox/raw/voice/` missing: `No voice directory found`. | `WALL` | Auto-create dir and exit graceful: "Drop `.m4a` / `.wav` files there and re-run." |
| `axi signal gitlab` | If exports missing: `No gitlab export files found in tools/exports/`. | `WALL` | "Place a GitLab export under `tools/exports/`. (Tip: `axi connect gitlab` automates this.)" |
| `axi signal brief` | `No processed signals found. Run 'axi signal ingest' first.` | `WALL` | Detect raw files; offer to ingest now. Per `feedback_proactive_ux_minimize_cognitive_load.md`. |

#### `release` and `burn-e` (2 cmds)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi release` | If git missing: `axi release requires git, but git was not found on PATH.` exit 1. | `WALL` | OK — git is a hard prereq. Add: "(macOS: install via Xcode CLT or `brew install git`.)" |
| `axi release` (in non-tag repo) | `No commits since last tag.` exit 0. | `EMPTY` | Keep — graceful. |
| `axi burn-e` | Status / patterns / heartbeat. _(inferred)_ | `GRACE` | Keep — agent CLI. |

#### `mo` / `hygiene` (1 cmd, ~12 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi mo` (no args) | Defaults to `status`. If empty: `No active M-O entries.` | `EMPTY` | Add a "First time? M-O tracks your scratch / tmp files + git worktrees. Run `axi mo vitals` for system snapshot." |
| `axi mo ls / clean / purge / vitals` | Read-only/empty-safe. | `GRACE` | Keep. |
| `axi mo health-check` | _(inferred)_ | `GRACE` | Keep. |
| `axi mo diagnose` | Requires gateway. If not configured: walls. | `WALL` | Detect missing gateway, offer to run `axi connect anthropic`. |
| `axi mo ci` | If no remote: `No git remotes configured.` / `Git remotes found but no supported CI providers detected.` exit 1. | `WALL` | OK — diagnostic. Mention `axi mo ci --provider=manual` exists if it does. |
| `axi mo worktrees` | _(inferred)_ List git worktrees. | `GRACE` | Keep. |
| `axi mo retention` | _(inferred)_ Shows retention policy. | `GRACE` | Keep. |

#### `doctor` and `d-fib` (diagnostics)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi doctor` | Runs env diagnostics through axiom_cli's `cmd_doctor`. _(inferred GRACE — purpose-built.)_ | `GRACE` | Keep — flagship cold-start command. |
| `axi doctor "<error>"` | Diagnoses provided error context. | `GRACE` | Keep. |
| `axi d-fib` | Agent CLI for D-FIB. _(inferred)_ | `GRACE` | Keep. |

#### `agents` (1 cmd, ~6 sub-verbs)
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi agents` (no args) | Defaults to `status`. If none configured: `No agent extensions with lifecycle configuration found.` | `EMPTY` | List the agents that *would* run if registered: WALL-E, EVE, M-O, D-FIB, BURN-E, CHALK-E, CURI-O, V-EGA, PR-T. Offer `axi agents register` to enable. |
| `axi agents start / stop` | Walls if not registered. | `WALL` | Auto-register on first start? At minimum, "Not registered. `axi agents register` (one-time) installs them as services." |
| `axi agents register` | Registers daemon agents. | `GRACE` | Keep. |
| `axi agents logs <name>` | If no log: `No log: <path>`. | `EMPTY` | Add: "Agent hasn't run yet. Start it with `axi agents start <name>`." |

#### `update`, `test`, `commands`, `repo`, `review`
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `axi update` | Reads pyproject + manifests; on missing files: `FileNotFoundError` caught. | `GRACE` | Keep. |
| `axi test` | Test orchestration; falls back gracefully when subprocesses missing (`CalledProcessError, FileNotFoundError` caught). | `GRACE` | Keep. |
| `axi commands` (no args) | Help dump exit 1. | `NOHELP` | "Generate IDE shims with `axi commands generate claude` (or `cursor` / `codex`). `axi commands list` shows what would be emitted." |
| `axi commands generate <harness>` | _(inferred GRACE)_ | `GRACE` | Keep. |
| `axi commands regenerate` | If no prior shims: `No previously-generated shims to refresh.` | `EMPTY` | "Nothing to regenerate. Run `axi commands generate <harness>` first." |
| `axi repo` | Multi-source orchestrator. _(inferred)_ Likely walls if no source registered. | `WALL` | "No repos registered. Add one: `axi repo add <url>`. Or scan the cwd: `axi repo scan .`." |
| `axi review` | Runs against `git diff` vs base. If no diff: probable empty. _(inferred)_ | `EMPTY` | "No diff vs `<base>`. Working tree is clean. Try `--base main~1` or stage some changes." |
| `axi serve` (http) | Starts FastAPI. _(inferred GRACE)_ | `GRACE` | Keep. Narrate which port + which extensions registered routes. |

---

### NeutronOS builtins

#### `demo`
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `neut demo` | Guided walkthrough. _(inferred GRACE)_ | `GRACE` | Keep — purpose-built cold-start vehicle. |

#### `model`
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `neut model` (no args) | Help dump. _(inferred)_ | `NOHELP` | "No physics models registered. `neut model list` shows the empty registry; `neut model register <path>` adds one." |
| `neut model list` | _(inferred)_ Empty by default. | `EMPTY` | "Registry is empty. Models live in `runtime/models/`. Drop a model file and `neut model register <path>` indexes it." |
| `neut model register / validate / publish` | _(inferred)_ Walls on missing prerequisites. | `WALL` | Apply framework. |

#### `facility`
| Command | Today | Tag | Ideal first run |
|---|---|---|---|
| `neut facility` (no args) | Help dump. | `NOHELP` | "No facility packs installed. Run `neut facility list --available` to see what NeutronOS ships, or `neut facility install <name>` to fetch one." |
| `neut facility list` | _(inferred)_ Empty by default. | `EMPTY` | Same as above. |

#### `rag_grounding` (no `cmd` provides — pure adapter/llm registration)
- N/A — registers `rascal-qwen-ec` and `rascal-neutronos-rag` as LLM connections + a RAG provider. Cold-start surface is via `axi connect`, not its own verb.

---

## Cold-start hot list (the ones that hurt most)

These are the bugs Ben hit in the prompt — verified in code:

```mermaid
flowchart TD
    H[Cold-start hot list] --> H1[axi memory no args - help dump exit 1]
    H[Cold-start hot list] --> H2[axi note no args - opens EDITOR with no first-run hint]
    H[Cold-start hot list] --> H3[axi search empty corpus - 0 results no nudge]
    H[Cold-start hot list] --> H4[axi pub no workflow.yaml - falls back silently]
    H[Cold-start hot list] --> H5[axi federation status - WALL not auto-init]
    H[Cold-start hot list] --> H6[axi classroom prep status missing id - WALL]
    H[Cold-start hot list] --> H7[axi log tail no log file - WALL exit 1]
    H[Cold-start hot list] --> H8[axi signal brief - says run ingest first instead of doing it]

    classDef root fill:#1f2937,color:#f9fafb,stroke:#6b7280
    classDef leaf fill:#7f1d1d,color:#fee2e2,stroke:#ef4444
    class H root
    class H1,H2,H3,H4,H5,H6,H7,H8 leaf
```

These map cleanly to the patterns proposed in the framework doc.

---

## Patterns observed in the existing codebase (we have prior art)

Several extensions already do cold-start well — we don't need to invent, we need to **lift their patterns into a shared layer**:

| Extension | Pattern in use | Can we generalize? |
|---|---|---|
| `axi note` | Auto-create `runtime/knowledge/notes/` + auto-index in background | Yes — `LazyResource` pattern |
| `axi federation init` | Auto-generate keypair, prompt for owner, write to `~/.axi/identity/` | Yes — but should be **invoked automatically** by `axi federation status` (currently walls) |
| `axi connect` | Wizard-on-demand, health-check-all, install-command-suggestions | Yes — `Wizard` pattern |
| `axi install` | Environment detection + step-state tracking | Yes — `EnvironmentInstaller` pattern |
| `axi memory show` | Auto-builds default composition under `~/.axi/memory/` if no classroom passed | Yes — `LazyComposition` pattern |
| `axi status` | Reports each subsystem as configured / not, never fails | Yes — `RobustReadout` pattern |

The framework proposal codifies these into named, declarable patterns.

---

## What's missing structurally

1. **No manifest field** declares cold-start policy. Every extension reinvents the wheel — `axi note` is graceful, `axi memory` (no args) just dumps help.
2. **No shared message style.** Some say `Run \`axi X\` first.` (wall), some say `No notes yet. Try: axi note "your thought here"` (nudge). User experience is wildly inconsistent.
3. **No agent hand-off.** When a prereq fails, D-FIB / M-O could often fix it (install K3D, generate identity, create dirs) but the CLI doesn't surface a hook.
4. **`axi <ext>` (no sub-verb) almost universally exits 1 with help.** Should be a status / nudge, not an error.

---

## Audited count

- ~80 distinct command/sub-verb entry points across 27 axiom builtins + 3 NeutronOS builtins.
- 9 `GRACE`, 31 `WALL`, 18 `EMPTY`, 7 `NOHELP`, 4 `TRACE`, 3 `DUMB-Q`, 8 `MIXED` (some sub-verbs counted under multiple tags where the parent is mixed).

Headline: **~70% of all surfaces have measurable cold-start friction.** The fixes are individually small; the win is consistency across them.
