stack/docs/MISSION-MANIFEST.md

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: Planning Current Milestone: IUV-M01 Progress: 0 / 3 milestones Status: active Last Updated: 2026-04-05 Parent Mission: install-ux-hardening-20260405 (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

• 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.
• 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.
• AC-3: Gateway port prompt prefills 14242 in the input field (user can press Enter to accept).
• AC-4: "What is Mosaic?" intro copy mentions Pi SDK as the underlying agent runtime.
• AC-5: Release mosaic-v0.0.26 tagged and published to the Gitea npm registry, unblocking the 0.0.25 happy path.
• 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	in-progress	fix/bootstrap-hotfix	#436	2026-04-05	—
2	IUV-M02	UX polish: CORS/FQDN, skill installer rework	not-started	feat/install-ux-polish	#437	—	—
3	IUV-M03	Provider-first intelligent flow + drill-down main menu	not-started	feat/install-ux-intent	#438	—	—

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)