feat: unified first-run flow — merge wizard + gateway install (IUH-M03)

Collapse `mosaic wizard` and `mosaic gateway install` into a single cohesive
first-run experience. Gateway config and admin bootstrap now run as terminal
stages of `runWizard`, sharing `WizardState` with the framework stages and
eliminating the fragile 10-minute `$XDG_RUNTIME_DIR/mosaic-install-state.json`
session-file bridge.

- Extract `gatewayConfigStage` and `gatewayBootstrapStage` as first-class
  wizard stages with full spec coverage (headless + interactive paths).
- `mosaic gateway install` becomes a thin wrapper that invokes the same
  two stages — the CLI entry point is preserved for operators who only
  need to (re)configure the daemon.
- Honor explicit `--port` override even on resume: when the override
  differs from the saved GATEWAY_PORT, force a config regeneration so
  `.env` and `meta.json` cannot drift.
- Honor `state.hooks.accepted === false` in the finalize stage and in
  `mosaic-link-runtime-assets`: declined hooks are now actually opted-out,
  with a stable `mosaic-managed: true` marker in the template so cleanup
  survives template updates without touching user-owned configs.
- Headless rerun of an already-bootstrapped gateway with no local token
  cache is a successful no-op (no more false-positive install failures).
- `tools/install.sh` calls `mosaic wizard` only — the follow-up
  `mosaic gateway install` auto-launch is removed.

Closes mosaicstack/mosaic-stack#427.

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

docs/MISSION-MANIFEST.md

@@ -7,11 +7,11 @@
 
 **ID:** install-ux-hardening-20260405
 **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:** 3 / 3 milestones
+**Progress:** 2 / 3 milestones
-**Status:** complete
+**Status:** active
-**Last Updated:** 2026-04-05 (mission complete)
+**Last Updated:** 2026-04-05
 **Parent Mission:** [cli-unification-20260404](./archive/missions/cli-unification-20260404/MISSION-MANIFEST.md) (complete)
 
 ## Context
