docs: mark IUH-M02 complete, start IUH-M03

M02 shipped as PR #431 (cd8b1f66) — password masking, hooks preview
stage with consent capture, and headless install path via
MOSAIC_ASSUME_YES + MOSAIC_ADMIN_*. Updates mission manifest,
task table, and scratchpad Session 4 with completion notes and
the finalize-stage hooks-gating follow-up to fold into M03.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/MISSION-MANIFEST.md

@@ -1,72 +1,57 @@
-# Mission Manifest — CLI Unification & E2E First-Run
+# Mission Manifest — Install UX Hardening
 
 > Persistent document tracking full mission scope, status, and session history.
 > Updated by the orchestrator at each phase transition and milestone completion.
 
 ## Mission
 
-**ID:** cli-unification-20260404
+**ID:** install-ux-hardening-20260405
-**Statement:** Transform the Mosaic CLI from a partially-duplicated, manually-assembled experience into a single cohesive entry point that installs, configures, and controls the entire Mosaic system. Every Mosaic package gets first-class CLI surface. The first-run experience works end-to-end with no manual stitching. Gateway token recovery is possible without the web UI. Opt-in telemetry uses the published telemetry clients.
+**Statement:** Close the remaining gaps in the Mosaic Stack first-run and teardown experience uncovered by the post-`cli-unification` audit. A user MUST be able to cleanly uninstall the stack; the wizard MUST make security-sensitive surfaces visible (hooks, password entry); and CI/headless installs MUST NOT hang on interactive prompts. The longer-term goal is a single cohesive first-run flow that collapses `mosaic wizard` and `mosaic gateway install` into one state-bridged experience.
-**Phase:** Complete
+**Phase:** Execution
-**Current Milestone:** —
+**Current Milestone:** IUH-M03
-**Progress:** 8 / 8 milestones
+**Progress:** 2 / 3 milestones
-**Status:** completed
+**Status:** active
 **Last Updated:** 2026-04-05
