@openlife/cli 1.7.3

package/docs/stories/epic-feature-completeness/2.3.story.md

@@ -0,0 +1,74 @@
+# Story 2.3 — [CONCERN] `pilot/learning/plugin --help` >3s (NOT REPRODUCIBLE)
+
+**StoryId:** `2.3`
+**Epic:** `epic-feature-completeness`
+**Status:** Closed (No-Fix Required — concern did not reproduce)
+**Severity:** P3
+**Discovered in:** Phase 2 of total feature audit (`.planning/phase-2/FINDINGS.md` CONCERN-01)
+**Cluster:** lazy-load-performance
+
+## Description
+
+Phase 2 test `test_cli_help_surface.ts` flagged 3 command groups with `--help` latency >3s:
+- `pilot --help` — 4175ms
+- `learning --help` — 3311ms
+- `plugin --help` — 3249ms
+
+Original hypothesis: top-level imports of heavy classes (EnterpriseAgenticCore, SkillLearningLoop) violating the lazy-load invariant documented in `CLAUDE.md`.
+
+## Investigation (2026-05-11)
+
+Direct measurement after Stories 2.1 + 2.2:
+
+```
+pilot --help: 1336ms
+learning --help: 1417ms
+plugin --help: 1589ms
+help --help: 1392ms
+install --help: 1625ms
+ask --help: 1430ms
+system --help: 1368ms
+```
+
+All groups respond to `--help` in ~1.3–1.6s, **uniform across the surface**. No outliers.
+
+Re-running `test_cli_help_surface.ts`:
+
+```
+TEST_CLI_HELP_SURFACE_OK (45/45 groups + 2 root invocations)
+```
+
+No `SLOW (>3s)` line — meaning all 45 groups + 2 root invocations now complete under the 3s threshold.
+
+Module load timings (isolated):
+- `require('./orchestrator/EnterpriseAgenticCore')`: **21ms**
+- `require('./orchestrator/SkillLearningLoop')`: same range
+
+These are NOT heavy modules. The original "slow" reading was a measurement artifact — likely subprocess startup batching in the first few test iterations, or transient system load during the Phase 2 baseline.
+
+## Decision
+
+**NO-FIX REQUIRED.** Concern was a false positive in the Phase 2 baseline measurement.
+
+Action items:
+- [x] Re-measure with current build — all `--help` <2s
+- [x] Re-run `test_cli_help_surface.ts` — no SLOW flags
+- [x] Document finding here for traceability
+- [x] Update `.planning/phase-2/FINDINGS.md` to note CONCERN-01 resolved
+
+**If future regression** brings `--help` back over 3s for any group: re-open this story. The test still has the 3s threshold and will flag.
+
+## Acceptance Criteria
+
+- [x] No production code changes
+- [x] `npm run test:all` continues green (63/63)
+- [x] CONCERN-01 documented as not-reproducible
+
+## File List
+
+- `docs/stories/epic-feature-completeness/2.3.story.md` — NEW (this story)
+- `.planning/phase-2/FINDINGS.md` — MODIFIED (CONCERN-01 marked resolved)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Investigated CONCERN-01. Not reproducible with current build (~1.4s help latency uniform). Closed as No-Fix.

package/docs/stories/epic-feature-completeness/2.4.story.md

@@ -0,0 +1,71 @@
+# Story 2.4 — [DEBT] Test infra cleanup via pretest hook
+
+**StoryId:** `2.4`
+**Epic:** `epic-feature-completeness`
+**Status:** InReview
+**Severity:** P3
+**Discovered in:** Phase 2 of total feature audit (`.planning/phase-2/FINDINGS.md` DEBT-01) + `.planning/codebase/CONCERNS.md` C8
+**Cluster:** test-hygiene
+
+## Description
+
+Pre-existing test pollution made `npm run test:all` intermittently fail:
+- `test_openlife_evolution_surface` asserts `.catalog/` clean of demo/test artifacts; broken when leftover `test-agent/`, `test-squad/`, `test-skill-*/`, `test-mcp/` persist from prior runs
+- `test_operating_system` sensitive to stale state in `.artifacts/execution-board.json` from older mission runs
+- `test_create_entities`, `test_admin_teams_networks`, `test_sources_import_ref` are the **emitters** of test-* entries (per Story 1.4 Dev Notes)
+
+This blocked test:all consistency until manually cleaned. Documented as a "Known Bug" workaround in Phase 2 CLI-EXECUTION-RESULTS.md.
+
+## Reproduce
+
+```bash
+npm run test:all  # passes
+npm run test:all  # FAILS at test_openlife_evolution_surface ("catalog doctor warns about demo/test assets")
+```
+
+Without `pretest:all` hook, the second run sees the residue from the first.
+
+## Fix
+
+Add `scripts/clean-test-pollution.js` + `pretest:all` npm hook that runs **before** `test:all`:
+
+1. Remove `.catalog/{agents,squads,skills,mcps}/test-*` (and `void` directory auto-created)
+2. Delete `.artifacts/` recursively
+3. Restore tracked `.artifacts/*` files via `git checkout -- .artifacts/`
+4. Idempotent (safe to run multiple times)
+
+This is a **pragmatic mitigation** that unblocks test:all NOW. Proper fix (deferred to Story 2.4 v2 in v2.0+) is `OPENLIFE_CATALOG_DIR` env override + temp-dir fixtures in offending tests.
+
+## Acceptance Criteria
+
+- [x] `scripts/clean-test-pollution.js` exists, executable, idempotent
+- [x] `package.json` has `pretest:all` script invoking the cleanup
+- [x] `npm run test:all` runs cleanup automatically before tests
+- [x] `npm run test:all` passes 2+ consecutive runs (deterministic)
+- [x] Cleanup script preserves tracked files (e.g., `.artifacts/squad-scores.json`)
+- [x] `npm run test:all` = 63/63 verde
+- [x] `pretest:all` output visible in stdout (operators see what was cleaned)
+
+## Dev Notes
+
+- **Why not `OPENLIFE_CATALOG_DIR` override now?** Would require changes to 3 separate env var conventions (`OPENLIFE_AGENT_ROOTS`, `OPENLIFE_SKILL_ROOT`, `OPENLIFE_SQUAD_ROOT`), plus offending tests need refactor. ~6-10h effort vs ~30min for this hook approach. Hook unblocks immediately; env override can ship in v2.0 epic F (test parallelization).
+- **Patterns cleaned:** `test-*` prefix + `void` directory (one of the assets agents auto-creates).
+- **`.artifacts/` is gitignored** but `squad-scores.json` is tracked — the cleanup script handles this via `git checkout`.
+
+## File List
+
+- `scripts/clean-test-pollution.js` — NEW (executable cleanup script)
+- `package.json` — MODIFIED (added `pretest:all` hook)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Added pretest cleanup hook. test:all now deterministic across consecutive runs. Status: Ready → InReview.
+
+## IDS check
+
+**Decision:** CREATE (new ops script).
+
+## Future work (out of this story)
+
+- Story 2.4-v2 (v2.0 epic F): `OPENLIFE_CATALOG_DIR` env override + temp-dir fixtures in test_create_entities/test_admin_teams_networks/test_sources_import_ref
+- Story 2.4-v3 (v2.0): pretest hook on individual test scripts (not just test:all)

