# Mission Manifest — Install UX v2

> Persistent document tracking full mission scope, status, and session history.
> Updated by the orchestrator at each phase transition and milestone completion.

## Mission

**ID:** install-ux-v2-20260405
**Statement:** The install-ux-hardening mission shipped the plumbing (uninstall, masked password, hooks consent, unified flow, headless path), but the first real end-to-end run surfaced a critical regression and a collection of UX failings that make the wizard feel neither quick nor intelligent. This mission closes the bootstrap regression as a hotfix, then rethinks the first-run experience around a provider-first, intent-driven flow with a drill-down main menu and a genuinely fast quick-start.
**Phase:** Closed
**Current Milestone:** —
**Progress:** 3 / 3 milestones
**Status:** complete
**Last Updated:** 2026-04-19 (archived during MVP manifest authoring; IUV-M03 substantively shipped via PR #446 — drill-down menu + provider-first flow + quick start; releases 0.0.27 → 0.0.29)
**Archived to:** `docs/archive/missions/install-ux-v2-20260405/`
**Parent Mission:** [install-ux-hardening-20260405](./archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md) (complete — `mosaic-v0.0.25`)

## Context

Real-run testing of `@mosaicstack/mosaic@0.0.25` uncovered:

1. **Critical:** admin bootstrap fails with HTTP 400 `property email should not exist` — `bootstrap.controller.ts` uses `import type { BootstrapSetupDto }`, erasing the class at runtime. Nest's `@Body()` falls back to plain `Object` metatype, and ValidationPipe with `forbidNonWhitelisted` rejects every property. One-character fix (drop the `type` keyword), but it blocks the happy path of the release that just shipped.
2. The wizard reports `✔ Wizard complete` and `✔ Done` _after_ the bootstrap 400 — failure only propagates in headless mode (`wizard.ts:147`).
3. The gateway port prompt does not prefill `14242` in the input buffer.
4. `"What is Mosaic?"` intro copy does not mention Pi SDK (the actual agent runtime behind Claude/Codex/OpenCode).
5. CORS origin prompt is confusing — the user should be able to supply an FQDN/hostname and have the system derive the CORS value.
6. Skill / additional feature install section is unusable in practice.
7. Quick-start asks far too many questions to be meaningfully "quick".
8. No drill-down main menu — everything is a linear interrogation.
9. Provider setup happens late and without intelligence. An OpenClaw-style provider-first flow would let the user describe what they want in natural language, have the agent expound on it, and have the agent choose its own name based on that intent.

## Success Criteria

- [x] AC-1: Admin bootstrap completes successfully end-to-end on a fresh install (DTO value import, no forbidNonWhitelisted regression); covered by an integration or e2e test that exercises the real DTO binding. _(PR #440)_
- [x] AC-2: Wizard fails loudly (non-zero exit, clear error) when the bootstrap stage returns `completed: false`, in both interactive and headless modes. No more silent `✔ Wizard complete` after a 400. _(PR #440)_
- [x] AC-3: Gateway port prompt prefills `14242` in the input field (user can press Enter to accept). _(PR #440)_
- [x] AC-4: `"What is Mosaic?"` intro copy mentions Pi SDK as the underlying agent runtime. _(PR #440)_
- [x] AC-5: Release `mosaic-v0.0.26` tagged and published to the Gitea npm registry, unblocking the 0.0.25 happy path. _(tag: mosaic-v0.0.26, registry: 0.0.26 live)_
- [ ] AC-6: CORS origin prompt replaced with FQDN/hostname input; CORS string is derived from that.
- [ ] AC-7: Skill / additional feature install section is reworked until it is actually usable end-to-end (worker defines the concrete failure modes during diagnosis).
- [ ] AC-8: First-run flow has a drill-down main menu with at least `Plugins` (Recommended / Custom), `Providers`, and the other top-level configuration groups. Linear interrogation is gone.
- [ ] AC-9: `Quick Start` path completes with a minimal, curated set of questions (target: under 90 seconds for a returning user; define the exact baseline during design).
- [ ] AC-10: Provider setup happens first, driven by a natural-language intake prompt. The agent expounds on the user's intent and chooses its own name based on that intent (OpenClaw-style). Naming is confirmable / overridable.
- [ ] AC-11: All milestones ship as merged PRs with green CI and closed issues.

## Milestones

| #   | ID      | Name                                                         | Status   | Branch                 | Issue | Started    | Completed  |
| --- | ------- | ------------------------------------------------------------ | -------- | ---------------------- | ----- | ---------- | ---------- |
| 1   | IUV-M01 | Hotfix: bootstrap DTO + wizard failure + port prefill + copy | complete | fix/bootstrap-hotfix   | #436  | 2026-04-05 | 2026-04-05 |
| 2   | IUV-M02 | UX polish: CORS/FQDN, skill installer rework                 | complete | feat/install-ux-polish | #437  | 2026-04-05 | 2026-04-05 |
| 3   | IUV-M03 | Provider-first intelligent flow + drill-down main menu       | complete | feat/install-ux-intent | #438  | 2026-04-05 | 2026-04-19 |

## Subagent Delegation Plan

| Milestone | Recommended Tier | Rationale                                                             |
| --------- | ---------------- | --------------------------------------------------------------------- |
| IUV-M01   | sonnet           | Tight bug cluster with known fix sites + small release cycle          |
| IUV-M02   | sonnet           | UX rework, moderate surface, diagnostic-heavy for the skill installer |
| IUV-M03   | opus             | Architectural redesign of first-run flow, state machine + LLM intake  |

## Risks

- **Hotfix regression surface** — the `import type` → `import` fix on the DTO class is one character but needs an integration test that binds the real DTO, not just a controller unit test, to prevent the same class-erasure regression from sneaking back in.
- **LLM-driven intake latency / offline** — M03's provider-first intent flow assumes an available LLM call to expound on user input and choose a name. Offline installs need a deterministic fallback.
- **Menu vs. linear back-compat** — M03 changes the top-level flow shape; existing `tools/install.sh --yes` + env-var headless path must continue to work.
- **Scope creep in M03** — "redesign the wizard" can absorb arbitrary work. Keep it bounded with explicit non-goals.

## Out of Scope

- Migrating the wizard to a GUI / web UI (still terminal-first)
- Replacing the Gitea registry or the Woodpecker publish pipeline
- Multi-tenant / multi-user onboarding (still single-admin bootstrap)
- Reworking `mosaic uninstall` (M01 of the parent mission — stable)