-**Release:** [`mosaic-v0.0.24`](https://git.mosaicstack.dev/mosaicstack/mosaic-stack/releases/tag/mosaic-v0.0.24) (`@mosaicstack/mosaic@0.0.24`, alpha — stays in 0.0.x until GA)
+**Parent Mission:** [cli-unification-20260404](./archive/missions/cli-unification-20260404/MISSION-MANIFEST.md) (complete)
+
+## Context
+
+Post-merge audit of `cli-unification-20260404` (AC-1, AC-6) validated that the first-run wizard covers first user, password, admin tokens, gateway instance config, skills, and SOUL.md/USER.md init. The audit surfaced six gaps, grouped into three tracks of independent value.
 
 ## Success Criteria
 
-- [x] AC-1: Fresh machine `bash <(curl …install.sh)` → single command lands on a working authenticated gateway with a usable admin token; no secondary manual wizards required
+- [x] AC-1: `mosaic uninstall` (top-level) cleanly reverses every mutation made by `tools/install.sh` — framework data, npm CLI, nested stack deps, runtime asset injections in `~/.claude/`, npmrc scope mapping, PATH edits. Dry-run supported. `--keep-data` preserves memory + user files + gateway DB. (PR #429)
-- [x] AC-2: `mosaic --help` lists every sub-package as a top-level command and is alphabetized for readability
+- [x] AC-2: `curl … | bash -s -- --uninstall` works without requiring a functioning CLI. (PR #429)
-- [x] AC-3: `mosaic auth`, `mosaic brain`, `mosaic forge`, `mosaic log`, `mosaic macp`, `mosaic memory`, `mosaic queue`, `mosaic storage`, `mosaic telemetry` each expose at least one working subcommand that exercises the underlying package
+- [x] AC-3: Password entry in `bootstrapFirstUser` is masked (no plaintext echo); confirm prompt added. (PR #431)
-- [x] AC-4: Gateway admin token can be rotated or recovered from the CLI alone — operator is never stranded because the web UI is inaccessible
+- [x] AC-4: Wizard has an explicit hooks stage that previews which hooks will be installed, asks for confirmation, and records the user's choice. `mosaic config hooks list|enable|disable` surface exists. (PR #431 — consent recorded in `state.hooks.accepted`; finalize-stage gating is a follow-up)
-- [x] AC-5: `mosaic telemetry` uses the published `@mosaicstack/telemetry-client-js` (from the Gitea npm registry); local OTEL stays for wide-event logging / post-mortems; remote upload is opt-in and disabled by default
+- [x] AC-5: `runConfigWizard` and `bootstrapFirstUser` accept a headless path (env vars + `--yes`) so `tools/install.sh --yes` + `MOSAIC_ASSUME_YES=1` completes end-to-end in CI without TTY. (PR #431)
-- [x] AC-6: Install → wizard → gateway install → TUI verification flow is a single cohesive path with clear state transitions and no dead ends
+- [ ] AC-6: `mosaic wizard` and `mosaic gateway install` are collapsed into a single cohesive entry point with shared state (no two-phase handoff via the 10-minute session file).
-- [x] AC-7: `@mosaicstack/mosaic` is the sole `mosaic` binary owner; `@mosaicstack/cli` is gone from the repo and all docs
+- [ ] AC-7: All milestones ship as merged PRs with green CI, closed issues, updated release notes.
-- [x] AC-8: All milestones ship as merged PRs with green CI, closed issues, and updated release notes
 
 ## Milestones
 
-| #   | ID     | Name                                                                     | Status | Branch                              | Issue                             | Started    | Completed  |
+| #   | ID      | Name                                                      | Status      | Branch                  | Issue | Started    | Completed  |
-| --- | ------ | ------------------------------------------------------------------------ | ------ | ----------------------------------- | --------------------------------- | ---------- | ---------- |
+| --- | ------- | --------------------------------------------------------- | ----------- | ----------------------- | ----- | ---------- | ---------- |
-| 1   | cu-m01 | Kill legacy @mosaicstack/cli package                                     | done   | chore/remove-cli-package-duplicate  | #398                              | 2026-04-04 | 2026-04-04 |
+| 1   | IUH-M01 | `mosaic uninstall` — top-level teardown + shell wrapper   | done        | feat/mosaic-uninstall   | #425  | 2026-04-05 | 2026-04-05 |
-| 2   | cu-m02 | Archive stale mission state + scaffold new mission                       | done   | docs/mission-cli-unification        | #399                              | 2026-04-04 | 2026-04-04 |
+| 2   | IUH-M02 | Wizard remediation — hooks visibility, pwd mask, headless | done        | feat/wizard-remediation | #426  | 2026-04-05 | 2026-04-05 |
-| 3   | cu-m03 | Fix gateway bootstrap token recovery (server + CLI paths)                | done   | feat/gateway-token-recovery         | #411, #414                        | 2026-04-05 | 2026-04-05 |
+| 3   | IUH-M03 | Unified first-run wizard (collapse wizard + gateway)      | in-progress | feat/unified-first-run  | #427  | 2026-04-05 | —          |
-| 4   | cu-m04 | Alphabetize + group `mosaic --help` output                               | done   | feat/help-sort + feat/mosaic-config | #402, #408                        | 2026-04-05 | 2026-04-05 |
-| 5   | cu-m05 | Sub-package CLI surface (auth/brain/forge/log/macp/memory/queue/storage) | done   | feat/mosaic-\*-cli (x9)             | #403–#407, #410, #412, #413, #415 | 2026-04-05 | 2026-04-05 |
-| 6   | cu-m06 | `mosaic telemetry` — local OTEL + opt-in remote upload                   | done   | feat/mosaic-telemetry               | #417                              | 2026-04-05 | 2026-04-05 |
-| 7   | cu-m07 | Unified first-run UX (install.sh → wizard → gateway → TUI)               | done   | feat/mosaic-first-run-ux            | #418                              | 2026-04-05 | 2026-04-05 |
-| 8   | cu-m08 | Docs refresh + release tag                                               | done   | docs/cli-unification-release-v0.1.0 | #419                              | 2026-04-05 | 2026-04-05 |
 
-## Deployment
+## Subagent Delegation Plan
 
-| Target               | URL       | Method                                          |
+| Milestone | Recommended Tier | Rationale                                                              |
-| -------------------- | --------- | ----------------------------------------------- |
+| --------- | ---------------- | ---------------------------------------------------------------------- |
-| Local tier (default) | localhost | `mosaic gateway install` — pglite + local queue |
+| IUH-M01   | sonnet           | Standard feature work — new command surface mirroring existing install |
-| Team tier            | any host  | `mosaic gateway install` — PG + Valkey          |
+| IUH-M02   | sonnet           | Small surgical fixes across 3-4 files                                  |
-| Docker Compose (dev) | localhost | `docker compose up` for PG/Valkey/OTEL/Jaeger   |
+| IUH-M03   | opus             | Architectural refactor; state machine design decisions                 |
 
-## Coordination
+## Risks
 
-- **Primary Agent:** claude-opus-4-6[1m]
+- **Reversal completeness** — runtime asset linking creates `.mosaic-bak-*` backups; uninstall must honor them vs. when to delete. Ambiguity without an install manifest.
-- **Sibling Agents:** sonnet (standard implementation), haiku (status/explore/verify), codex (coding-heavy tasks)
+- **npm global nested deps** — `npm uninstall -g @mosaicstack/mosaic` removes nested `@mosaicstack/*`, but ownership conflicts with explicitly installed peer packages (`@mosaicstack/gateway`, `@mosaicstack/memory`) need test coverage.
-- **Shared Contracts:** `docs/PRD.md` (existing v0.1.0 PRD — still the long-term target), this manifest, `docs/TASKS.md`, `docs/scratchpads/cli-unification-20260404.md`
+- **Headless bootstrap** — admin password via env var is a credential on disk; needs clear documentation that `MOSAIC_ADMIN_PASSWORD` is intended for CI-only and should be rotated post-install.
 
-## Token Budget
+## Out of Scope
 
-| Metric | Value  |
+- `mosaicstack.dev/install.sh` vanity URL (blocked on marketing site work)
-| ------ | ------ |
+- Uninstall for the `@mosaicstack/gateway` database contents — delegated to `mosaic gateway uninstall` semantics already in place
-| Budget | TBD    |
+- Signature/checksum verification of install scripts
-| Used   | ~80K   |
-| Mode   | normal |
-
-## Session History
-
-| Session | Runtime         | Started    | Duration | Ended Reason     | Last Task                                                    |
-| ------- | --------------- | ---------- | -------- | ---------------- | ------------------------------------------------------------ |
-| 1       | claude-opus-4-6 | 2026-04-04 | ~4h      | context-budget   | cu-m01 + cu-m02 merged (#398, #399); open questions resolved |
-| 2       | claude-opus-4-6 | 2026-04-05 | ~6h      | mission-complete | cu-m03..cu-m08 all merged; mosaic-v0.1.0 released            |
-
-## Scratchpad
-
-Path: `docs/scratchpads/cli-unification-20260404.md`

docs/TASKS.md

@@ -1,90 +1,40 @@
-# Tasks — CLI Unification & E2E First-Run
+# Tasks — Install UX Hardening
 
 > Single-writer: orchestrator only. Workers read but never modify.
 >
-> **Mission:** cli-unification-20260404
+> **Mission:** install-ux-hardening-20260405
 > **Schema:** `| id | status | description | issue | agent | branch | depends_on | estimate | notes |`
 > **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa`
-> **Agent values:** `codex` | `sonnet` | `haiku` | `opus` | `glm-5` | `—` (auto)
+> **Agent values:** `codex` | `sonnet` | `haiku` | `opus` | `—` (auto)
 
-## Milestone 1 — Kill legacy @mosaicstack/cli (done)
+## Milestone 1 — `mosaic uninstall` (IUH-M01)
 
-| id       | status | description                                                       | issue | agent | branch                             | depends_on | estimate | notes                       |
+| id        | status | description                                                                                                         | issue | agent  | branch                | depends_on | estimate | notes                                                  |
-| -------- | ------ | ----------------------------------------------------------------- | ----- | ----- | ---------------------------------- | ---------- | -------- | --------------------------- |
+| --------- | ------ | ------------------------------------------------------------------------------------------------------------------- | ----- | ------ | --------------------- | ---------- | -------- | ------------------------------------------------------ |
-| CU-01-01 | done   | Delete packages/cli directory; update workspace + docs references | #398  | opus  | chore/remove-cli-package-duplicate | —          | 5K       | Merged c39433c3. 6685 LOC−. |
+| IUH-01-01 | done   | Design install manifest schema (`~/.config/mosaic/.install-manifest.json`) — what install writes on first success   | #425  | sonnet | feat/mosaic-uninstall | —          | 8K       | v1 schema in `install-manifest.ts`                     |
+| IUH-01-02 | done   | `mosaic uninstall` TS command: `--framework`, `--cli`, `--gateway`, `--all`, `--keep-data`, `--yes`, `--dry-run`    | #425  | sonnet | feat/mosaic-uninstall | IUH-01-01  | 25K      | `uninstall.ts`                                         |
+| IUH-01-03 | done   | Reverse runtime asset linking in `~/.claude/` — restore `.mosaic-bak-*` if present, remove managed copies otherwise | #425  | sonnet | feat/mosaic-uninstall | IUH-01-02  | 12K      | file list hardcoded from mosaic-link-runtime-assets    |
+| IUH-01-04 | done   | Reverse npmrc scope mapping and PATH edits made by `tools/install.sh`                                               | #425  | sonnet | feat/mosaic-uninstall | IUH-01-02  | 8K       | npmrc reversed; no PATH edits found in v0.0.24 install |
+| IUH-01-05 | done   | Shell fallback: `tools/install.sh --uninstall` path for users without a working CLI                                 | #425  | sonnet | feat/mosaic-uninstall | IUH-01-02  | 10K      |                                                        |
+| IUH-01-06 | done   | Vitest coverage: dry-run output, `--all`, `--keep-data`, partial state, missing manifest                            | #425  | sonnet | feat/mosaic-uninstall | IUH-01-05  | 15K      | 14 new tests, 170 total                                |
+| IUH-01-07 | done   | Code review (independent) + remediation                                                                             | #425  | sonnet | feat/mosaic-uninstall | IUH-01-06  | 5K       |                                                        |
+| IUH-01-08 | done   | PR open, CI green, review, merge to `main`, close issue                                                             | #425  | sonnet | feat/mosaic-uninstall | IUH-01-07  | 3K       | PR #429, merge 25cada77                                |
 
-## Milestone 2 — Archive stale mission + scaffold new mission (done)
+## Milestone 2 — Wizard Remediation (IUH-M02)
 
-| id       | status | description                                                        | issue | agent | branch                       | depends_on | estimate | notes                             |
+| id        | status | description                                                                                                    | issue | agent  | branch                  | depends_on | estimate | notes                                           |
-| -------- | ------ | ------------------------------------------------------------------ | ----- | ----- | ---------------------------- | ---------- | -------- | --------------------------------- |
+| --------- | ------ | -------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------------- | ---------- | -------- | ----------------------------------------------- |
-| CU-02-01 | done   | Move stale MISSION-MANIFEST / TASKS / PRD-Harness to docs/archive/ | #399  | opus  | docs/mission-cli-unification | CU-01-01   | 3K       | Harness + storage missions done.  |
+| IUH-02-01 | done   | Password masking: replace plaintext `rl.question` in `bootstrapFirstUser` with masked TTY read + confirmation  | #426  | sonnet | feat/wizard-remediation | IUH-01-08  | 8K       | `prompter/masked-prompt.ts`                     |
-| CU-02-02 | done   | Scaffold new MISSION-MANIFEST.md, TASKS.md, scratchpad             | #399  | opus  | docs/mission-cli-unification | CU-02-01   | 5K       | This file + manifest + scratchpad |
+| IUH-02-02 | done   | Hooks preview stage in wizard: show `framework/runtime/claude/hooks-config.json` entries + confirm prompt      | #426  | sonnet | feat/wizard-remediation | IUH-02-01  | 12K      | `stages/hooks-preview.ts`; finalize gating TODO |
-| CU-02-03 | done   | PR review, merge, branch cleanup                                   | #399  | opus  | docs/mission-cli-unification | CU-02-02   | 2K       | Merged as 6f15a84c                |
+| IUH-02-03 | done   | `mosaic config hooks list\|enable\|disable` subcommands                                                        | #426  | sonnet | feat/wizard-remediation | IUH-02-02  | 15K      | `commands/config.ts`                            |
+| IUH-02-04 | done   | Headless path: env-var driven `runConfigWizard` + `bootstrapFirstUser` (`MOSAIC_ASSUME_YES`, `MOSAIC_ADMIN_*`) | #426  | sonnet | feat/wizard-remediation | IUH-02-03  | 12K      |                                                 |
+| IUH-02-05 | done   | Tests + code review + PR merge                                                                                 | #426  | sonnet | feat/wizard-remediation | IUH-02-04  | 10K      | PR #431, merge cd8b1f66                         |
 
-## Milestone 3 — Gateway bootstrap token recovery
+## Milestone 3 — Unified First-Run Wizard (IUH-M03)
 
-| id       | status | description                                                                                    | issue | agent  | branch | depends_on | estimate | notes                         |
+| id        | status      | description                                                                                                 | issue | agent | branch                 | depends_on | estimate | notes |
-| -------- | ------ | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----------------------------- |
+| --------- | ----------- | ----------------------------------------------------------------------------------------------------------- | ----- | ----- | ---------------------- | ---------- | -------- | ----- |
-| CU-03-01 | done   | Implementation plan for BetterAuth-cookie recovery flow (decision locked 2026-04-04)           | —     | opus   | —      | CU-02-03   | 4K       | Design locked; plan-only task |
+| IUH-03-01 | not-started | Design doc: unified state machine; decide whether `mosaic gateway install` becomes an internal wizard stage | #427  | opus  | feat/unified-first-run | IUH-02-05  | 10K      |       |
-| CU-03-02 | done   | Server: add recovery/rotate endpoint on apps/gateway/src/admin (gated by design from CU-03-01) | —     | sonnet | —      | CU-03-01   | 12K      |                               |
+| IUH-03-02 | not-started | Refactor `runWizard` to invoke gateway install as a stage; drop the 10-minute session-file bridge           | #427  | opus  | feat/unified-first-run | IUH-03-01  | 25K      |       |
-| CU-03-03 | done   | CLI: `mosaic gateway login` — interactive BetterAuth sign-in, persist session                  | —     | sonnet | —      | CU-03-02   | 10K      |                               |
+| IUH-03-03 | not-started | Preserve backward-compat: `mosaic gateway install` still works as a standalone entry point                  | #427  | opus  | feat/unified-first-run | IUH-03-02  | 10K      |       |
-| CU-03-04 | done   | CLI: `mosaic gateway config rotate-token` — mint new admin token via authenticated API         | —     | sonnet | —      | CU-03-03   | 8K       |                               |
+| IUH-03-04 | not-started | Tests + code review + PR merge                                                                              | #427  | opus  | feat/unified-first-run | IUH-03-03  | 12K      |       |
-| CU-03-05 | done   | CLI: `mosaic gateway config recover-token` — execute the recovery flow from CU-03-01           | —     | sonnet | —      | CU-03-03   | 10K      |                               |
-| CU-03-06 | done   | Install UX: fix the "user exists, no token" dead-end in runInstall bootstrapFirstUser path     | —     | sonnet | —      | CU-03-05   | 8K       |                               |
-| CU-03-07 | done   | Tests: integration tests for each recovery path (happy + error)                                | —     | sonnet | —      | CU-03-06   | 10K      |                               |
-| CU-03-08 | done   | Code review + remediation                                                                      | —     | haiku  | —      | CU-03-07   | 4K       |                               |
-
-## Milestone 4 — `mosaic --help` alphabetize + grouping
-
-| id       | status | description                                                                                                                                                                                                     | issue | agent  | branch | depends_on | estimate | notes                           |
-| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------------------- |
-| CU-04-01 | done   | Enable `configureHelp({ sortSubcommands: true })` on root program and each subgroup                                                                                                                             | —     | sonnet | —      | CU-02-03   | 3K       |                                 |
-| CU-04-02 | done   | Group commands into sections (Runtime, Gateway, Framework, Platform) in help output                                                                                                                             | —     | sonnet | —      | CU-04-01   | 5K       |                                 |
-| CU-04-03 | done   | Verify help snapshots render readably; update any docs with stale output                                                                                                                                        | —     | haiku  | —      | CU-04-02   | 3K       |                                 |
-| CU-04-04 | done   | Top-level `mosaic config` command — `show`, `get <key>`, `set <key> <val>`, `edit`, `path` — wraps packages/mosaic/src/config/config-service.ts (framework/agent config; distinct from `mosaic gateway config`) | —     | sonnet | —      | CU-02-03   | 10K      | New scope (decision 2026-04-04) |
-| CU-04-05 | done   | Tests + code review for CU-04-04                                                                                                                                                                                | —     | haiku  | —      | CU-04-04   | 4K       |                                 |
-
-## Milestone 5 — Sub-package CLI surface
-
-> Pattern: each sub-package exports `register<Name>Command(program: Command)` co-located with the library code (proven by `@mosaicstack/quality-rails`). Wire into `packages/mosaic/src/cli.ts`.
-
-| id       | status | description                                                                                               | issue | agent  | branch | depends_on | estimate | notes               |
-| -------- | ------ | --------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------- |
-| CU-05-01 | done   | `mosaic forge` — subcommands: `run`, `status`, `resume`, `personas list`                                  | —     | sonnet | —      | CU-02-03   | 18K      | User priority       |
-| CU-05-02 | done   | `mosaic storage` — subcommands: `status`, `tier show`, `tier switch`, `export`, `import`, `migrate`       | —     | sonnet | —      | CU-02-03   | 15K      |                     |
-| CU-05-03 | done   | `mosaic queue` — subcommands: `list`, `stats`, `pause/resume`, `jobs tail`, `drain`                       | —     | sonnet | —      | CU-02-03   | 12K      |                     |
-| CU-05-04 | done   | `mosaic memory` — subcommands: `search`, `stats`, `insights list`, `preferences list`                     | —     | sonnet | —      | CU-02-03   | 12K      |                     |
-| CU-05-05 | done   | `mosaic brain` — subcommands: `projects list/create`, `missions list`, `tasks list`, `conversations list` | —     | sonnet | —      | CU-02-03   | 15K      |                     |
-| CU-05-06 | done   | `mosaic auth` — subcommands: `users list/create/delete`, `sso list`, `sso test`, `sessions list`          | —     | sonnet | —      | CU-03-03   | 15K      | needs gateway login |
-| CU-05-07 | done   | `mosaic log` — subcommands: `tail`, `search`, `export`, `level <level>`                                   | —     | sonnet | —      | CU-02-03   | 10K      |                     |
-| CU-05-08 | done   | `mosaic macp` — subcommands: `tasks list`, `submit`, `gate`, `events tail`                                | —     | sonnet | —      | CU-02-03   | 12K      |                     |
-| CU-05-09 | done   | Wire all eight `register<Name>Command` calls into packages/mosaic/src/cli.ts                              | —     | haiku  | —      | CU-05-01…8 | 3K       |                     |
-| CU-05-10 | done   | Integration test: `mosaic <cmd> --help` exits 0 for every new command                                     | —     | haiku  | —      | CU-05-09   | 5K       |                     |
-
-## Milestone 6 — `mosaic telemetry`
-
-| id       | status | description                                                                                       | issue | agent  | branch | depends_on | estimate | notes                                          |
-| -------- | ------ | ------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ---------------------------------------------- |
-| CU-06-01 | done   | Add `@mosaicstack/telemetry-client-js` as dependency of `@mosaicstack/mosaic` from Gitea registry | —     | sonnet | —      | CU-02-03   | 3K       |                                                |
-| CU-06-02 | done   | `mosaic telemetry local` — status, tail, Jaeger link (wraps existing apps/gateway/src/tracing.ts) | —     | sonnet | —      | CU-06-01   | 8K       |                                                |
-| CU-06-03 | done   | `mosaic telemetry` — status, opt-in, opt-out, test, upload (uses telemetry-client-js)             | —     | sonnet | —      | CU-06-01   | 12K      | Dry-run mode when server endpoint not yet live |
-| CU-06-04 | done   | Persistent consent state in mosaic config; disabled by default                                    | —     | sonnet | —      | CU-06-03   | 5K       |                                                |
-| CU-06-05 | done   | Tests + code review                                                                               | —     | haiku  | —      | CU-06-04   | 5K       |                                                |
-
-## Milestone 7 — Unified first-run UX
-
-| id       | status | description                                                                                    | issue | agent  | branch | depends_on | estimate | notes |
-| -------- | ------ | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- |
-| CU-07-01 | done   | tools/install.sh: after npm install, hand off to `mosaic wizard` then `mosaic gateway install` | —     | sonnet | —      | CU-03-06   | 10K      |       |
-| CU-07-02 | done   | `mosaic wizard` and `mosaic gateway install` coordination: shared state, no duplicate prompts  | —     | sonnet | —      | CU-07-01   | 12K      |       |
-| CU-07-03 | done   | Post-install verification step: "gateway healthy, tui connects, admin token on file"           | —     | sonnet | —      | CU-07-02   | 8K       |       |
-| CU-07-04 | done   | End-to-end test on a clean container from scratch                                              | —     | haiku  | —      | CU-07-03   | 8K       |       |
-
-## Milestone 8 — Docs + release
-
-| id       | status | description                                                            | issue | agent  | branch | depends_on | estimate | notes |
-| -------- | ------ | ---------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- |
-| CU-08-01 | done   | Update README.md with new command tree, install flow, and feature list | —     | sonnet | —      | CU-07-04   | 8K       |       |
-| CU-08-02 | done   | Update docs/guides/user-guide.md with all new sub-package commands     | —     | sonnet | —      | CU-08-01   | 10K      |       |
-| CU-08-03 | done   | Version bump `@mosaicstack/mosaic`, publish to Gitea registry          | —     | opus   | —      | CU-08-02   | 3K       |       |
-| CU-08-04 | done   | Release notes, tag `v0.1.0-rc.N`, publish release on Gitea             | —     | opus   | —      | CU-08-03   | 3K       |       |

docs/archive/missions/cli-unification-20260404/MISSION-MANIFEST.md

@@ -0,0 +1,72 @@
+# Mission Manifest — CLI Unification & E2E First-Run
+
+> Persistent document tracking full mission scope, status, and session history.
+> Updated by the orchestrator at each phase transition and milestone completion.
+
+## Mission
+
+**ID:** cli-unification-20260404
+**Statement:** Transform the Mosaic CLI from a partially-duplicated, manually-assembled experience into a single cohesive entry point that installs, configures, and controls the entire Mosaic system. Every Mosaic package gets first-class CLI surface. The first-run experience works end-to-end with no manual stitching. Gateway token recovery is possible without the web UI. Opt-in telemetry uses the published telemetry clients.
+**Phase:** Complete
+**Current Milestone:** —
+**Progress:** 8 / 8 milestones
+**Status:** completed
+**Last Updated:** 2026-04-05
+**Release:** [`mosaic-v0.0.24`](https://git.mosaicstack.dev/mosaicstack/mosaic-stack/releases/tag/mosaic-v0.0.24) (`@mosaicstack/mosaic@0.0.24`, alpha — stays in 0.0.x until GA)
+
+## Success Criteria
+
+- [x] AC-1: Fresh machine `bash <(curl …install.sh)` → single command lands on a working authenticated gateway with a usable admin token; no secondary manual wizards required
+- [x] AC-2: `mosaic --help` lists every sub-package as a top-level command and is alphabetized for readability
+- [x] AC-3: `mosaic auth`, `mosaic brain`, `mosaic forge`, `mosaic log`, `mosaic macp`, `mosaic memory`, `mosaic queue`, `mosaic storage`, `mosaic telemetry` each expose at least one working subcommand that exercises the underlying package
+- [x] AC-4: Gateway admin token can be rotated or recovered from the CLI alone — operator is never stranded because the web UI is inaccessible
+- [x] AC-5: `mosaic telemetry` uses the published `@mosaicstack/telemetry-client-js` (from the Gitea npm registry); local OTEL stays for wide-event logging / post-mortems; remote upload is opt-in and disabled by default
+- [x] AC-6: Install → wizard → gateway install → TUI verification flow is a single cohesive path with clear state transitions and no dead ends
+- [x] AC-7: `@mosaicstack/mosaic` is the sole `mosaic` binary owner; `@mosaicstack/cli` is gone from the repo and all docs
+- [x] AC-8: All milestones ship as merged PRs with green CI, closed issues, and updated release notes
+
+## Milestones
+
+| #   | ID     | Name                                                                     | Status | Branch                              | Issue                             | Started    | Completed  |
+| --- | ------ | ------------------------------------------------------------------------ | ------ | ----------------------------------- | --------------------------------- | ---------- | ---------- |
+| 1   | cu-m01 | Kill legacy @mosaicstack/cli package                                     | done   | chore/remove-cli-package-duplicate  | #398                              | 2026-04-04 | 2026-04-04 |
+| 2   | cu-m02 | Archive stale mission state + scaffold new mission                       | done   | docs/mission-cli-unification        | #399                              | 2026-04-04 | 2026-04-04 |
+| 3   | cu-m03 | Fix gateway bootstrap token recovery (server + CLI paths)                | done   | feat/gateway-token-recovery         | #411, #414                        | 2026-04-05 | 2026-04-05 |
+| 4   | cu-m04 | Alphabetize + group `mosaic --help` output                               | done   | feat/help-sort + feat/mosaic-config | #402, #408                        | 2026-04-05 | 2026-04-05 |
+| 5   | cu-m05 | Sub-package CLI surface (auth/brain/forge/log/macp/memory/queue/storage) | done   | feat/mosaic-\*-cli (x9)             | #403–#407, #410, #412, #413, #415 | 2026-04-05 | 2026-04-05 |
+| 6   | cu-m06 | `mosaic telemetry` — local OTEL + opt-in remote upload                   | done   | feat/mosaic-telemetry               | #417                              | 2026-04-05 | 2026-04-05 |
+| 7   | cu-m07 | Unified first-run UX (install.sh → wizard → gateway → TUI)               | done   | feat/mosaic-first-run-ux            | #418                              | 2026-04-05 | 2026-04-05 |
+| 8   | cu-m08 | Docs refresh + release tag                                               | done   | docs/cli-unification-release-v0.1.0 | #419                              | 2026-04-05 | 2026-04-05 |
+
+## Deployment
+
+| Target               | URL       | Method                                          |
+| -------------------- | --------- | ----------------------------------------------- |
+| Local tier (default) | localhost | `mosaic gateway install` — pglite + local queue |
+| Team tier            | any host  | `mosaic gateway install` — PG + Valkey          |
+| Docker Compose (dev) | localhost | `docker compose up` for PG/Valkey/OTEL/Jaeger   |
+
+## Coordination
+
+- **Primary Agent:** claude-opus-4-6[1m]
+- **Sibling Agents:** sonnet (standard implementation), haiku (status/explore/verify), codex (coding-heavy tasks)
+- **Shared Contracts:** `docs/PRD.md` (existing v0.1.0 PRD — still the long-term target), this manifest, `docs/TASKS.md`, `docs/scratchpads/cli-unification-20260404.md`
+
+## Token Budget
+
+| Metric | Value  |
+| ------ | ------ |
+| Budget | TBD    |
+| Used   | ~80K   |
+| Mode   | normal |
+
+## Session History
+
+| Session | Runtime         | Started    | Duration | Ended Reason     | Last Task                                                    |
+| ------- | --------------- | ---------- | -------- | ---------------- | ------------------------------------------------------------ |
+| 1       | claude-opus-4-6 | 2026-04-04 | ~4h      | context-budget   | cu-m01 + cu-m02 merged (#398, #399); open questions resolved |
+| 2       | claude-opus-4-6 | 2026-04-05 | ~6h      | mission-complete | cu-m03..cu-m08 all merged; mosaic-v0.1.0 released            |
+
+## Scratchpad
+
+Path: `docs/scratchpads/cli-unification-20260404.md`

docs/archive/missions/cli-unification-20260404/TASKS.md

@@ -0,0 +1,90 @@
+# Tasks — CLI Unification & E2E First-Run
+
+> Single-writer: orchestrator only. Workers read but never modify.
+>
+> **Mission:** cli-unification-20260404
+> **Schema:** `| id | status | description | issue | agent | branch | depends_on | estimate | notes |`
+> **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa`
+> **Agent values:** `codex` | `sonnet` | `haiku` | `opus` | `glm-5` | `—` (auto)
+
+## Milestone 1 — Kill legacy @mosaicstack/cli (done)
+
+| id       | status | description                                                       | issue | agent | branch                             | depends_on | estimate | notes                       |
+| -------- | ------ | ----------------------------------------------------------------- | ----- | ----- | ---------------------------------- | ---------- | -------- | --------------------------- |
+| CU-01-01 | done   | Delete packages/cli directory; update workspace + docs references | #398  | opus  | chore/remove-cli-package-duplicate | —          | 5K       | Merged c39433c3. 6685 LOC−. |
+
+## Milestone 2 — Archive stale mission + scaffold new mission (done)
+
+| id       | status | description                                                        | issue | agent | branch                       | depends_on | estimate | notes                             |
+| -------- | ------ | ------------------------------------------------------------------ | ----- | ----- | ---------------------------- | ---------- | -------- | --------------------------------- |
+| CU-02-01 | done   | Move stale MISSION-MANIFEST / TASKS / PRD-Harness to docs/archive/ | #399  | opus  | docs/mission-cli-unification | CU-01-01   | 3K       | Harness + storage missions done.  |
+| CU-02-02 | done   | Scaffold new MISSION-MANIFEST.md, TASKS.md, scratchpad             | #399  | opus  | docs/mission-cli-unification | CU-02-01   | 5K       | This file + manifest + scratchpad |
+| CU-02-03 | done   | PR review, merge, branch cleanup                                   | #399  | opus  | docs/mission-cli-unification | CU-02-02   | 2K       | Merged as 6f15a84c                |
+
+## Milestone 3 — Gateway bootstrap token recovery
+
+| id       | status | description                                                                                    | issue | agent  | branch | depends_on | estimate | notes                         |
+| -------- | ------ | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----------------------------- |
+| CU-03-01 | done   | Implementation plan for BetterAuth-cookie recovery flow (decision locked 2026-04-04)           | —     | opus   | —      | CU-02-03   | 4K       | Design locked; plan-only task |
+| CU-03-02 | done   | Server: add recovery/rotate endpoint on apps/gateway/src/admin (gated by design from CU-03-01) | —     | sonnet | —      | CU-03-01   | 12K      |                               |
+| CU-03-03 | done   | CLI: `mosaic gateway login` — interactive BetterAuth sign-in, persist session                  | —     | sonnet | —      | CU-03-02   | 10K      |                               |
+| CU-03-04 | done   | CLI: `mosaic gateway config rotate-token` — mint new admin token via authenticated API         | —     | sonnet | —      | CU-03-03   | 8K       |                               |
+| CU-03-05 | done   | CLI: `mosaic gateway config recover-token` — execute the recovery flow from CU-03-01           | —     | sonnet | —      | CU-03-03   | 10K      |                               |
+| CU-03-06 | done   | Install UX: fix the "user exists, no token" dead-end in runInstall bootstrapFirstUser path     | —     | sonnet | —      | CU-03-05   | 8K       |                               |
+| CU-03-07 | done   | Tests: integration tests for each recovery path (happy + error)                                | —     | sonnet | —      | CU-03-06   | 10K      |                               |
+| CU-03-08 | done   | Code review + remediation                                                                      | —     | haiku  | —      | CU-03-07   | 4K       |                               |
+
+## Milestone 4 — `mosaic --help` alphabetize + grouping
+
+| id       | status | description                                                                                                                                                                                                     | issue | agent  | branch | depends_on | estimate | notes                           |
+| -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------------------- |
+| CU-04-01 | done   | Enable `configureHelp({ sortSubcommands: true })` on root program and each subgroup                                                                                                                             | —     | sonnet | —      | CU-02-03   | 3K       |                                 |
+| CU-04-02 | done   | Group commands into sections (Runtime, Gateway, Framework, Platform) in help output                                                                                                                             | —     | sonnet | —      | CU-04-01   | 5K       |                                 |
+| CU-04-03 | done   | Verify help snapshots render readably; update any docs with stale output                                                                                                                                        | —     | haiku  | —      | CU-04-02   | 3K       |                                 |
+| CU-04-04 | done   | Top-level `mosaic config` command — `show`, `get <key>`, `set <key> <val>`, `edit`, `path` — wraps packages/mosaic/src/config/config-service.ts (framework/agent config; distinct from `mosaic gateway config`) | —     | sonnet | —      | CU-02-03   | 10K      | New scope (decision 2026-04-04) |
+| CU-04-05 | done   | Tests + code review for CU-04-04                                                                                                                                                                                | —     | haiku  | —      | CU-04-04   | 4K       |                                 |
+
+## Milestone 5 — Sub-package CLI surface
+
+> Pattern: each sub-package exports `register<Name>Command(program: Command)` co-located with the library code (proven by `@mosaicstack/quality-rails`). Wire into `packages/mosaic/src/cli.ts`.
+
+| id       | status | description                                                                                               | issue | agent  | branch | depends_on | estimate | notes               |
+| -------- | ------ | --------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------- |
+| CU-05-01 | done   | `mosaic forge` — subcommands: `run`, `status`, `resume`, `personas list`                                  | —     | sonnet | —      | CU-02-03   | 18K      | User priority       |
+| CU-05-02 | done   | `mosaic storage` — subcommands: `status`, `tier show`, `tier switch`, `export`, `import`, `migrate`       | —     | sonnet | —      | CU-02-03   | 15K      |                     |
+| CU-05-03 | done   | `mosaic queue` — subcommands: `list`, `stats`, `pause/resume`, `jobs tail`, `drain`                       | —     | sonnet | —      | CU-02-03   | 12K      |                     |
+| CU-05-04 | done   | `mosaic memory` — subcommands: `search`, `stats`, `insights list`, `preferences list`                     | —     | sonnet | —      | CU-02-03   | 12K      |                     |
+| CU-05-05 | done   | `mosaic brain` — subcommands: `projects list/create`, `missions list`, `tasks list`, `conversations list` | —     | sonnet | —      | CU-02-03   | 15K      |                     |
+| CU-05-06 | done   | `mosaic auth` — subcommands: `users list/create/delete`, `sso list`, `sso test`, `sessions list`          | —     | sonnet | —      | CU-03-03   | 15K      | needs gateway login |
+| CU-05-07 | done   | `mosaic log` — subcommands: `tail`, `search`, `export`, `level <level>`                                   | —     | sonnet | —      | CU-02-03   | 10K      |                     |
+| CU-05-08 | done   | `mosaic macp` — subcommands: `tasks list`, `submit`, `gate`, `events tail`                                | —     | sonnet | —      | CU-02-03   | 12K      |                     |
+| CU-05-09 | done   | Wire all eight `register<Name>Command` calls into packages/mosaic/src/cli.ts                              | —     | haiku  | —      | CU-05-01…8 | 3K       |                     |
+| CU-05-10 | done   | Integration test: `mosaic <cmd> --help` exits 0 for every new command                                     | —     | haiku  | —      | CU-05-09   | 5K       |                     |
+
+## Milestone 6 — `mosaic telemetry`
+
+| id       | status | description                                                                                       | issue | agent  | branch | depends_on | estimate | notes                                          |
+| -------- | ------ | ------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ---------------------------------------------- |
+| CU-06-01 | done   | Add `@mosaicstack/telemetry-client-js` as dependency of `@mosaicstack/mosaic` from Gitea registry | —     | sonnet | —      | CU-02-03   | 3K       |                                                |
+| CU-06-02 | done   | `mosaic telemetry local` — status, tail, Jaeger link (wraps existing apps/gateway/src/tracing.ts) | —     | sonnet | —      | CU-06-01   | 8K       |                                                |
+| CU-06-03 | done   | `mosaic telemetry` — status, opt-in, opt-out, test, upload (uses telemetry-client-js)             | —     | sonnet | —      | CU-06-01   | 12K      | Dry-run mode when server endpoint not yet live |
+| CU-06-04 | done   | Persistent consent state in mosaic config; disabled by default                                    | —     | sonnet | —      | CU-06-03   | 5K       |                                                |
+| CU-06-05 | done   | Tests + code review                                                                               | —     | haiku  | —      | CU-06-04   | 5K       |                                                |
+
+## Milestone 7 — Unified first-run UX
+
+| id       | status | description                                                                                    | issue | agent  | branch | depends_on | estimate | notes |
+| -------- | ------ | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- |
+| CU-07-01 | done   | tools/install.sh: after npm install, hand off to `mosaic wizard` then `mosaic gateway install` | —     | sonnet | —      | CU-03-06   | 10K      |       |
+| CU-07-02 | done   | `mosaic wizard` and `mosaic gateway install` coordination: shared state, no duplicate prompts  | —     | sonnet | —      | CU-07-01   | 12K      |       |
+| CU-07-03 | done   | Post-install verification step: "gateway healthy, tui connects, admin token on file"           | —     | sonnet | —      | CU-07-02   | 8K       |       |
+| CU-07-04 | done   | End-to-end test on a clean container from scratch                                              | —     | haiku  | —      | CU-07-03   | 8K       |       |
+
+## Milestone 8 — Docs + release
+
+| id       | status | description                                                            | issue | agent  | branch | depends_on | estimate | notes |
+| -------- | ------ | ---------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- |
+| CU-08-01 | done   | Update README.md with new command tree, install flow, and feature list | —     | sonnet | —      | CU-07-04   | 8K       |       |
+| CU-08-02 | done   | Update docs/guides/user-guide.md with all new sub-package commands     | —     | sonnet | —      | CU-08-01   | 10K      |       |
+| CU-08-03 | done   | Version bump `@mosaicstack/mosaic`, publish to Gitea registry          | —     | opus   | —      | CU-08-02   | 3K       |       |
+| CU-08-04 | done   | Release notes, tag `v0.1.0-rc.N`, publish release on Gitea             | —     | opus   | —      | CU-08-03   | 3K       |       |

docs/scratchpads/install-ux-hardening-20260405.md

@@ -68,6 +68,40 @@ ASSUMPTION: No PATH modifications in current install.sh (v0.0.24). Framework v0/
 ASSUMPTION: `--uninstall` in install.sh handles framework + cli + npmrc only; gateway teardown deferred to `mosaic gateway uninstall`.
 ASSUMPTION: Pi settings.json edits (skills paths) added by framework/install.sh are NOT reversed in this iteration — too risky to touch user Pi config without manifest evidence. Noted as follow-up.
 
+---
+
+## Session 2 — 2026-04-05 (orchestrator resume)
+
+### IUH-M01 completion summary
+
+- **PR:** #429 merged as `25cada77`
+- **CI:** green (Woodpecker)
+- **Issue:** #425 closed
+- **Files:** +1205 lines across 4 new + 2 modified + 1 docs
+- **Tests:** 14 new, 170 total passing
+
+### Follow-ups captured from worker report
+
+1. **Pi settings.json reversal deferred** — worker flagged as too risky without manifest evidence. Future IUH task should add manifest entries for Pi settings mutations. Not blocking M02/M03.
+2. **Pre-existing `cli-smoke.spec.ts` failure** — `@mosaicstack/brain` package entry resolution fails in Vitest. Unrelated to IUH-M01. Worth a separate issue later.
+3. **`pr-create.sh` wrapper bug with multiline bodies** — wrapper evals body args as shell when they contain newlines/paths. Worker fell back to Gitea REST API. Same class of bug I hit earlier with `issue-create.sh`. Worth a tooling-team issue to fix both wrappers.
+
+### Mission doc sync
+
+cli-unification docs that were archived before the M01 subagent ran did not travel into the M01 PR (they were local, stashed before pull). Re-applying now:
+
+- `docs/archive/missions/cli-unification-20260404/` (the old manifest + tasks)
+- `docs/MISSION-MANIFEST.md` (new install-ux-hardening content)
+- `docs/TASKS.md` (new install-ux-hardening content)
+
+Committing as `docs: scaffold install-ux-hardening mission + archive cli-unification`.
+
+### Next action
+
+Delegate IUH-M02 to a sonnet subagent in an isolated worktree.
+
+---
+
 ## Session 3: 2026-04-05 (agent-a6ff34a5) — IUH-M02 Wizard Remediation
 
 ### Plan
@@ -122,3 +156,45 @@ ASSUMPTION: The `hooks` subcommands under `config` operate on `~/.claude/hooks-c
 ASSUMPTION: For the hooks preview stage, the "name" field displayed per hook entry is the top-level event key (e.g. "PostToolUse") plus the matcher from nested hooks array. This is the most user-readable representation given the hooks-config.json structure.
 ASSUMPTION: `config hooks list/enable/disable` use `CLAUDE_HOME` env or `~/.claude` as the target directory for hooks files.
 ASSUMPTION: The headless TTY detection (`!process.stdin.isTTY`) is sufficient; `MOSAIC_ASSUME_YES=1` is an explicit override for cases where stdin is a TTY but the user still wants non-interactive (e.g., scripted installs with piped terminal).
+
+---
+
+## Session 4 — 2026-04-05 (orchestrator resume) — IUH-M02 closed, delegating IUH-M03
+
+### IUH-M02 completion summary
+
+- **PR:** #431 merged as `cd8b1f66`
+- **CI:** green (Woodpecker)
+- **Issue:** #426 closed
+- **Acceptance criteria:** AC-3 (password mask), AC-4 (hooks visibility — consent recorded), AC-5 (headless path) all satisfied
+- **New files:** `prompter/masked-prompt.ts`, `stages/hooks-preview.ts` (+ specs)
+- **Modified:** `wizard.ts`, `types.ts` (`state.hooks`), `commands/gateway/install.ts`, `commands/config.ts`
+
+### Follow-up captured from M02 agent
+
+**Hooks consent is recorded but not enforced.** The `hooks-preview` stage sets `state.hooks.accepted` when the user confirms, but the finalize stage still unconditionally runs `mosaic-link-runtime-assets`, which copies `hooks-config.json` into `~/.claude/` regardless of consent. This is a soft gap — the user sees the prompt and can decline, but declining currently has no effect downstream.
+
+Options for addressing:
+
+- Fold into IUH-M03 (since M03 touches the finalize/install convergence path anyway)
+- Spin a separate small follow-up issue after M03 lands
+
+Leaning toward folding into M03 — the unified first-run flow naturally reworks the finalize→gateway handoff where this gating belongs.
+
+### IUH-M03 delegation
+
+Now delegating to an **opus** subagent in an isolated worktree. Scope from `/tmp/iuh-m03-body.md`:
+
+- Extract `runConfigWizard` → `stages/gateway-config.ts`
+- Extract `bootstrapFirstUser` → `stages/gateway-bootstrap.ts`
+- `runWizard` invokes gateway stages as final stages
+- Drop the 10-minute `$XDG_RUNTIME_DIR/mosaic-install-state.json` session bridge
+- `mosaic gateway install` becomes a thin standalone wrapper for backward-compat
+- `tools/install.sh` single auto-launch entry point
+- **Bonus if scoped:** honor `state.hooks.accepted` in finalize stage so declining hooks actually skips hook install
+
+Known tooling caveats to pass to worker:
+
+- `issue-create.sh` / `pr-create.sh` wrappers eval multiline bodies as shell — use Gitea REST API fallback with `load_credentials gitea-mosaicstack`
+- Protected `main`: PR-only, squash merge
+- Must run `ci-queue-wait.sh --purpose push|merge` before push/merge