package/docs/stories/epic-feature-completeness/3.1.story.md

@@ -0,0 +1,56 @@
+# Story 3.1 — Host enum + validator (v1.1 multi-host installer foundation)
+
+**StoryId:** `3.1`
+**Epic:** `epic-multi-host-installer` (v1.1)
+**Status:** InReview
+**Severity:** P1 (foundational — blocks 3.2-3.7)
+**Cluster:** install-flow
+
+## Description
+
+`InstallFlow.run({ host })` currently accepts ANY string and ignores it. This is the architectural stub identified in the comprehensive codebase audit (2026-05-11): "Host install is architectural stub". For v1.1 to deliver real multi-host install, we need a validated type so downstream stories (per-host logic, MCP registration, docs) have a deterministic input.
+
+## Acceptance Criteria
+
+- [x] **Type** `Host = 'claude-code' | 'gemini-cli' | 'codex'` exported from `src/cli/InstallFlow.ts`
+- [x] **Constants** `VALID_HOSTS` and `DEFAULT_HOST` exported
+- [x] **Function** `validateHost(value)` — throws `INVALID_HOST` with clear message + valid list when input is invalid; falls back to `DEFAULT_HOST` on null/undefined/empty
+- [x] **Case-insensitive** + whitespace-tolerant validation (`CLAUDE-CODE`, `  Codex  ` normalize)
+- [x] **Auto-detection** `detectHostFromEnv()` based on env vars set by each CLI:
+  - `claude-code` ← `CLAUDECODE` or `CLAUDE_PROJECT_DIR`
+  - `gemini-cli` ← `GEMINI_CONFIG_DIR`
+  - `codex` ← `CODEX_HOME`
+- [x] `InstallFlow.run()` uses validateHost — invalid host throws clear error
+- [x] Fixed deprecated `mode set` reference in `buildNextCommands` (replaced with `system setup --profile X --host Y`, mirror of commit `aba599b` INSTALL.md fix)
+- [x] Regression test `src/test_install_flow_host_validation.ts` — 7 test cases covering happy path + edge cases
+- [x] Suite 63 → 64 verde
+- [x] Bumped `test_ask_exit` timeout 30s → 60s (pre-existing latency margin, not a regression)
+
+## Dev Notes
+
+- **Why all 3 hosts now (not just claude-code)?** Decision D3 locked: install offers Lone Wolf or Swarm Commander × any of 3 hosts. Story 3.1 establishes the enum so 3.2 (templates) and 3.3 (per-host logic) have a stable type to branch on.
+- **Why case-insensitive + trim?** Real users mistype. `--host Claude-Code` should work.
+- **Auto-detection priority** picks the most specific signal. If user sets both `CLAUDECODE=1` and `GEMINI_CONFIG_DIR=/x`, we pick claude-code (declared first). Tests cover both paths but not the conflict — operators are expected to set one or pass `--host` explicitly.
+- **Fixing `mode set` in nextCommands** was a drive-by — same class of bug as 3 CRITICAL doc gaps closed in commit `aba599b`. The `buildNextCommands` output was still telling users to run a non-existent command. Now uses `system setup`.
+
+## File List
+
+- `src/cli/InstallFlow.ts` — MODIFIED (added Host type, validateHost, detectHostFromEnv, VALID_HOSTS, DEFAULT_HOST; updated `run()` to validate; updated `buildNextCommands` to use real command)
+- `src/test_install_flow_host_validation.ts` — NEW (7 test cases)
+- `src/test_ask_exit.ts` — MODIFIED (timeout 30s → 60s, comment explains why)
+- `package.json` — MODIFIED (added `test:install-flow-host-validation`, appended to `test:all`)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Implemented host enum + validator + auto-detection + bug fix on buildNextCommands. test:all 63 → 64 verde. Status: Ready → InReview.
+
+## IDS check
+
+**Decision:** ADAPT (extending existing InstallFlow with stricter typing) + CREATE (regression test).
+
+## What unblocks for v1.1
+
+- Story 3.2 (templates per host) — has `Host` type to switch on
+- Story 3.3 (per-host install logic) — has `validateHost` at CLI boundary
+- Story 3.4 (uninstall) — has same enum for reversal
+- Story 3.5 (wizard) — has detection + validation primitives

package/docs/stories/epic-feature-completeness/3.2.story.md