@@ -23,18 +23,18 @@ Post-merge audit of `cli-unification-20260404` (AC-1, AC-6) validated that the f
 - [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: `curl … | bash -s -- --uninstall` works without requiring a functioning CLI. (PR #429)
 - [x] AC-3: Password entry in `bootstrapFirstUser` is masked (no plaintext echo); confirm prompt added. (PR #431)
-- [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; PR #433 — finalize-stage gating now honors `state.hooks.accepted === false` end-to-end)
+- [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: `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: `mosaic wizard` and `mosaic gateway install` are collapsed into a single cohesive entry point with shared state; gateway install is now terminal stages 11 & 12 of `runWizard`, session-file bridge removed, `mosaic gateway install` preserved as a thin standalone wrapper. (PR #433)
+- [ ] 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: All milestones shipped as merged PRs with green CI and closed issues. (PRs #429, #431, #433)
+- [ ] AC-7: All milestones ship as merged PRs with green CI, closed issues, updated release notes.
 
 ## Milestones
 
-| #   | ID      | Name                                                      | Status | Branch                  | Issue | Started    | Completed  |
+| #   | ID      | Name                                                      | Status      | Branch                  | Issue | Started    | Completed  |
-| --- | ------- | --------------------------------------------------------- | ------ | ----------------------- | ----- | ---------- | ---------- |
+| --- | ------- | --------------------------------------------------------- | ----------- | ----------------------- | ----- | ---------- | ---------- |
-| 1   | IUH-M01 | `mosaic uninstall` — top-level teardown + shell wrapper   | done   | feat/mosaic-uninstall   | #425  | 2026-04-05 | 2026-04-05 |
+| 1   | IUH-M01 | `mosaic uninstall` — top-level teardown + shell wrapper   | done        | feat/mosaic-uninstall   | #425  | 2026-04-05 | 2026-04-05 |
-| 2   | IUH-M02 | Wizard remediation — hooks visibility, pwd mask, headless | done   | feat/wizard-remediation | #426  | 2026-04-05 | 2026-04-05 |
+| 2   | IUH-M02 | Wizard remediation — hooks visibility, pwd mask, headless | done        | feat/wizard-remediation | #426  | 2026-04-05 | 2026-04-05 |
-| 3   | IUH-M03 | Unified first-run wizard (collapse wizard + gateway)      | done   | feat/unified-first-run  | #427  | 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 | —          |
 
 ## Subagent Delegation Plan
 

docs/TASKS.md

@@ -32,10 +32,9 @@
 
 ## 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 |
-| --------- | ------ | ----------------------------------------------------------------------------------------------------------- | ----- | ----- | ---------------------- | ---------- | -------- | ---------------------------------- |
+| --------- | ----------- | ----------------------------------------------------------------------------------------------------------- | ----- | ----- | ---------------------- | ---------- | -------- | ----- |
-| IUH-03-01 | done   | 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      | scratchpad Session 5               |
+| 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      |       |
-| IUH-03-02 | done   | 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      | stages 11 & 12; bridge removed     |
+| 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      |       |
-| IUH-03-03 | done   | Preserve backward-compat: `mosaic gateway install` still works as a standalone entry point                  | #427  | opus  | feat/unified-first-run | IUH-03-02  | 10K      | thin wrapper over stages           |
+| 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      |       |
-| IUH-03-04 | done   | Tests + code review + PR merge                                                                              | #427  | opus  | feat/unified-first-run | IUH-03-03  | 12K      | PR #433, merge 732f8a49; +15 tests |
+| IUH-03-04 | not-started | Tests + code review + PR merge                                                                              | #427  | opus  | feat/unified-first-run | IUH-03-03  | 12K      |       |
-| IUH-03-05 | done   | Bonus: honor `state.hooks.accepted` in finalize stage (closes M02 follow-up)                                | #427  | opus  | feat/unified-first-run | IUH-03-04  | 5K       | MOSAIC_SKIP_CLAUDE_HOOKS env flag  |

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

@@ -279,52 +279,3 @@ plan (this entry) → code → typecheck/lint/format → test → codex review (
 - **Round 3** — hooks removal too broad (would touch user-owned files); port override written to meta but not .env (drift); wizard swallowed errors. Fixed: `cmp -s` managed-file check, force regeneration when portOverride differs from saved port, re-throw unexpected errors.
 - **Round 4** — port-override regeneration tripped the corrupt-partial-state guard (blocker); headless already-bootstrapped-with-no-local-token path reported failure instead of no-op; hooks byte-equality fragile across template updates. Fixed: introduce `forcePortRegen` flag bypassing the guard (with a dedicated spec test), headless rerun of already-bootstrapped gateway now returns `{ completed: true }` (with spec coverage), hooks cleanup now checks for a stable `"mosaic-managed": true` marker embedded in the template (byte-equality remains as a fallback for legacy installs).
 - Round 5 codex review attempted but blocked by upstream usage limit (quota). Rerun after quota refresh if further findings appear; all round-4 findings are code-covered.
-
----
-
-## Session 6 — 2026-04-05 (orchestrator close-out) — MISSION COMPLETE
-
-### IUH-M03 completion summary (reported by opus delivery agent)
-
-- **PR:** #433 merged as `732f8a49`
-- **CI:** Woodpecker green on final rebased commit `f3d5ef8d`
-- **Issue:** #427 closed with summary comment
-- **Tests:** 219 passing (+15 net new), 24 files
-- **Codex review:** 4 rounds applied and remediated; round 5 blocked by upstream quota — no known outstanding findings
-
-### What shipped in M03
-
-- NEW stages: `stages/gateway-config.ts`, `stages/gateway-bootstrap.ts` (extracted from the old monolithic `gateway/install.ts`)
-- NEW integration test: `__tests__/integration/unified-wizard.test.ts`
-- `runWizard` now has 12 stages — gateway config + bootstrap are terminal stages 11 & 12
-- 10-minute `$XDG_RUNTIME_DIR/mosaic-install-state.json` session-file bridge **deleted**
-- `mosaic gateway install` rewritten as a thin standalone wrapper invoking the same two stages — backward-compat preserved
-- `WizardState.gateway?` slice carries host/port/tier/admin/adminTokenIssued across stages
-- `tools/install.sh` single unified `mosaic wizard` call — no more two-phase launch
-- **Bonus scoped in:** finalize stage honors `state.hooks.accepted === false` via `MOSAIC_SKIP_CLAUDE_HOOKS=1`; `mosaic-link-runtime-assets` honors the flag; Mosaic-managed detection now uses a stable `"mosaic-managed": true` marker in `hooks-config.json` with byte-equality fallback for legacy installs. **Closes the M02 follow-up.**
-
-### Mission status — ALL DONE
-
-| AC   | Status | PR                                                   |
-| ---- | ------ | ---------------------------------------------------- |
-| AC-1 | ✓      | #429                                                 |
-| AC-2 | ✓      | #429                                                 |
-| AC-3 | ✓      | #431                                                 |
-| AC-4 | ✓      | #431 + #433 (gating)                                 |
-| AC-5 | ✓      | #431                                                 |
-| AC-6 | ✓      | #433                                                 |
-| AC-7 | ✓      | #429, #431, #433 all merged, CI green, issues closed |
-
-### Follow-ups for future work (not blocking mission close)
-
-1. **`pr-ci-wait.sh` vs Woodpecker**: wrapper reports `state=unknown` because Woodpecker doesn't publish to Gitea's combined-status endpoint. Worker used `tea pr` CI glyphs as authoritative. Pre-existing tooling gap — worth a separate tooling-team issue.
-2. **`issue-create.sh` / `pr-create.sh` wrapper `eval` bug with multiline bodies** — hit by M01, M02, M03 workers. All fell back to Gitea REST API. Needs wrapper fix.
-3. **Codex review round 5** — attempted but blocked by upstream quota. Rerun after quota resets to confirm nothing else surfaces.
-4. **Pi settings.json reversal** — deferred from M01; install manifest schema should be extended to track Pi settings mutations for reversal.
-5. **`cli-smoke.spec.ts` pre-existing failure** — `@mosaicstack/brain` resolution in Vitest. Unrelated. Worth a separate issue.
-
-### Next steps (orchestrator)
-
-1. This scratchpad + MISSION-MANIFEST.md + TASKS.md updates → final docs PR
-2. After merge: create release tag per framework rule (milestone/mission completion = release tag + repository release)
-3. Archive mission docs under `docs/archive/missions/install-ux-hardening-20260405/` once the tag is published

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.25",
+  "version": "0.0.24",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/mosaic-stack.git",