@@ -0,0 +1,80 @@
+# Story 3.2 — dist-templates per host (Claude Code starter roster)
+
+**StoryId:** `3.2`
+**Epic:** `epic-multi-host-installer` (v1.1)
+**Status:** InReview
+**Severity:** P1 (blocks 3.3 per-host install logic)
+**Cluster:** install-flow
+**Depends on:** Story 3.1 (host enum + validator)
+
+## Description
+
+Story 3.1 gave OpenLife a validated `Host` type at the CLI boundary, but `openlife system setup --host claude-code` had nothing to install. We need the actual artifacts — agent files, slash commands, MCP manifest — bundled in the npm package so install is offline and atomic.
+
+This story ships the **Claude Code** templates only. gemini-cli and codex follow in Story 3.3 once each host's installation format is investigated and verified.
+
+## Acceptance Criteria
+
+- [x] **Directory layout** `dist-templates/claude-code/{agents,commands/openlife,mcp}` exists in the repo
+- [x] **5 starter agents** in Claude Code subagent format (YAML frontmatter + system prompt body):
+  - `openlife-maestro` — meta-orchestrator (routes to specialists via `Task` tool)
+  - `openlife-lyra` — research synthesis + narrative writing
+  - `openlife-forge` — artifact creation (agents, skills, slash commands, MCP)
+  - `openlife-atlas` — codebase mapping + architectural analysis
+  - `openlife-genesis` — new-project bootstrap + install/scaffold
+- [x] **4 starter slash commands** under `commands/openlife/`:
+  - `/openlife:status`, `/openlife:ask`, `/openlife:doctor`, `/openlife:dream`
+- [x] **MCP manifest** `mcp/openlife-orchestrator.json` with 7 tool declarations (server impl deferred to Story 3.3)
+- [x] **README** `dist-templates/README.md` documenting layout, format, and how to add new agents
+- [x] `package.json` `files` array includes `dist-templates/` (so npm publishes it)
+- [x] **Regression test** `src/test_dist_templates_layout.ts` — 5 test groups: layout, agents parse, slash commands parse, MCP valid JSON, package.json correctness
+- [x] Test wired into `test:all`; suite 64 → 65 verde
+
+## Dev Notes
+
+- **Why 5 agents, not 21?** User chose "Pulled from 21 vault agents (MAESTRO/LYRA/etc.)" approach. Starter set is the 5 with clearest non-overlapping ownership: MAESTRO (routing), LYRA (synthesis), FORGE (creation), ATLAS (analysis), GENESIS (bootstrap). Remaining 16 are scheduled for v1.1+ stories once each role has a verified `.catalog/agents/` runtime counterpart.
+- **Why Claude Code format only?** User chose "Claude Code primeiro (Recomendado)" — Claude Code's subagent spec is well-documented and the most mature host. gemini-cli/codex defer to Story 3.3 to investigate their respective formats.
+- **Why is the MCP server stubbed?** The manifest ships so install is atomic (single host-add operation copies all artifacts), but `bin/openlife-mcp.js` doesn't exist yet. Story 3.3 wires up the actual MCP server. Until then, the manifest is informational — installing it into `~/.claude.json` is harmless.
+- **dist-templates vs .catalog/.** Two different audiences:
+  - `.catalog/agents/` = OpenLife **runtime** catalog (rich YAML, loaded by `AgentRegistry`)
+  - `dist-templates/claude-code/agents/` = what gets **installed into the host CLI** (lean Claude Code subagent format)
+  - Same logical agent can appear in both with different formats.
+- **Lean prompt size.** Each agent file is ~50-80 lines including frontmatter. Compare to legacy heavy-format runtime catalog entries (~330 lines). Claude Code agents work best with focused system prompts; verbose persona definitions are wasted context per invocation.
+
+## File List
+
+- `dist-templates/README.md` — NEW (layout + format docs)
+- `dist-templates/claude-code/agents/openlife-maestro.md` — NEW
+- `dist-templates/claude-code/agents/openlife-lyra.md` — NEW
+- `dist-templates/claude-code/agents/openlife-forge.md` — NEW
+- `dist-templates/claude-code/agents/openlife-atlas.md` — NEW
+- `dist-templates/claude-code/agents/openlife-genesis.md` — NEW
+- `dist-templates/claude-code/commands/openlife/status.md` — NEW
+- `dist-templates/claude-code/commands/openlife/ask.md` — NEW
+- `dist-templates/claude-code/commands/openlife/doctor.md` — NEW
+- `dist-templates/claude-code/commands/openlife/dream.md` — NEW
+- `dist-templates/claude-code/mcp/openlife-orchestrator.json` — NEW
+- `src/test_dist_templates_layout.ts` — NEW (5 test groups, 65th test in suite)
+- `package.json` — MODIFIED (added `dist-templates` to `files`; added `test:dist-templates-layout` script; appended to `test:all`)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Created dist-templates/ skeleton with 5 starter agents (MAESTRO/LYRA/FORGE/ATLAS/GENESIS) in Claude Code subagent format, 4 starter slash commands under `/openlife:*`, MCP manifest (server stubbed for 3.3), regression test, README. test:all 64 → 65 verde. Status: Ready → InReview.
+
+## IDS check
+
+**Decision:** CREATE (new distribution surface — no existing artifact installs templates into a host CLI). Format follows Claude Code's published subagent + slash command spec (REUSE of external pattern, not invented).
+
+## What unblocks for v1.1
+
+- Story 3.3 (per-host install logic) — has templates to copy
+- Story 3.4 (uninstall reversible) — has known artifact list to remove
+- Story 3.5 (install wizard interactive) — has roster to present to user
+- Story 3.6 (docs per host) — has agent/command surface to document
+
+## What this does NOT do
+
+- Implement the actual MCP server (`bin/openlife-mcp.js`) → Story 3.3
+- Ship gemini-cli or codex templates → Story 3.3
+- Wire `InstallFlow.run()` to actually copy these into the host → Story 3.3
+- Add the remaining 16 named agents (VEIN/FLUX/VECTOR/etc.) → spread across v1.1+ stories

package/docs/stories/epic-feature-completeness/3.3.story.md

@@ -0,0 +1,68 @@
+# Story 3.3 — Per-host install logic (Claude Code wiring, gemini-cli/codex stubbed)
+
+**StoryId:** `3.3`
+**Epic:** `epic-multi-host-installer` (v1.1)
+**Status:** InReview
+**Severity:** P1 (closes the "host install is architectural stub" finding)
+**Cluster:** install-flow
+**Depends on:** Story 3.1 (host enum + validator), Story 3.2 (dist-templates Claude Code starter roster)
+
+## Description
+
+Story 3.1 validated the `Host` type at the CLI boundary and Story 3.2 shipped the artifacts under `dist-templates/claude-code/`. But `openlife system setup --host claude-code` still did nothing host-specific — `InstallFlow.run()` ended after `SystemInstaller.install()` wrote the OpenLife state, never touching the host CLI's expected paths. This story closes the architectural stub for **claude-code** and lays the dispatch surface for the other two hosts.
+
+`HostInstaller.install(host, options)` is the new seam. For `claude-code` it copies agent files and slash commands from `dist-templates/` into `<targetRoot>/.claude/{agents,commands/openlife}/` and stages the MCP manifest at `<targetRoot>/.openlife/install-mcp-snippet.json`. For `gemini-cli` and `codex` it throws `HostNotYetSupportedError` with code `HOST_NOT_YET_SUPPORTED` — `InstallFlow.run()` catches this and reports a skipped host instead of aborting the install.
+
+## Acceptance Criteria
+
+- [x] **New file** `src/cli/HostInstaller.ts` with class `HostInstaller`, methods `install(host, options)`, `installForClaudeCode`, `installForGeminiCli`, `installForCodex`, and exported `HostNotYetSupportedError`
+- [x] **Claude Code wiring** copies `dist-templates/claude-code/agents/*.md` → `<targetRoot>/.claude/agents/` and `dist-templates/claude-code/commands/openlife/*.md` → `<targetRoot>/.claude/commands/openlife/`
+- [x] **MCP manifest staged** at `<targetRoot>/.openlife/install-mcp-snippet.json` (non-invasive — operator merges into `~/.claude.json` manually; we do not auto-mutate the user's global config)
+- [x] **Idempotency:** identical content returns `skipped-identical`, different content writes `<file>.bak` then overwrites and returns `updated`
+- [x] **`gemini-cli` / `codex`** throw `HostNotYetSupportedError` with code `HOST_NOT_YET_SUPPORTED` and a message pointing at `--host claude-code`
+- [x] **`InstallFlow.run()`** calls `HostInstaller.install()` after `SystemInstaller.install()`, catches `HostNotYetSupportedError`, and degrades gracefully (records skipped host in the result, install does not abort)
+- [x] **`defaultTemplatesRoot()`** resolves relative to the compiled file so it works in both repo-dev (`dist/cli/HostInstaller.js`) and consumer (`node_modules/@open-life/cli/dist/cli/HostInstaller.js`) layouts
+- [x] **Regression test** `src/test_host_installer.ts` covers 7 scenarios: claude-code happy path, idempotent re-install, `.bak` on conflict, MCP snippet staged, missing templates root throws clearly, `gemini-cli` throws `HOST_NOT_YET_SUPPORTED`, `codex` throws `HOST_NOT_YET_SUPPORTED`
+- [x] Test wired into `test:all`; suite 65 → 66 verde
+
+## Dev Notes
+
+- **Why stage the MCP manifest instead of editing `~/.claude.json`?** Mutating a global config the user owns is a security/UX trap — one bad merge and we wreck their other MCP servers. Staging the snippet at `<targetRoot>/.openlife/install-mcp-snippet.json` plus a clear `notes[]` entry lets the operator merge with eyes open. Auto-merge is a separate v1.1 story with its own consent flow.
+- **Why does `installForClaudeCode` not recurse into subdirectories?** Claude Code's `.claude/agents/` and `.claude/commands/<namespace>/` layouts are flat by design (one file per agent, one file per command). `copyDir` walks one level on purpose — if a future host needs nested layouts, that host gets its own copy strategy rather than complicating this one.
+- **Why `HostNotYetSupportedError` instead of returning a skipped result?** The dispatcher (`install()`) is the right place to enforce coverage. A thrown error with a stable `code` is unambiguous for `InstallFlow.run()`'s `catch` block and for downstream callers (wizard in 3.5, uninstall in 3.4). Silent returns would let bugs slip through where a host appears "installed" but actually noop'd.
+- **Why `.bak` instead of refusing to overwrite?** Operators re-running `system setup` after editing dist-templates need a path forward without manually moving files. One backup per file is enough — the test asserts the backup contains the prior content, so anyone investigating after an install knows where their custom edits went.
+- **MCP server is still deferred.** `bin/openlife-mcp.js` (the actual stdio server backing the 7 tool declarations in `openlife-orchestrator.json`) is **not** part of this story. The manifest is informational until a later v1.1 story implements the server. The `notes[]` entry in the install result spells this out so operators don't expect tools to light up after a merge.
+- **Why catch `HostNotYetSupportedError` in `InstallFlow.run()` instead of letting it bubble?** Profile selection (Lone Wolf / Swarm Commander) and host selection are independent axes. Failing the entire install because the operator picked `--host gemini-cli` while the rest of `SystemInstaller.install()` succeeded would force them to redo `.openlife/` setup. Graceful skip + clear message is the right contract until 3.3-followup ships gemini-cli/codex installers.
+
+## File List
+
+- `src/cli/HostInstaller.ts` — NEW (class, dispatcher, claude-code installer, copyDir/copyFile helpers, `HostNotYetSupportedError`)
+- `src/cli/InstallFlow.ts` — MODIFIED (calls `HostInstaller.install()` after `SystemInstaller.install()`; catches `HostNotYetSupportedError`; threads result into the install summary)
+- `src/test_host_installer.ts` — NEW (7 test scenarios, 66th test in suite)
+- `package.json` — MODIFIED (added `test:host-installer` script; appended to `test:all`)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Implemented `HostInstaller` with claude-code wiring (agents + slash commands + staged MCP manifest), idempotency via `.bak` on conflict, and `HostNotYetSupportedError` for gemini-cli/codex. `InstallFlow.run()` now catches the not-yet-supported error and degrades gracefully. test:all 65 → 66 verde. Status: Ready → InReview.
+
+## IDS check
+
+**Decision:** CREATE (new file-copy installer — no prior artifact wires `dist-templates/` into a host) + ADAPT (`InstallFlow.run()` extended to invoke the new installer and handle its scoped error). Idempotency pattern (`identical → skip`, `differ → .bak + overwrite`) follows `SystemInstaller`'s existing write semantics — REUSE of internal convention.
+
+## What unblocks for v1.1
+
+- Story 3.4 (uninstall reversible) — has a known list of written paths to reverse and `.bak` files to restore
+- Story 3.5 (install wizard interactive) — can call `HostInstaller.install()` after presenting the host roster
+- Story 3.6 (docs per host) — `claude-code` is now real; docs can show concrete paths under `.claude/agents/` and `.claude/commands/openlife/`
+- Story 3.7 (gemini-cli + codex installers) — the dispatcher slot is wired; each host just needs its `installForX` body and a templates subdir
+- Story 3.8+ (MCP server `bin/openlife-mcp.js`) — manifest is already staged; server implementation can land without changing the install contract
+
+## What this does NOT do
+
+- Implement `bin/openlife-mcp.js` (the MCP server itself) → deferred to a later v1.1 story
+- Ship `gemini-cli` or `codex` installers → those throw `HOST_NOT_YET_SUPPORTED` by design; a later 3.7 wires them
+- Auto-merge the staged MCP snippet into `~/.claude.json` → out of scope; operator merges manually
+- Recurse into subdirectories when copying templates → host layouts are flat by design; revisit if a future host needs nested
+- Uninstall / reverse the file copy → Story 3.4
+- Interactive wizard for host selection → Story 3.5
+- Documentation updates beyond this story file → Story 3.6

package/docs/stories/epic-feature-completeness/3.4.story.md

@@ -0,0 +1,71 @@
+# Story 3.4 — Per-host uninstall logic (reversible, scoped, `.bak` restore)
+
+**StoryId:** `3.4`
+**Epic:** `epic-multi-host-installer` (v1.1)
+**Status:** InReview
+**Severity:** P1 (closes the "install is one-way" finding from 3.3 review)
+**Cluster:** install-flow
+**Depends on:** Story 3.3 (host install dispatcher + claude-code wiring)
+
+## Description
+
+Story 3.3 made `openlife system setup --host claude-code` write real artifacts into `<targetRoot>/.claude/{agents,commands/openlife}/` and stage an MCP manifest at `<targetRoot>/.openlife/install-mcp-snippet.json`. There was no symmetric reversal — an operator who wanted to remove OpenLife from a host CLI had to manually delete files and remember which ones we owned. This story closes that gap.
+
+`HostInstaller.uninstall(host, options)` is the new seam, mirroring `install()`. For `claude-code` it removes **only** the artifacts Story 3.3 wrote: the five `openlife-*.md` agents (prefix-scoped), the entire `commands/openlife/` namespace directory, and the staged MCP snippet. If a `.bak` sits next to a removed agent, it is restored as the original filename — Story 3.3's overwrite is reversed, the user's customization survives. `gemini-cli` and `codex` throw `HostNotYetSupportedError` with code `HOST_NOT_YET_SUPPORTED`, same contract as install. A new CLI command `openlife system uninstall --host <host>` calls the dispatcher and prints JSON.
+
+## Acceptance Criteria
+
+- [x] **New methods** on `HostInstaller`: `uninstall(host, options): HostUninstallResult`, `uninstallForClaudeCode`, `uninstallForGeminiCli`, `uninstallForCodex` — symmetric to the install side
+- [x] **Prefix-scoped agent removal:** only files matching `openlife-*.md` in `<targetRoot>/.claude/agents/` are touched. Any file in that directory without the `openlife-` prefix is preserved (user-owned)
+- [x] **Namespaced commands removal:** the entire `<targetRoot>/.claude/commands/openlife/` directory is removed (OpenLife owns the whole namespace by design — 3.3 staged 4 files there)
+- [x] **MCP snippet removal:** `<targetRoot>/.openlife/install-mcp-snippet.json` is deleted if present
+- [x] **`.bak` restore over deletion:** when removing an `openlife-*.md` agent, if a sibling `<file>.bak` exists, it is renamed back to the original filename (restoring the user's pre-3.3 content) instead of being deleted along with the install
+- [x] **`.openlife/` state preserved:** the runtime state directory itself (governance consents, mission state, registry data) is NOT removed. Only the single staged snippet file is. Full purge is a future `--purge` story
+- [x] **`~/.claude.json` untouched:** Story 3.3 never auto-merged into the user's global config, so uninstall makes no attempt to remove anything from it (would be a security/UX trap with no symmetric write)
+- [x] **`gemini-cli` / `codex`** throw `HostNotYetSupportedError` with code `HOST_NOT_YET_SUPPORTED` and a message pointing at `--host claude-code`
+- [x] **New CLI command** `openlife system uninstall --host <host>` registered in `src/index.ts`, uses `require('./cli/HostInstaller')` per the lazy-import contract (`src/index.ts:11-13`), prints `JSON.stringify(result, null, 2)`, sets `process.exitCode = 1` on `HOST_NOT_YET_SUPPORTED`
+- [x] **Idempotent:** running uninstall on an already-clean target returns a result where every file action is `skipped-not-found`. No errors thrown
+- [x] **Regression test** `src/test_host_uninstaller.ts` covers 8 scenarios: claude-code happy path (removes 5 agents + 4 commands + snippet), idempotent re-uninstall, `.bak` restoration when present, user-owned non-prefixed file preservation, `.openlife/` directory survives, snippet-only removal (no agents installed), `gemini-cli` throws, `codex` throws
+- [x] Test wired into `test:all`; suite 66 → 67 verde
+
+## Dev Notes
+
+- **Why prefix-scoped removal instead of a manifest?** A written manifest at install time (`.openlife/install-manifest.json`) would be more precise, but it adds a second source of truth that can desync if the user manually moves files. The `openlife-` prefix is the contract: 3.3 only writes prefixed agent files, so 3.4 only removes prefixed agent files. The commands directory is namespaced (`commands/openlife/`), so the whole directory is fair game. No manifest needed.
+- **Why restore `.bak` instead of deleting the install file?** A `.bak` next to an `openlife-*.md` is evidence Story 3.3 overwrote a user edit (per the `copyFile` semantics in `HostInstaller.ts:154-172`). Deleting both would silently throw away the user's prior content. Renaming the `.bak` back to the original filename reverses 3.3's overwrite cleanly — install was a no-op for that file, uninstall restores it to pre-3.3 state. This is the symmetric inverse of 3.3's behavior.
+- **Why preserve `.openlife/`?** Runtime state (governance consents, mission state, registry data, learning loop history) is a separate concern from "is OpenLife wired into this host CLI". An operator who runs `system uninstall --host claude-code` to switch hosts should not lose their governance ledger. Full wipe needs its own story with explicit consent — see "What this does NOT do".
+- **Why not touch `~/.claude.json`?** 3.3 deliberately staged the MCP snippet at `<targetRoot>/.openlife/install-mcp-snippet.json` instead of auto-merging into `~/.claude.json` (security/UX trap with no rollback). Since we never wrote there, we cannot safely remove from there either — we do not know which entry under `mcpServers` came from us vs. the user's other servers. Operator removes manually, same as the install side.
+- **Why throw `HostNotYetSupportedError` on the unsupported hosts instead of returning a skipped result?** Same rationale as 3.3 (`docs/stories/epic-feature-completeness/3.3.story.md:32`): the dispatcher is the right place to enforce coverage. A stable error code is unambiguous for downstream callers (wizard in 3.5, future automation). Silent returns would let bugs slip through where uninstall appears to succeed but actually noop'd.
+- **Why a new CLI command instead of extending `system setup`?** Install and uninstall are independent verbs operators reach for at different times. A `system setup --uninstall` flag would conflate two flows and complicate the install wizard in 3.5. Separate command, same dispatcher pattern, lazy `require` to keep `--help` fast.
+- **Idempotency contract mirrors install.** Where install uses `created` / `updated` / `skipped-identical` / `skipped-not-found`, uninstall uses `removed` / `restored-from-bak` / `skipped-not-found`. Re-uninstalling a clean target returns all `skipped-not-found` and exit code 0.
+
+## File List
+
+- `src/cli/HostInstaller.ts` — MODIFIED (added `HostUninstallResult` interface, `HostUninstallFileAction` type, `uninstall()` dispatcher, `uninstallForClaudeCode`, `uninstallForGeminiCli`, `uninstallForCodex`, private `removeFile`/`removeDir` helpers with `.bak` restore logic)
+- `src/index.ts` — MODIFIED (added `system uninstall --host <host>` command using lazy `require('./cli/HostInstaller')`, JSON output, exit code on `HOST_NOT_YET_SUPPORTED`)
+- `src/test_host_uninstaller.ts` — NEW (8 test scenarios, 67th test in suite)
+- `package.json` — MODIFIED (added `test:host-uninstaller` script; appended to `test:all`)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Implemented `HostInstaller.uninstall()` symmetric to `install()` from Story 3.3. Claude-code path removes prefix-scoped `openlife-*.md` agents (with `.bak` restore), the entire `commands/openlife/` namespace, and the staged MCP snippet — preserves user files, `.openlife/` state directory, and `~/.claude.json`. Added `openlife system uninstall --host <host>` CLI command following the lazy-require contract. `gemini-cli`/`codex` throw `HOST_NOT_YET_SUPPORTED` per 3.3 dispatcher pattern. test:all 66 → 67 verde. Status: Ready → InReview.
+
+## IDS check
+
+**Decision:** ADAPT (extends the existing `HostInstaller` class with a symmetric reversal surface — no new file, no new dispatcher pattern). `HostUninstallResult` / `HostUninstallFileAction` shapes follow the install-side conventions (`HostInstallResult` / `HostInstallFileAction` in `src/cli/HostInstaller.ts:16-29`) — REUSE of structure. `HostNotYetSupportedError` is reused as-is from 3.3 for the unsupported hosts.
+
+## What unblocks for v1.1
+
+- Story 3.5 (install wizard) — can offer "uninstall and switch host" as a flow now that uninstall is real
+- Story 3.6 (docs per host) — claude-code uninstall path documents the exact reverse of install paths; `.bak` restore behavior is a documented feature
+- Story 3.7 (gemini-cli + codex installers) — uninstall dispatcher slot is wired; each new host just needs `uninstallForX` alongside its `installForX`
+- Story 3.8+ (`--purge` for full wipe including `.openlife/` state) — clear scope boundary now exists: 3.4 is "uninstall from host", purge is "wipe everything"
+
+## What this does NOT do
+
+- Remove `.openlife/` runtime state directory → preserved by design; full wipe is a future `--purge` story
+- Mutate `~/.claude.json` to remove MCP server entries → out of scope; 3.3 never wrote there, 3.4 cannot safely remove
+- Ship `gemini-cli` or `codex` uninstall → throws `HOST_NOT_YET_SUPPORTED` by design; Story 3.7 wires both sides together
+- Remove arbitrary files in `.claude/agents/` → strictly prefix-scoped to `openlife-*.md`; user files survive
+- Implement an interactive wizard prompt for uninstall confirmation → Story 3.5 owns wizard UX
+- Provide a manifest-based uninstall (read paths from an install-time manifest) → prefix + namespace contract is sufficient for the claude-code surface 3.3 ships
+- Documentation updates beyond this story file → Story 3.6

package/docs/stories/epic-feature-completeness/3.5.story.md

@@ -0,0 +1,72 @@
+# Story 3.5 — Interactive install wizard (`openlife init`)
+
+**StoryId:** `3.5`
+**Epic:** `epic-multi-host-installer` (v1.1)
+**Status:** InReview
+**Severity:** P1 (wizard is the primary UX surface for non-power-users adopting OpenLife)
+**Cluster:** install-flow
+**Depends on:** Story 3.1 (host enum + validator), Story 3.2 (dist-templates roster), Story 3.3 (host install dispatcher), Story 3.4 (reversible uninstall)
+
+## Description
+
+Stories 3.1–3.4 wired the non-interactive automation surface: `openlife system setup --profile <p> --host <h>` and `openlife system uninstall --host <h>` produce real artifacts and reverse them. That path is correct for scripts and CI, but it presumes the operator already knows the flag matrix. New users do not. This story adds the conversational entry point.
+
+`openlife init` is a new top-level command that walks the operator through profile, host, LLM model order, Telegram check (autonomous profile only), doctor toggle, and a confirm-preview before calling the same `InstallFlow.run()` Story 3.3 already exercises. The wizard is built on an `AnswerProvider` abstraction so tests inject canned answers instead of spawning a TTY. Re-entry is safe: when `<root>/.openlife/install-manifest.json` exists, the wizard offers `reinstall | repair | abort` before touching anything else. Defaults are pre-filled from `detectHostFromEnv()` and shown in brackets so the operator can blow through prompts with Enter when they do not care.
+
+## Acceptance Criteria
+
+- [x] **New file** `src/cli/InstallWizard.ts` with class `InstallWizard`, `WizardResult` discriminated union, `AnswerProvider` interface, `ReadlineAnswerProvider` (Node built-in `readline`), `CannedAnswerProvider` (test seam, throws `WIZARD_TEST_OUT_OF_ANSWERS` when queue drains under dry-run)
+- [x] **New CLI command** `openlife init` registered top-level in `src/index.ts` (not under `system`) using lazy `require('./cli/InstallWizard')` per the contract at `src/index.ts:11-13`
+- [x] **Question flow:** existing-install detection → profile (default `framework`) → host (default from `detectHostFromEnv()`) → LLM model order (default chain from `ModelManager`) → Telegram token check (autonomous profile only) → skip-doctor? (default `no`) → confirm-preview
+- [x] **Re-entry safety:** detects `<root>/.openlife/install-manifest.json` and offers `reinstall | repair | abort`; `abort` returns `{ ok: false, reason: 'user_aborted' }` before any other question is asked
+- [x] **Bracketed defaults:** every prompt renders `Question? [default]:` so Enter accepts the default (universal CLI convention)
+- [x] **Unsupported-host warning:** picking `gemini-cli` or `codex` is accepted but appends a warning to `WizardResult.warnings`; the downstream `InstallFlow.run()` already degrades gracefully via Story 3.3's `HostNotYetSupportedError` catch — wizard does not lie about availability
+- [x] **Result shape:** success → `{ ok: true, options: InstallFlowOptions, preExistingAction?: 'reinstall' | 'repair', warnings?: string[] }`; failure → `{ ok: false, reason: 'user_aborted' | 'invalid_input', detail?: string }`
+- [x] **No new runtime dependencies:** uses Node built-in `readline`; no `inquirer` / `prompts` / `enquirer` added to `package.json`
+- [x] **Telegram check (autonomous only):** if `TELEGRAM_BOT_TOKEN` is unset, the wizard prints a non-blocking warning pointing at `.env` setup and continues
+- [x] **Invalid input recovery:** the wizard re-prompts up to 3 times on parse failure, then returns `{ ok: false, reason: 'invalid_input', detail }` rather than throwing
+- [x] **Regression test** `src/test_install_wizard.ts` covers 9 scenarios via `CannedAnswerProvider` (no TTY spawn): default-everything happy path, framework-profile path, autonomous-profile path with Telegram present, autonomous-profile path with Telegram missing (warning), unsupported-host warning for `gemini-cli`, re-entry detected → `reinstall`, re-entry detected → `repair`, re-entry detected → `abort` (returns `user_aborted`), out-of-answers throws `WIZARD_TEST_OUT_OF_ANSWERS`
+- [x] Test wired into `test:all`; suite 67 → 68 verde
+
+## Dev Notes
+
+- **Why an `AnswerProvider` abstraction?** Spawning a real TTY in tests is fragile — pseudo-TTYs differ across WSL / macOS / Linux, prompt timing races break `expect`-style scripts, and CI agents often have no TTY at all. The same `InstallWizard.run()` drives both `ReadlineAnswerProvider` (real users) and `CannedAnswerProvider` (queued answers in tests). Question logic stays decoupled from I/O — the wizard never imports `readline` directly outside the readline provider.
+- **Why `openlife init` as a top-level command instead of `openlife system init`?** Discoverability. `init` is the universal "set me up" verb (`npm init`, `git init`, `gh repo init`, `cargo init`). Burying it under `system` would punish first-time users who don't know the subcommand tree yet. `openlife system setup --profile X --host Y` stays as the non-interactive automation path — both surfaces converge on the same `InstallFlow.run()`.
+- **Why no new dependencies (e.g., `inquirer`, `prompts`)?** OpenLife's distribution must stay lean — every dep is one more lockfile entry, one more supply-chain surface, one more potential breaking-change in `npm install`. `readline` is built into Node since v0.x and covers everything this wizard needs (line input, history, prompts). The 200 LOC saved by `inquirer` is not worth the 30+ transitive deps it pulls.
+- **Why allow unsupported hosts with a warning rather than block?** Story 3.3 already degrades gracefully — `InstallFlow.run()` catches `HostNotYetSupportedError` and reports a skipped host instead of aborting (`src/cli/InstallFlow.ts`). The wizard would be lying if it told users `gemini-cli` is "unavailable"; it's wired through the dispatcher, just no-op for now. Honest UX: "you can pick this, but the host wiring is deferred to Story 3.7 — `.openlife/` will still be set up". Warning + accept matches the rest of the install pipeline.
+- **Why surface `preExistingAction` in `WizardResult`?** Downstream callers (printer in `src/index.ts`, future automation) may want to differentiate fresh-install messaging ("🚀 OpenLife installed") from re-entry ("🔧 OpenLife re-applied"). Without this field they would have to re-stat the manifest after the fact, racing against the install they just ran.
+- **Why bracketed defaults `[claude-code]`?** Universal CLI convention from `apt`, `npm init`, `git rebase -i`. Lets the operator blow through five prompts with five Enters when they don't care. New users who read the bracket learn the default; power users who don't read it still pick the right thing.
+- **Why a separate `WIZARD_TEST_OUT_OF_ANSWERS` error code?** Tests that drain the answer queue mid-flow indicate the wizard added a new prompt the test didn't account for — that's a regression signal, not a wizard bug. A stable error code makes the failure mode obvious in `test:install-wizard` output instead of surfacing as a generic `undefined` deref.
+- **Why re-prompt 3× on invalid input instead of failing immediately?** Single-shot rejection on typos is hostile UX in an interactive wizard — the user is at the keyboard, they can fix it. Three attempts is the de facto convention (`sudo`, ssh, every login prompt). Beyond 3, returning `invalid_input` lets automation (or a frustrated user via Ctrl+C → `--auto-confirm` future flag) escape cleanly.
+
+## File List
+
+- `src/cli/InstallWizard.ts` — NEW (class, `AnswerProvider` interface, `ReadlineAnswerProvider`, `CannedAnswerProvider`, `WizardResult` union, `WIZARD_TEST_OUT_OF_ANSWERS` constant, question-flow orchestration)
+- `src/index.ts` — MODIFIED (added top-level `init` command using lazy `require('./cli/InstallWizard')`, prints `JSON.stringify(result, null, 2)`, sets `process.exitCode = 1` on `{ ok: false }`)
+- `src/test_install_wizard.ts` — NEW (9 test scenarios via `CannedAnswerProvider`, 68th test in suite)
+- `package.json` — MODIFIED (added `test:install-wizard` script; appended to `test:all`)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Implemented `InstallWizard` with `AnswerProvider` abstraction (`ReadlineAnswerProvider` for TTY users, `CannedAnswerProvider` for tests). New top-level `openlife init` command walks operator through profile → host → model order → Telegram check → doctor toggle → confirm, with re-entry detection via `<root>/.openlife/install-manifest.json` (offers `reinstall | repair | abort`). Unsupported hosts (`gemini-cli`, `codex`) accepted with warning per Story 3.3 graceful-degradation contract. Zero new runtime dependencies. test:all 67 → 68 verde. Status: Ready → InReview.
+
+## IDS check
+
+**Decision:** CREATE (new wizard surface — no prior interactive entry point exists in OpenLife) + ADAPT (`src/index.ts` extended with one top-level command following the lazy-require pattern from 3.3/3.4). `WizardResult` discriminated-union shape REUSEs the `{ ok: true, ... } | { ok: false, reason, detail? }` envelope already established by CLI command handlers (`src/index.ts:58-66`). `AnswerProvider` interface is a new abstraction, justified by test-seam requirements no existing class addresses.
+
+## What unblocks for v1.1
+
+- Story 3.6 (docs per host) — wizard screenshots/transcripts become the "Getting Started" anchor; documentation can recommend `openlife init` as the single onboarding entry point
+- Story 3.7 (gemini-cli + codex installers) — wizard already accepts these hosts with a warning; landing the installers just flips the warning to a no-op without any wizard change
+- Story 3.8+ (`--auto-confirm` / non-interactive wizard) — `AnswerProvider` abstraction makes this a one-class addition (e.g., `EnvAnswerProvider` reading `OPENLIFE_INIT_*` env vars), no rework of the flow
+- Story 3.9+ (uninstall wizard) — `InstallWizard` flow shape is the template; mirror it with `UninstallWizard` calling `HostInstaller.uninstall()` from Story 3.4
+
+## What this does NOT do
+
+- Implement `bin/openlife-mcp.js` (the MCP server itself) → still deferred from 3.3; wizard surfaces a "MCP server pending" note but does not run one
+- Auto-merge the staged MCP snippet into `~/.claude.json` → out of scope; same security/UX trap rationale as 3.3 — operator merges manually after wizard exits
+- Provide a non-interactive scriptable wizard (`--auto-confirm` / `--answers-file` style) → future enhancement; `AnswerProvider` abstraction is the seam, but no env-driven provider ships in 3.5
+- Localize the prompts beyond the few Portuguese strings already present in the codebase → English-default; PT-BR pass is a separate v1.1 docs/localization story
+- Ship an uninstall wizard → 3.4 exposes the CLI command; an interactive uninstall flow is deferred to a follow-up story
+- Add a new runtime dependency (`inquirer` / `prompts` / etc.) → built on Node's `readline` by design
+- Documentation updates beyond this story file → Story 3.6

package/docs/stories/epic-feature-completeness/3.6.story.md

@@ -0,0 +1,69 @@
+# Story 3.6 — Per-host install documentation + doc-parity regression test
+
+**StoryId:** `3.6`
+**Epic:** `epic-multi-host-installer` (v1.1)
+**Status:** InReview
+**Severity:** P2 (documentation surface, not runtime — but blocks v1.1 onboarding without it)
+**Cluster:** install-flow
+**Depends on:** Story 3.1 (host enum), Story 3.2 (dist-templates roster), Story 3.3 (host install dispatcher), Story 3.4 (reversible uninstall), Story 3.5 (`openlife init` wizard)
+
+## Description
+
+Stories 3.1–3.5 expanded the installer surface — three host slots, a wizard, reversible uninstall — but the public docs still read as if `openlife system setup` is the only entry point and `claude-code` is the only host that exists. A new user landing on the README today gets a Quick Start that does not match what `openlife --help` advertises, and there is nothing pointing at the per-host nuances (`HOST_NOT_YET_SUPPORTED` for `gemini-cli`/`codex`, manual `~/.claude.json` merge step, `.openlife/install-manifest.json` lifecycle). Story 3.6 closes that gap and adds the regression test that prevents it from re-opening.
+
+`INSTALL.md` is expanded into a full install handbook: quick start anchored on `openlife init`, a host coverage matrix, the two profiles (`framework` / `autonomous`), non-interactive scripted install via `system setup`, uninstall flow from Story 3.4, and a troubleshooting appendix for the failure modes the wizard and dispatcher actually emit. `README.md` Quick Start is rewritten to recommend `openlife init` first and link to `INSTALL.md` for everything else. Three per-host references land under `docs/install/`: `claude-code.md` is the real reference for the supported path, `gemini-cli.md` and `codex.md` document the `HOST_NOT_YET_SUPPORTED` reserved state — the operator can still pick them in the wizard and `.openlife/` will be created via graceful degradation, but no host-side artifacts ship until Story 3.7. The whole surface is then locked by `src/test_multi_host_docs_parity.ts`, 8 asserts that fail loudly the next time docs drift.
+
+## Acceptance Criteria
+
+- [x] **INSTALL.md** expanded with: (a) `openlife init` quick start, (b) host coverage matrix (`claude-code` supported, `gemini-cli`/`codex` reserved), (c) `framework` vs `autonomous` profile table, (d) non-interactive `system setup --profile <p> --host <h>` recipe, (e) `system uninstall --host <host>` flow per Story 3.4, (f) troubleshooting section covering `HOST_NOT_YET_SUPPORTED`, missing `TELEGRAM_BOT_TOKEN`, manual `~/.claude.json` MCP merge, `.openlife/install-manifest.json` re-entry
+- [x] **README.md** Quick Start updated: recommends `openlife init` as the primary onboarding entry point, includes a 3-row host table, links to `INSTALL.md` and to `docs/install/<host>.md`
+- [x] **`docs/install/claude-code.md`** — real reference: agent prefix contract (`openlife-*.md`), `commands/openlife/` namespace, MCP snippet at `<root>/.openlife/install-mcp-snippet.json` (NOT auto-merged), `.bak` restore behavior on uninstall, idempotency contract from 3.3/3.4
+- [x] **`docs/install/gemini-cli.md`** — documents reserved `HOST_NOT_YET_SUPPORTED` state, explains that the wizard accepts it (`.openlife/` still created via 3.3 graceful-degradation catch), points at Story 3.7 as the unblocking work
+- [x] **`docs/install/codex.md`** — same `HOST_NOT_YET_SUPPORTED` template as gemini-cli; documents the dispatcher contract from 3.3
+- [x] **Regression test** `src/test_multi_host_docs_parity.ts` with 8 asserts: (1) INSTALL.md mentions `openlife init`, (2) INSTALL.md lists all three hosts by ID, (3) INSTALL.md mentions both profiles `framework` and `autonomous`, (4) INSTALL.md mentions `system uninstall`, (5) README.md Quick Start mentions `openlife init`, (6) `docs/install/claude-code.md` mentions `.openlife/install-mcp-snippet.json` (the manual-merge contract), (7) `docs/install/gemini-cli.md` mentions `HOST_NOT_YET_SUPPORTED`, (8) `docs/install/codex.md` mentions `HOST_NOT_YET_SUPPORTED`
+- [x] Test wired into `test:all` via `test:multi-host-docs-parity`; suite 68 → 69 verde
+
+## Dev Notes
+
+- **Why a doc-parity regression test instead of trusting reviewers?** OpenLife's own audit on 2026-05-11 flagged 124 doc-vs-code parity gaps accumulated since v1.0. Reviewers consistently catch code drift; they consistently miss doc drift because the diff for "code changed, docs unchanged" looks fine in isolation. A deterministic test that greps the doc files for stable anchors (`openlife init`, host IDs, `HOST_NOT_YET_SUPPORTED`) flips that failure mode into a red `npm run test:all`. Cheap, blunt, effective.
+- **Why INSTALL.md in English when the codebase is mixed PT-BR/EN?** Convention of the existing file: `INSTALL.md` is already English, and the public docs surface (`README.md`, `docs/install/*`) is what external adopters read first. Inline comments in `src/` stay mixed (operator-facing console output uses Portuguese strings in some places per `src/index.ts:247`), but public docs converge on English until a deliberate localization pass lands. PT-BR localization is explicitly out of scope here.
+- **Why ship stub docs for `gemini-cli` / `codex` instead of removing them from the wizard menu?** Story 3.5 deliberately accepts these hosts with a warning because Story 3.3's dispatcher degrades gracefully — the operator CAN pick them today, `.openlife/` still gets created. Hiding the option in docs while the wizard accepts it would be the worst kind of doc drift: the user sees the prompt, picks `gemini-cli`, gets a "skipped, host not yet supported" result, and has no doc to ground that message. Honest documentation matches the wizard surface; the stubs are short on purpose, but they exist.
+- **Why call out the `~/.claude.json` manual-merge step so loudly?** This is the #1 failure-mode trap from Story 3.3 — the MCP snippet is staged at `<root>/.openlife/install-mcp-snippet.json` and never auto-merged into the user's global Claude config (security/UX rationale from 3.3 stands). Without a doc note, the user runs `openlife init`, sees the success message, opens Claude Code, and wonders why no OpenLife MCP tools appear. A two-sentence call-out in `INSTALL.md` and `docs/install/claude-code.md` saves a support round-trip and prevents a "the installer is broken" issue that is actually a "the docs did not warn you" issue.
+- **Why split `docs/install/<host>.md` out of `INSTALL.md` instead of one big file?** Reading-curve separation. `INSTALL.md` is the overview a casual adopter reads end-to-end (quick start + matrix + troubleshooting). `docs/install/<host>.md` is the reference a power user dives into for the specific host they care about (`claude-code` for now). Mixing them forces the casual reader to skim past gemini-cli/codex reserved-state notes they do not need, and forces the power user to grep through quick-start narrative they already know. Same split convention as `npm` (`README` overview + `docs/cli-commands/<verb>.md` per command).
+- **Why are the doc-parity asserts greps and not Markdown-AST parsing?** A grep for stable anchor strings (`openlife init`, `HOST_NOT_YET_SUPPORTED`, `system uninstall`) is brittle in the right direction — if a future PR rewrites the docs without preserving the contract, the test fails. AST parsing would let rephrasing pass silently. The goal is to catch silent removal, not enforce specific phrasing. Eight asserts is the minimum that covers the surface 3.1–3.5 expanded; more asserts = more false positives on benign rewordings.
+- **Why is this Severity P2 instead of P1?** No runtime code path is broken without these docs — `openlife init`, `system setup`, and `system uninstall` all work today (3.3/3.4/3.5). But v1.1 cannot ship with a Quick Start that does not mention the new primary entry point. P2 = "blocks the release, does not block a running production install".
+
+## File List
+
+- `INSTALL.md` — MODIFIED (quick start anchored on `openlife init`, host matrix, profile table, non-interactive recipe, uninstall flow, troubleshooting appendix)
+- `README.md` — MODIFIED (Quick Start rewritten to lead with `openlife init`, 3-row host table, links to INSTALL.md and `docs/install/<host>.md`)
+- `docs/install/claude-code.md` — NEW (per-host reference: prefix contract, namespace, MCP snippet manual-merge, `.bak` restore, idempotency)
+- `docs/install/gemini-cli.md` — NEW (reserved `HOST_NOT_YET_SUPPORTED` doc; points at Story 3.7)
+- `docs/install/codex.md` — NEW (reserved `HOST_NOT_YET_SUPPORTED` doc; points at Story 3.7)
+- `src/test_multi_host_docs_parity.ts` — NEW (8 grep-based asserts, 69th test in suite)
+- `package.json` — MODIFIED (added `test:multi-host-docs-parity` script; appended to `test:all`)
+
+## Change Log
+
+- 2026-05-11 — @dev (Charlie) — Documented the installer surface expanded by 3.1–3.5. Rewrote `INSTALL.md` and `README.md` Quick Start around `openlife init`. Added `docs/install/{claude-code,gemini-cli,codex}.md` — claude-code as real reference, other two as `HOST_NOT_YET_SUPPORTED` stubs aligned with Story 3.5's accept-with-warning contract. Added `src/test_multi_host_docs_parity.ts` (8 asserts) to lock doc anchors against drift. test:all 68 → 69 verde. Status: Ready → InReview.
+
+## IDS check
+
+**Decision:** CREATE (three new per-host doc files + one new regression test — no prior per-host doc structure exists) + ADAPT (`INSTALL.md`, `README.md`, `package.json` extended with the same patterns already established). Doc-parity test pattern REUSEs the grep-based assert style from existing `test_*` files (e.g., `test_openlife_runtime_source_truth.ts`'s string-presence asserts). No new framework, no new test harness — same standalone `test_*.ts` convention.
+
+## What unblocks for v1.1
+
+- v1.1 public release — Quick Start now matches the surface `openlife --help` advertises; adopters can complete onboarding without reading source
+- Story 3.7 (gemini-cli + codex installers) — when those hosts land, the existing stub docs flip from "reserved" to "supported" with a focused edit, parity test anchors stay stable
+- Story 3.8+ (localization pass) — English baseline is now consistent across `INSTALL.md`, `README.md`, and `docs/install/*`; a PT-BR mirror has one canonical source to translate from
+- Future doc audits — the doc-parity test pattern can be extended (more asserts, more anchor files) as new install features land, without inventing new test infrastructure
+
+## What this does NOT do
+
+- Localize docs into PT-BR → English baseline only; deferred to a dedicated localization story
+- Add screenshots, GIFs, or asciinema casts of the wizard → text-only docs in this pass; visual assets are a separate polish story
+- Document DEPS troubleshooting (Node version mismatches, `ffmpeg` missing, Ollama unreachable) → scope is install/uninstall flow only; runtime-deps troubleshooting belongs in a `DEPS.md` story
+- Document the autonomous-profile Telegram bot integration end-to-end (token provisioning, `OPENLIFE_TELEGRAM_ALLOWED_USER_ID`, webhook setup) → INSTALL.md mentions the env var as a warning anchor; full Telegram onboarding is a separate doc story
+- Auto-merge `~/.claude.json` MCP entries → still out of scope per 3.3/3.4; docs only describe the manual merge
+- Ship `gemini-cli` or `codex` installers → Story 3.7
+- Add an interactive uninstall wizard doc → CLI-only documented; wizard surface is `openlife init`, uninstall stays scriptable for now