feat(mosaic): drill-down main menu + provider-first flow + quick start (#446 )

docs: orchestrator close-out IUV-M02 (#445 )
feat(mosaic): IUV-M02 — CORS/FQDN UX polish + skill installer rework (#444 )
2026-04-06 00:15:23 +00:00 · 2026-04-05 23:50:55 +00:00 · 2026-04-05 23:44:07 +00:00 · 2026-04-05 22:40:08 +00:00 · 2026-04-05 22:31:37 +00:00 · 2026-04-05 22:01:57 +00:00
23 changed files with 1758 additions and 92 deletions
--- a/apps/gateway/tsconfig.json
+++ b/apps/gateway/tsconfig.json
@@ -8,6 +8,6 @@
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  },
-  "include": ["src/**/*", "vitest.config.ts"],
+  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
 }
--- a/docs/MISSION-MANIFEST.md
+++ b/docs/MISSION-MANIFEST.md
@@ -7,11 +7,11 @@
 **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
+**Phase:** Execution
-**Current Milestone:** IUV-M01
+**Current Milestone:** IUV-M03
-**Progress:** 0 / 3 milestones
+**Progress:** 2 / 3 milestones
 **Status:** active
-**Last Updated:** 2026-04-05
+**Last Updated:** 2026-04-05 (IUV-M02 complete — CORS/FQDN + skill installer rework)
 **Parent Mission:** [install-ux-hardening-20260405](./archive/missions/install-ux-hardening-20260405/MISSION-MANIFEST.md) (complete — `mosaic-v0.0.25`)
 ## Context
@@ -30,11 +30,11 @@ Real-run testing of `@mosaicstack/mosaic@0.0.25` uncovered:
 ## 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.
+- [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)_
- [ ] 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.
+- [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)_
- [ ] AC-3: Gateway port prompt prefills `14242` in the input field (user can press Enter to accept).
+- [x] AC-3: Gateway port prompt prefills `14242` in the input field (user can press Enter to accept). _(PR #440)_
- [ ] AC-4: `"What is Mosaic?"` intro copy mentions Pi SDK as the underlying agent runtime.
+- [x] AC-4: `"What is Mosaic?"` intro copy mentions Pi SDK as the underlying agent runtime. _(PR #440)_
- [ ] AC-5: Release `mosaic-v0.0.26` tagged and published to the Gitea npm registry, unblocking the 0.0.25 happy path.
+- [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.
@@ -44,11 +44,11 @@ Real-run testing of `@mosaicstack/mosaic@0.0.25` uncovered:
 ## Milestones
-| #   | ID      | Name                                                         | Status      | Branch                 | Issue | Started    | Completed |
+| #   | 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 | —         |
+| 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                 | not-started | feat/install-ux-polish | #437  | —          | —         |
+| 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       | not-started | feat/install-ux-intent | #438  | —          | —         |
+| 3   | IUV-M03 | Provider-first intelligent flow + drill-down main menu       | not-started | feat/install-ux-intent | #438  | —          | —          |
 ## Subagent Delegation Plan
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -9,29 +9,29 @@
 ## Milestone 1 — Hotfix: bootstrap DTO + wizard failure + port prefill + copy (IUV-M01)
-| id        | status      | description                                                                                                                                                                                   | issue | agent  | branch               | depends_on | estimate | notes                                                                                          |
+| id        | status | description                                                                                                                                                                                   | issue | agent  | branch               | depends_on | estimate | notes                                                                                   |
-| --------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | -------------------- | ---------- | -------- | ---------------------------------------------------------------------------------------------- |
+| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | -------------------- | ---------- | -------- | --------------------------------------------------------------------------------------- |
-| IUV-01-01 | not-started | Fix `apps/gateway/src/admin/bootstrap.controller.ts:16` — switch `import type { BootstrapSetupDto }` to a value import so Nest's `@Body()` binds the real class                               | #436  | sonnet | fix/bootstrap-hotfix | —          | 3K       | one-character fix; repro is real-run `mosaic wizard` against `0.0.25`                          |
+| IUV-01-01 | done   | Fix `apps/gateway/src/admin/bootstrap.controller.ts:16` — switch `import type { BootstrapSetupDto }` to a value import so Nest's `@Body()` binds the real class                               | #436  | sonnet | fix/bootstrap-hotfix | —          | 3K       | PR #440 merged `0ae932ab`                                                               |
-| IUV-01-02 | not-started | Add integration / e2e test that POSTs `/api/bootstrap/setup` with `{name,email,password}` against a real Nest app instance and asserts 201 — NOT a mocked controller unit test                | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-01  | 10K      | must fail before the fix and pass after; guards against the class-erasure regression recurring |
+| IUV-01-02 | done   | Add integration / e2e test that POSTs `/api/bootstrap/setup` with `{name,email,password}` against a real Nest app instance and asserts 201 — NOT a mocked controller unit test                | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-01  | 10K      | `apps/gateway/src/admin/bootstrap.e2e.spec.ts` — 4 tests; unplugin-swc added for vitest |
-| IUV-01-03 | not-started | `packages/mosaic/src/wizard.ts:147` — propagate `!bootstrapResult.completed` as a wizard failure in **interactive** mode too (not only headless); non-zero exit + no `✔ Wizard complete` line | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-02  | 5K       |                                                                                                |
+| IUV-01-03 | done   | `packages/mosaic/src/wizard.ts:147` — propagate `!bootstrapResult.completed` as a wizard failure in **interactive** mode too (not only headless); non-zero exit + no `✔ Wizard complete` line | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-02  | 5K       | removed `&& headlessRun` guard                                                          |
-| IUV-01-04 | not-started | Gateway port prompt prefills `14242` in the input buffer — investigate why `promptPort`'s `defaultValue` isn't reaching the user-visible input                                                | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-03  | 5K       | likely WizardPrompter adapter or @clack/prompts `initialValue` vs `defaultValue` mismatch      |
+| IUV-01-04 | done   | Gateway port prompt prefills `14242` in the input buffer — investigate why `promptPort`'s `defaultValue` isn't reaching the user-visible input                                                | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-03  | 5K       | added `initialValue` through prompter interface → clack                                 |
-| IUV-01-05 | not-started | `"What is Mosaic?"` intro copy updated to mention Pi SDK as the underlying agent runtime (alongside Claude Code / Codex / OpenCode)                                                           | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-04  | 2K       |                                                                                                |
+| IUV-01-05 | done   | `"What is Mosaic?"` intro copy updated to mention Pi SDK as the underlying agent runtime (alongside Claude Code / Codex / OpenCode)                                                           | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-04  | 2K       | `packages/mosaic/src/stages/welcome.ts`                                                 |
-| IUV-01-06 | not-started | Tests + code review + PR merge + tag `mosaic-v0.0.26` + Gitea release + npm registry republish                                                                                                | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-05  | 10K      | bump `packages/mosaic/package.json` to 0.0.25 → 0.0.26                                         |
+| IUV-01-06 | done   | Tests + code review + PR merge + tag `mosaic-v0.0.26` + Gitea release + npm registry republish                                                                                                | #436  | sonnet | fix/bootstrap-hotfix | IUV-01-05  | 10K      | PRs #440/#441/#442 merged; tag `mosaic-v0.0.26`; registry latest=0.0.26 ✓               |
 ## Milestone 2 — UX polish: CORS/FQDN, skill installer rework (IUV-M02)
-| id        | status      | description                                                                                                                          | issue | agent  | branch                 | depends_on | estimate | notes                       |
+| id        | status | description                                                                                                                          | issue | agent  | branch                 | depends_on | estimate | notes                                                                  |
-| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------- | ---------- | -------- | --------------------------- |
+| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----- | ------ | ---------------------- | ---------- | -------- | ---------------------------------------------------------------------- |
-| IUV-02-01 | not-started | Replace CORS origin prompt with FQDN / hostname input; derive the CORS value internally; default to `localhost` with clear help text | #437  | sonnet | feat/install-ux-polish | IUV-01-06  | 10K      |                             |
+| IUV-02-01 | done   | Replace CORS origin prompt with FQDN / hostname input; derive the CORS value internally; default to `localhost` with clear help text | #437  | sonnet | feat/install-ux-polish | —          | 10K      | `deriveCorsOrigin()` pure fn; MOSAIC_HOSTNAME headless var; PR #444    |
-| IUV-02-02 | not-started | Diagnose and document the concrete failure modes of the current skill / additional feature install section end-to-end                | #437  | sonnet | feat/install-ux-polish | IUV-02-01  | 8K       | needs real-run reproduction |
+| IUV-02-02 | done   | Diagnose and document the concrete failure modes of the current skill / additional feature install section end-to-end                | #437  | sonnet | feat/install-ux-polish | IUV-02-01  | 8K       | selection→install gap, silent catch{}, no whitelist concept            |
-| IUV-02-03 | not-started | Rework the skill installer so it is usable end-to-end (selection, install, verify, failure reporting)                                | #437  | sonnet | feat/install-ux-polish | IUV-02-02  | 20K      |                             |
+| IUV-02-03 | done   | Rework the skill installer so it is usable end-to-end (selection, install, verify, failure reporting)                                | #437  | sonnet | feat/install-ux-polish | IUV-02-02  | 20K      | MOSAIC_INSTALL_SKILLS env var whitelist; SyncSkillsResult typed return |
-| IUV-02-04 | not-started | Tests + code review + PR merge                                                                                                       | #437  | sonnet | feat/install-ux-polish | IUV-02-03  | 10K      |                             |
+| IUV-02-04 | done   | Tests + code review + PR merge                                                                                                       | #437  | sonnet | feat/install-ux-polish | IUV-02-03  | 10K      | 18 new tests (13 CORS + 5 skills); PR #444 merged `172bacb3`           |
 ## Milestone 3 — Provider-first intelligent flow + drill-down main menu (IUV-M03)
 | id        | status      | description                                                                                                                                                  | issue | agent | branch                 | depends_on | estimate | notes                                                         |
 | --------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | ----- | ---------------------- | ---------- | -------- | ------------------------------------------------------------- |
-| IUV-03-01 | not-started | Design doc: new first-run state machine — main menu (Plugins / Providers / …), Quick Start vs Custom paths, provider-first flow, intent intake + naming loop | #438  | opus  | feat/install-ux-intent | IUV-02-04  | 15K      | scratchpad + explicit non-goals                               |
+| IUV-03-01 | not-started | Design doc: new first-run state machine — main menu (Plugins / Providers / …), Quick Start vs Custom paths, provider-first flow, intent intake + naming loop | #438  | opus  | feat/install-ux-intent | —          | 15K      | scratchpad + explicit non-goals                               |
 | IUV-03-02 | not-started | Implement drill-down main menu (Plugins: Recommended / Custom, Providers, …) as the top-level entry point of `mosaic wizard`                                 | #438  | opus  | feat/install-ux-intent | IUV-03-01  | 25K      |                                                               |
 | IUV-03-03 | not-started | Quick Start path: curated minimum question set — define the exact baseline, delete everything else from the fast path                                        | #438  | opus  | feat/install-ux-intent | IUV-03-02  | 15K      |                                                               |
 | IUV-03-04 | not-started | Provider-first natural-language intake: user describes intent → agent expounds → agent proposes a name (confirmable / overridable) — OpenClaw-style          | #438  | opus  | feat/install-ux-intent | IUV-03-03  | 25K      | offline fallback required (deterministic default name + path) |
--- a/docs/scratchpads/install-ux-v2-20260405.md
+++ b/docs/scratchpads/install-ux-v2-20260405.md
@@ -107,3 +107,67 @@ Sequencing: strict. M01 ships first as a hotfix release (mosaic-v0.0.26). M02 is
 1. Create Gitea issues for M01, M02, M03
 2. Open the mission-scaffold docs PR (same pattern as parent mission's PR #430)
 3. After merge, delegate IUV-M01 to a sonnet subagent in an isolated worktree with the concrete fix-site pointers above
 ## Session 2 — 2026-04-05 (IUV-M01 delivery + close-out)
 ### Outcome
 IUV-M01 shipped. `mosaic-v0.0.26` released and registry latest confirmed `0.0.26`.
 ### PRs merged
 | PR   | Title                                                                    | Merge    |
 | ---- | ------------------------------------------------------------------------ | -------- |
 | #440 | fix: bootstrap hotfix — DTO erasure, wizard failure, port prefill, copy  | 0ae932ab |
 | #441 | fix: add vitest.config.ts to eslint allowDefaultProject (#440 build fix) | c08aa6fa |
 | #442 | docs: mark IUV-M01 complete — mosaic-v0.0.26 released                    | 78388437 |
 ### Bugs fixed (all 4 in worker's PR #440)
 1. **DTO class erasure** — `apps/gateway/src/admin/bootstrap.controller.ts:16` — dropped `type` from `import { BootstrapSetupDto }`. Guarded by new e2e test `bootstrap.e2e.spec.ts` (4 cases) that binds through a real Nest app with `ValidationPipe { whitelist, forbidNonWhitelisted }`. Test suite needed `unplugin-swc` in `apps/gateway/vitest.config.ts` to emit `decoratorMetadata` (tsx/esbuild can't).
 2. **Wizard silent failure** — `packages/mosaic/src/wizard.ts` — removed the `&& headlessRun` guard so `!bootstrapResult.completed` now aborts in both modes.
 3. **Port prefill** — root cause was clack's `defaultValue` vs `initialValue` semantics (`defaultValue` only fills on empty submit, `initialValue` prefills the buffer). Added an `initialValue` field to `WizardPrompter.text()` interface, threaded through clack and headless prompters, switched `gateway-config.ts` port/url prompts to use it.
 4. **Pi SDK copy** — `packages/mosaic/src/stages/welcome.ts` — intro copy now lists Pi SDK.
 ### Mid-delivery hiccup — tsconfig/eslint cross-contamination
 Worker's initial approach added `vitest.config.ts` to `apps/gateway/tsconfig.json`'s `include` to appease the eslint parser. That broke `pnpm --filter @mosaicstack/gateway build` with TS6059 (`vitest.config.ts` outside `rootDir: "src"`). The publish pipeline on the `#440` merge commit failed.
 **Correct fix** (worker's PR #441): leave `tsconfig.json` clean (`include: ["src/**/*"]`) and instead add the file to `allowDefaultProject` in the root `eslint.config.mjs`. This keeps the tsc program strict while letting eslint resolve a parser project for the standalone config file.
 **Pattern to remember**: when adding root-level `.ts` config files (vitest, build scripts) to a package with `rootDir: "src"`, the eslint parser project conflict is solved with `allowDefaultProject`, NEVER by widening tsconfig include. I had independently arrived at the same fix on a branch before the worker shipped #441 — deleted the duplicate.
 ### Residual follow-ups carried forward
 1. Headless prompter fallback order: worker set `initialValue > defaultValue` in the headless path. Correct semantic, but any future headless test that explicitly depends on `defaultValue` precedence will need review.
 2. Vitest + SWC decorator metadata pattern is now the blessed approach for NestJS e2e tests in this monorepo. Any other package that adds NestJS e2e tests should mirror `apps/gateway/vitest.config.ts`.
 ### Next action
 - Close out orchestrator doc sync (this commit): mark M01 subtasks done in `TASKS.md`, update manifest phase to Execution, commit scratchpad session 2, PR to main.
 - After merge, delegate IUV-M02 (sonnet, isolated worktree). Dependencies: IUV-02-01 (CORS→FQDN) starts unblocked since M01 is released; first real task for the M02 worker is diagnosing the skill installer failure modes (IUV-02-02) against the fresh 0.0.26 install.
 ## Session 3 — 2026-04-05 (IUV-M02 delivery + close-out)
 ### Outcome
 IUV-M02 shipped. PR #444 merged (`172bacb3`), issue #437 closed. 18 new tests (13 CORS derivation, 5 skill sync).
 ### Changes
 **CORS → FQDN (IUV-02-01):**
 - `packages/mosaic/src/stages/gateway-config.ts` — replaced raw "CORS origin" text prompt with "Web UI hostname" (default: `localhost`). Added HTTPS follow-up for remote hosts. Pure `deriveCorsOrigin(hostname, port, useHttps?)` function exported for testability.
 - Headless: `MOSAIC_HOSTNAME` env var as friendly alternative; `MOSAIC_CORS_ORIGIN` still works as full override.
 - `packages/mosaic/src/types.ts` — added `hostname?: string` to `GatewayState`.
 **Skill installer rework (IUV-02-02 + IUV-02-03):**
 - Root cause confirmed: `syncSkills()` in `finalize.ts` ignored `state.selectedSkills` entirely. The multiselect UI was a no-op.
 - `packages/mosaic/src/stages/finalize.ts` — `syncSkills()` rewritten to accept `selectedSkills[]`, returns typed `SyncSkillsResult`, passes `MOSAIC_INSTALL_SKILLS` (colon-separated) as env var to the bash script.
 - `packages/mosaic/framework/tools/_scripts/mosaic-sync-skills` — added bash associative array whitelist filter keyed on `MOSAIC_INSTALL_SKILLS`. When set, only whitelisted skills are linked. Empty/unset = all skills (legacy behavior preserved for `mosaic sync` outside wizard).
 - Failure surfaces: silent `catch {}` replaced with typed error reporting through `p.warn()`.
 ### Next action
 - Delegate IUV-M03 (opus, isolated worktree) — the architectural milestone: provider-first intelligent flow, drill-down main menu, Quick Start fast path, agent self-naming. This is the biggest piece of the mission.
--- a/docs/scratchpads/iuv-m03-design.md
+++ b/docs/scratchpads/iuv-m03-design.md
@@ -0,0 +1,227 @@
 # IUV-M03 Design: Provider-first intelligent flow + drill-down main menu
 **Issue:** #438
 **Branch:** `feat/install-ux-intent`
 **Date:** 2026-04-05
 ## 1. New first-run state machine
 The linear 12-stage interrogation is replaced with a menu-driven architecture.
 ### Flow overview
 ```
 Welcome banner
  |
  v
 Detect existing install (auto)
  |
  v
 Main Menu (loop)
  |-- Quick Start        -> provider key + admin creds -> finalize
  |-- Providers          -> LLM API key config
  |-- Agent Identity     -> intent intake + naming (deterministic)
  |-- Skills             -> recommended / custom selection
  |-- Gateway            -> port, storage tier, hostname, CORS
  |-- Advanced           -> SOUL.md, USER.md, TOOLS.md, runtimes, hooks
  |-- Finish & Apply     -> finalize + gateway bootstrap
  v
 Done
 ```
 ### Menu navigation
 - Main menu is a `select` prompt. Each option drills into a sub-flow.
 - Completing a section returns to the main menu.
 - Menu items show completion state: `[done]` hint after configuration.
 - `Finish & Apply` is always last and requires at minimum a provider key (or explicit skip).
 - The menu tracks configured sections in `WizardState.completedSections`.
 ### Headless bypass
 When `MOSAIC_ASSUME_YES=1` or `!process.stdin.isTTY`, the entire menu is skipped.
 The wizard runs: defaults + env var overrides -> finalize -> gateway config -> bootstrap.
 This preserves full backward compatibility with `tools/install.sh --yes`.
 ## 2. Quick Start path
 Target: 3-5 questions max. Under 90 seconds for a returning user.
 ### Questions asked
 1. **Provider API key** (Anthropic/OpenAI) - `text` prompt with paste support
 2. **Admin email** - `text` prompt
 3. **Admin password** - masked + confirmed
 ### Questions skipped (with defaults)
 | Setting                      | Default                         | Rationale              |
 | ---------------------------- | ------------------------------- | ---------------------- |
 | Agent name                   | "Mosaic"                        | Generic but branded    |
 | Port                         | 14242                           | Standard default       |
 | Storage tier                 | local                           | No external deps       |
 | Hostname                     | localhost                       | Dev-first              |
 | CORS origin                  | http://localhost:3000           | Standard web UI port   |
 | Skills                       | recommended set                 | Curated by maintainers |
 | Runtimes                     | auto-detected                   | No user input needed   |
 | Communication style          | direct                          | Most popular choice    |
 | SOUL.md / USER.md / TOOLS.md | template defaults               | Can customize later    |
 | Hooks                        | auto-install if Claude detected | Safe default           |
 ### Flow
 ```
 Quick Start selected
  -> "Paste your LLM API key (Anthropic recommended):"
  -> [auto-detect provider from key prefix: sk-ant-* = Anthropic, sk-* = OpenAI]
  -> Apply all defaults
  -> Run finalize (sync framework, write configs, link assets, sync skills)
  -> Run gateway config (headless-style with defaults + provided key)
  -> "Admin email:"
  -> "Admin password:" (masked + confirm)
  -> Run gateway bootstrap
  -> Done
 ```
 ## 3. Provider-first flow
 Provider configuration (currently buried in gateway-config stage as "ANTHROPIC_API_KEY")
 moves to a dedicated top-level menu item and is the first question in Quick Start.
 ### Provider detection
 The API key prefix determines the provider:
 - `sk-ant-api03-*` -> Anthropic (Claude)
 - `sk-*` -> OpenAI
 - Empty/skipped -> no provider (gateway starts without LLM access)
 ### Storage
 The provider key is stored in the gateway `.env` as `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`.
 For Quick Start, this replaces the old interactive prompt in `collectAndWriteConfig`.
 ### Menu section: "Providers"
 In the drill-down menu, "Providers" lets users:
 1. Enter/change their API key
 2. See which provider was detected
 3. Optionally configure a second provider
 For v0.0.27, we support Anthropic and OpenAI keys only. The key is stored
 in `WizardState` and written during finalize.
 ## 4. Intent intake + naming (deterministic fallback - Option B)
 ### Rationale
 At install time, the LLM provider may not be configured yet (chicken-and-egg).
 We use **Option B: deterministic advisor** for the install wizard.
 ### Flow (Agent Identity menu section)
 ```
 1. "What will this agent primarily help you with?"
   -> Select from presets:
      - General purpose assistant
      - Software development
      - DevOps & infrastructure
      - Research & analysis
      - Content & writing
      - Custom (free text description)
 2. System proposes a thematic name based on selection:
   - General purpose -> "Mosaic"
   - Software development -> "Forge"
   - DevOps & infrastructure -> "Sentinel"
   - Research & analysis -> "Atlas"
   - Content & writing -> "Muse"
   - Custom -> "Mosaic" (default)
 3. "Your agent will be named 'Forge'. Press Enter to accept or type a new name:"
   -> User confirms or overrides
 ```
 ### Storage
 - Agent name -> `WizardState.soul.agentName` -> written to SOUL.md
 - Intent category -> `WizardState.agentIntent` (new field) -> written to `~/.config/mosaic/agent.json`
 ### Post-install LLM-powered intake (future)
 A future `mosaic configure identity` command can use the configured LLM to:
 - Accept free-text intent description
 - Generate an expounded persona
 - Propose a contextual name
 This is explicitly out of scope for the install wizard.
 ## 5. Headless backward-compat
 ### Supported env vars (unchanged)
 | Variable                   | Used by                                        |
 | -------------------------- | ---------------------------------------------- |
 | `MOSAIC_ASSUME_YES=1`      | Skip all prompts, use defaults + env overrides |
 | `MOSAIC_ADMIN_NAME`        | Gateway bootstrap                              |
 | `MOSAIC_ADMIN_EMAIL`       | Gateway bootstrap                              |
 | `MOSAIC_ADMIN_PASSWORD`    | Gateway bootstrap                              |
 | `MOSAIC_GATEWAY_PORT`      | Gateway config                                 |
 | `MOSAIC_HOSTNAME`          | Gateway config (CORS derivation)               |
 | `MOSAIC_CORS_ORIGIN`       | Gateway config (full override)                 |
 | `MOSAIC_STORAGE_TIER`      | Gateway config (local/team)                    |
 | `MOSAIC_DATABASE_URL`      | Gateway config (team tier)                     |
 | `MOSAIC_VALKEY_URL`        | Gateway config (team tier)                     |
 | `MOSAIC_ANTHROPIC_API_KEY` | Provider config                                |
 ### New env vars
 | Variable              | Purpose                                   |
 | --------------------- | ----------------------------------------- |
 | `MOSAIC_AGENT_NAME`   | Override agent name in headless mode      |
 | `MOSAIC_AGENT_INTENT` | Override intent category in headless mode |
 ### `tools/install.sh --yes`
 The install script sets `MOSAIC_ASSUME_YES=1` and passes through env vars.
 No changes needed to the script itself. The new wizard detects headless mode
 at the top of `runWizard` and runs a linear path identical to the old flow.
 ## 6. Explicit non-goals
 - **No GUI** — this is a terminal wizard only
 - **No multi-user install** — single-user, single-machine
 - **No registry changes** — npm publish flow is unchanged
 - **No LLM calls during install** — deterministic fallback only
 - **No new dependencies** — uses existing @clack/prompts and picocolors
 - **No changes to gateway API** — only the wizard orchestration changes
 - **No changes to tools/install.sh** — headless compat maintained via env vars
 ## 7. Implementation plan
 ### Files to modify
 1. `packages/mosaic/src/types.ts` — add `MenuSection`, `AgentIntent`, `completedSections`, `agentIntent`, `providerKey`, `providerType` to WizardState
 2. `packages/mosaic/src/wizard.ts` — replace linear flow with menu loop
 3. `packages/mosaic/src/stages/mode-select.ts` — becomes the main menu
 4. `packages/mosaic/src/stages/provider-setup.ts` — new: provider key collection
 5. `packages/mosaic/src/stages/agent-intent.ts` — new: intent intake + naming
 6. `packages/mosaic/src/stages/menu-gateway.ts` — new: gateway sub-menu wrapper
 7. `packages/mosaic/src/stages/quick-start.ts` — new: quick start linear path
 8. `packages/mosaic/src/constants.ts` — add intent presets and name mappings
 9. `packages/mosaic/package.json` — version bump 0.0.26 -> 0.0.27
 ### Files to add (tests)
 1. `packages/mosaic/src/stages/wizard-menu.spec.ts` — menu navigation tests
 2. `packages/mosaic/src/stages/quick-start.spec.ts` — quick start path tests
 3. `packages/mosaic/src/stages/agent-intent.spec.ts` — intent + naming tests
 4. `packages/mosaic/src/stages/provider-setup.spec.ts` — provider detection tests
 ### Migration strategy
 The existing stage functions remain intact. The menu system wraps them —
 each menu item calls the appropriate stage function(s). The linear headless
 path calls them in the same order as before.
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -27,6 +27,7 @@ export default tseslint.config(
            'apps/web/e2e/*.ts',
            'apps/web/e2e/helpers/*.ts',
            'apps/web/playwright.config.ts',
            'apps/gateway/vitest.config.ts',
            'packages/mosaic/__tests__/*.ts',
          ],
        },
--- a/packages/mosaic/tests/integration/full-wizard.test.ts
+++ b/packages/mosaic/tests/integration/full-wizard.test.ts
@@ -17,6 +17,7 @@ import { runWizard } from '../../src/wizard.js';
 describe('Full Wizard (headless)', () => {
  let tmpDir: string;
  const repoRoot = join(import.meta.dirname, '..', '..');
  const originalEnv = { ...process.env };
  beforeEach(() => {
    tmpDir = mkdtempSync(join(tmpdir(), 'mosaic-wizard-test-'));
@@ -32,12 +33,16 @@ describe('Full Wizard (headless)', () => {
  afterEach(() => {
    rmSync(tmpDir, { recursive: true, force: true });
    process.env = { ...originalEnv };
  });
  it('quick start produces valid SOUL.md', async () => {
    // The headless path reads agent name from MOSAIC_AGENT_NAME env var
    // (via agentIntentStage) rather than prompting interactively.
    process.env['MOSAIC_AGENT_NAME'] = 'TestBot';
    const prompter = new HeadlessPrompter({
      'Installation mode': 'quick',
      'What name should agents use?': 'TestBot',
      'Communication style': 'direct',
      'Your name': 'Tester',
      'Your pronouns': 'They/Them',
@@ -62,9 +67,10 @@ describe('Full Wizard (headless)', () => {
  });
  it('quick start produces valid USER.md', async () => {
    process.env['MOSAIC_AGENT_NAME'] = 'TestBot';
    const prompter = new HeadlessPrompter({
      'Installation mode': 'quick',
      'What name should agents use?': 'TestBot',
      'Communication style': 'direct',
      'Your name': 'Tester',
      'Your pronouns': 'He/Him',
--- a/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills
+++ b/packages/mosaic/framework/tools/_scripts/mosaic-sync-skills
@@ -7,6 +7,11 @@ SKILLS_REPO_DIR="${MOSAIC_SKILLS_REPO_DIR:-$MOSAIC_HOME/sources/agent-skills}"
 MOSAIC_SKILLS_DIR="$MOSAIC_HOME/skills"
 MOSAIC_LOCAL_SKILLS_DIR="$MOSAIC_HOME/skills-local"
 # Colon-separated list of skill names to install.  When set, only these skills
 # are linked into runtime skill directories.  Empty/unset = link all skills
 # (the legacy "mosaic sync" full-catalog behavior).
 MOSAIC_INSTALL_SKILLS="${MOSAIC_INSTALL_SKILLS:-}"
 fetch=1
 link_only=0
@@ -25,6 +30,7 @@ Env:
  MOSAIC_HOME               Default: ~/.config/mosaic
  MOSAIC_SKILLS_REPO_URL    Default: https://git.mosaicstack.dev/mosaic/agent-skills.git
  MOSAIC_SKILLS_REPO_DIR    Default: ~/.config/mosaic/sources/agent-skills
  MOSAIC_INSTALL_SKILLS     Colon-separated list of skills to link (default: all)
 USAGE
 }
@@ -156,6 +162,27 @@ link_targets=(
 canonical_real="$(readlink -f "$MOSAIC_SKILLS_DIR")"
 # Build an associative array from the colon-separated whitelist for O(1) lookup.
 # When MOSAIC_INSTALL_SKILLS is empty, all skills are allowed.
 declare -A _skill_whitelist=()
 _whitelist_active=0
 if [[ -n "$MOSAIC_INSTALL_SKILLS" ]]; then
  _whitelist_active=1
  IFS=':' read -ra _wl_items <<< "$MOSAIC_INSTALL_SKILLS"
  for _item in "${_wl_items[@]}"; do
    [[ -n "$_item" ]] && _skill_whitelist["$_item"]=1
  done
 fi
 is_skill_selected() {
  local name="$1"
  if [[ $_whitelist_active -eq 0 ]]; then
    return 0
  fi
  [[ -n "${_skill_whitelist[$name]:-}" ]] && return 0
  return 1
 }
 link_skill_into_target() {
  local skill_path="$1"
  local target_dir="$2"
@@ -168,6 +195,11 @@ link_skill_into_target() {
    return
  fi
  # Respect the install whitelist (set during first-run wizard).
  if ! is_skill_selected "$name"; then
    return
  fi
  link_path="$target_dir/$name"
  if [[ -L "$link_path" ]]; then
--- a/packages/mosaic/package.json
+++ b/packages/mosaic/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@mosaicstack/mosaic",
-  "version": "0.0.26",
+  "version": "0.0.27",
  "repository": {
    "type": "git",
    "url": "https://git.mosaicstack.dev/mosaicstack/mosaic-stack.git",
--- a/packages/mosaic/src/constants.ts
+++ b/packages/mosaic/src/constants.ts
@@ -26,6 +26,53 @@ export const DEFAULTS = {
 | (add your git providers here) | | | |`,
 };
 /** Preset intent categories with display labels and suggested agent names. */
 export const INTENT_PRESETS: Record<
  string,
  { label: string; hint: string; suggestedName: string }
 > = {
  general: {
    label: 'General purpose assistant',
    hint: 'Versatile helper for any task',
    suggestedName: 'Mosaic',
  },
  'software-dev': {
    label: 'Software development',
    hint: 'Coding, debugging, architecture',
    suggestedName: 'Forge',
  },
  devops: {
    label: 'DevOps & infrastructure',
    hint: 'CI/CD, containers, monitoring',
    suggestedName: 'Sentinel',
  },
  research: {
    label: 'Research & analysis',
    hint: 'Data analysis, literature review',
    suggestedName: 'Atlas',
  },
  content: {
    label: 'Content & writing',
    hint: 'Documentation, copywriting, editing',
    suggestedName: 'Muse',
  },
  custom: {
    label: 'Custom',
    hint: 'Describe your own use case',
    suggestedName: 'Mosaic',
  },
 };
 /**
 * Detect LLM provider type from an API key prefix.
 */
 export function detectProviderType(key: string): 'anthropic' | 'openai' | 'none' {
  if (!key) return 'none';
  if (key.startsWith('sk-ant-')) return 'anthropic';
  if (key.startsWith('sk-')) return 'openai';
  return 'none';
 }
 export const RECOMMENDED_SKILLS = new Set([
  'brainstorming',
  'code-review-excellence',
--- a/packages/mosaic/src/stages/agent-intent.spec.ts
+++ b/packages/mosaic/src/stages/agent-intent.spec.ts
@@ -0,0 +1,129 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import type { WizardState } from '../types.js';
 import { agentIntentStage } from './agent-intent.js';
 function buildPrompter(overrides: Partial<Record<string, unknown>> = {}) {
  return {
    intro: vi.fn(),
    outro: vi.fn(),
    note: vi.fn(),
    log: vi.fn(),
    warn: vi.fn(),
    text: vi.fn().mockResolvedValue('Mosaic'),
    confirm: vi.fn().mockResolvedValue(false),
    select: vi.fn().mockResolvedValue('general'),
    multiselect: vi.fn(),
    groupMultiselect: vi.fn(),
    spinner: vi.fn().mockReturnValue({ update: vi.fn(), stop: vi.fn() }),
    separator: vi.fn(),
    ...overrides,
  };
 }
 function makeState(): WizardState {
  return {
    mosaicHome: '/tmp/mosaic',
    sourceDir: '/tmp/mosaic',
    mode: 'quick',
    installAction: 'fresh',
    soul: {},
    user: {},
    tools: {},
    runtimes: { detected: [], mcpConfigured: false },
    selectedSkills: [],
  };
 }
 describe('agentIntentStage', () => {
  const originalEnv = { ...process.env };
  afterEach(() => {
    process.env = { ...originalEnv };
  });
  it('uses default intent and name in headless mode', async () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    delete process.env['MOSAIC_AGENT_INTENT'];
    delete process.env['MOSAIC_AGENT_NAME'];
    const state = makeState();
    const p = buildPrompter();
    await agentIntentStage(p, state);
    expect(state.agentIntent).toBe('general');
    expect(state.soul.agentName).toBe('Mosaic');
  });
  it('reads intent from MOSAIC_AGENT_INTENT env var', async () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    process.env['MOSAIC_AGENT_INTENT'] = 'software-dev';
    delete process.env['MOSAIC_AGENT_NAME'];
    const state = makeState();
    const p = buildPrompter();
    await agentIntentStage(p, state);
    expect(state.agentIntent).toBe('software-dev');
    expect(state.soul.agentName).toBe('Forge');
  });
  it('honors MOSAIC_AGENT_NAME env var override', async () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    process.env['MOSAIC_AGENT_INTENT'] = 'devops';
    process.env['MOSAIC_AGENT_NAME'] = 'MyBot';
    const state = makeState();
    const p = buildPrompter();
    await agentIntentStage(p, state);
    expect(state.agentIntent).toBe('devops');
    expect(state.soul.agentName).toBe('MyBot');
  });
  it('falls back to general for unknown intent values', async () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    process.env['MOSAIC_AGENT_INTENT'] = 'nonexistent';
    delete process.env['MOSAIC_AGENT_NAME'];
    const state = makeState();
    const p = buildPrompter();
    await agentIntentStage(p, state);
    expect(state.agentIntent).toBe('general');
    expect(state.soul.agentName).toBe('Mosaic');
  });
  it('prompts for intent and name in interactive mode', async () => {
    delete process.env['MOSAIC_ASSUME_YES'];
    const origIsTTY = process.stdin.isTTY;
    Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
    const state = makeState();
    const p = buildPrompter({
      select: vi.fn().mockResolvedValue('research'),
      text: vi.fn().mockResolvedValue('Atlas'),
    });
    await agentIntentStage(p, state);
    expect(state.agentIntent).toBe('research');
    expect(state.soul.agentName).toBe('Atlas');
    expect(p.select).toHaveBeenCalled();
    expect(p.text).toHaveBeenCalled();
    Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
  });
  it('maps content intent to Muse suggested name', async () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    process.env['MOSAIC_AGENT_INTENT'] = 'content';
    delete process.env['MOSAIC_AGENT_NAME'];
    const state = makeState();
    const p = buildPrompter();
    await agentIntentStage(p, state);
    expect(state.agentIntent).toBe('content');
    expect(state.soul.agentName).toBe('Muse');
  });
 });
--- a/packages/mosaic/src/stages/agent-intent.ts
+++ b/packages/mosaic/src/stages/agent-intent.ts
@@ -0,0 +1,64 @@
 import type { WizardPrompter } from '../prompter/interface.js';
 import type { AgentIntent, WizardState } from '../types.js';
 import { INTENT_PRESETS } from '../constants.js';
 /**
 * Agent intent + naming stage — deterministic (no LLM required).
 *
 * The user picks an intent category from presets, the system proposes a
 * thematic name, and the user confirms or overrides it.
 *
 * In headless mode, reads from `MOSAIC_AGENT_INTENT` and `MOSAIC_AGENT_NAME`.
 */
 export async function agentIntentStage(p: WizardPrompter, state: WizardState): Promise<void> {
  const isHeadless = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
  if (isHeadless) {
    const intentEnv = process.env['MOSAIC_AGENT_INTENT'] ?? 'general';
    const nameEnv = process.env['MOSAIC_AGENT_NAME'];
    const preset = INTENT_PRESETS[intentEnv] ?? INTENT_PRESETS['general']!;
    state.agentIntent ??= (intentEnv in INTENT_PRESETS ? intentEnv : 'general') as AgentIntent;
    // Respect existing agentName (e.g. from CLI overrides) — only set from
    // env/preset if not already populated.
    state.soul.agentName ??= nameEnv ?? preset.suggestedName;
    return;
  }
  p.separator();
  p.note(
    'Tell us what this agent will primarily help you with.\n' +
      "We'll suggest a name based on your choice — you can always change it.",
    'Agent Identity',
  );
  const intentOptions = Object.entries(INTENT_PRESETS).map(([value, info]) => ({
    value: value as AgentIntent,
    label: info.label,
    hint: info.hint,
  }));
  const intent = await p.select<AgentIntent>({
    message: 'What will this agent primarily help you with?',
    options: intentOptions,
    initialValue: 'general' as AgentIntent,
  });
  state.agentIntent = intent;
  const preset = INTENT_PRESETS[intent];
  const suggestedName = preset?.suggestedName ?? 'Mosaic';
  const name = await p.text({
    message: `Your agent will be named "${suggestedName}". Press Enter to accept or type a new name`,
    initialValue: suggestedName,
    defaultValue: suggestedName,
    validate: (v) => {
      if (v.length === 0) return 'Name cannot be empty';
      if (v.length > 50) return 'Name must be under 50 characters';
      return undefined;
    },
  });
  state.soul.agentName = name;
  p.log(`Agent name set to: ${name}`);
 }
--- a/packages/mosaic/src/stages/finalize-skills.spec.ts
+++ b/packages/mosaic/src/stages/finalize-skills.spec.ts
@@ -0,0 +1,186 @@
 /**
 * Tests for the skill installer rework (IUV-02-03).
 *
 * We mock `node:child_process` to verify that:
 *   1. syncSkills passes MOSAIC_INSTALL_SKILLS with the exact selected subset
 *   2. When the script exits non-zero, the failure is surfaced to the user
 *   3. When the script is missing, a clear error is shown (not a silent no-op)
 *   4. An empty selection is a no-op (script never called)
 */
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import type { WizardState } from '../types.js';
 import type { ConfigService } from '../config/config-service.js';
 // ── spawnSync mock ─────────────────────────────────────────────────────────────
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const spawnSyncMock = vi.fn<any>();
 vi.mock('node:child_process', () => ({
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  spawnSync: (...args: any[]) => spawnSyncMock(...args),
 }));
 // ── platform stub ──────────────────────────────────────────────────────────────
 vi.mock('../platform/detect.js', () => ({
  getShellProfilePath: () => null,
 }));
 import { finalizeStage } from './finalize.js';
 // ── Helpers ────────────────────────────────────────────────────────────────────
 function makeState(mosaicHome: string, selectedSkills: string[] = []): WizardState {
  return {
    mosaicHome,
    sourceDir: mosaicHome,
    mode: 'quick',
    installAction: 'fresh',
    soul: { agentName: 'TestBot', communicationStyle: 'direct' },
    user: {},
    tools: {},
    runtimes: { detected: [], mcpConfigured: false },
    selectedSkills,
  };
 }
 function buildPrompter() {
  return {
    intro: vi.fn(),
    outro: vi.fn(),
    note: vi.fn(),
    log: vi.fn(),
    warn: vi.fn(),
    text: vi.fn(),
    confirm: vi.fn(),
    select: vi.fn(),
    multiselect: vi.fn(),
    groupMultiselect: vi.fn(),
    spinner: vi.fn().mockReturnValue({ update: vi.fn(), stop: vi.fn() }),
    separator: vi.fn(),
  };
 }
 function makeConfigService(): ConfigService {
  return {
    readSoul: vi.fn().mockResolvedValue({}),
    readUser: vi.fn().mockResolvedValue({}),
    readTools: vi.fn().mockResolvedValue({}),
    writeSoul: vi.fn().mockResolvedValue(undefined),
    writeUser: vi.fn().mockResolvedValue(undefined),
    writeTools: vi.fn().mockResolvedValue(undefined),
    syncFramework: vi.fn().mockResolvedValue(undefined),
    get: vi.fn(),
    set: vi.fn(),
    getSection: vi.fn(),
  } as unknown as ConfigService;
 }
 // ── Tests ──────────────────────────────────────────────────────────────────────
 describe('finalizeStage — skill installer', () => {
  let tmp: string;
  let binDir: string;
  let syncScript: string;
  beforeEach(() => {
    tmp = mkdtempSync(join(tmpdir(), 'mosaic-finalize-'));
    binDir = join(tmp, 'bin');
    mkdirSync(binDir, { recursive: true });
    syncScript = join(binDir, 'mosaic-sync-skills');
    // Default: script exists and succeeds
    writeFileSync(syncScript, '#!/usr/bin/env bash\necho ok\n', { mode: 0o755 });
    spawnSyncMock.mockReturnValue({ status: 0, stdout: 'ok', stderr: '' });
  });
  afterEach(() => {
    rmSync(tmp, { recursive: true, force: true });
    vi.clearAllMocks();
  });
  function findSkillsSyncCall() {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    return (spawnSyncMock.mock.calls as any[][]).find(
      (args) =>
        Array.isArray(args[1]) &&
        (args[1] as string[]).some((a) => a.includes('mosaic-sync-skills')),
    );
  }
  it('passes MOSAIC_INSTALL_SKILLS with the selected skill list', async () => {
    const state = makeState(tmp, ['brainstorming', 'lint', 'systematic-debugging']);
    const p = buildPrompter();
    const config = makeConfigService();
    await finalizeStage(p, state, config);
    const call = findSkillsSyncCall();
    expect(call).toBeDefined();
    const opts = call![2] as { env?: Record<string, string> };
    expect(opts.env?.['MOSAIC_INSTALL_SKILLS']).toBe('brainstorming:lint:systematic-debugging');
  });
  it('skips the sync script entirely when no skills are selected', async () => {
    const state = makeState(tmp, []);
    const p = buildPrompter();
    const config = makeConfigService();
    await finalizeStage(p, state, config);
    expect(findSkillsSyncCall()).toBeUndefined();
  });
  it('warns the user when the sync script exits non-zero', async () => {
    spawnSyncMock.mockReturnValue({
      status: 1,
      stdout: '',
      stderr: 'git clone failed: connection refused',
    });
    const state = makeState(tmp, ['brainstorming']);
    const p = buildPrompter();
    const config = makeConfigService();
    await finalizeStage(p, state, config);
    expect(p.warn).toHaveBeenCalledWith(expect.stringContaining('git clone failed'));
    expect(p.warn).toHaveBeenCalledWith(expect.stringContaining('mosaic sync'));
  });
  it('warns the user when the sync script is missing', async () => {
    // Remove the script to simulate a missing installation
    rmSync(syncScript);
    const state = makeState(tmp, ['brainstorming']);
    const p = buildPrompter();
    const config = makeConfigService();
    await finalizeStage(p, state, config);
    // spawnSync should NOT have been called for the skills script
    expect(findSkillsSyncCall()).toBeUndefined();
    expect(p.warn).toHaveBeenCalledWith(expect.stringContaining('not found'));
  });
  it('includes skills count in the summary when install succeeds', async () => {
    const state = makeState(tmp, ['brainstorming', 'lint']);
    const p = buildPrompter();
    const config = makeConfigService();
    await finalizeStage(p, state, config);
    const noteMock = p.note as ReturnType<typeof vi.fn>;
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const summaryCall = (noteMock.mock.calls as any[][]).find(
      ([, title]) => title === 'Installation Summary',
    );
    expect(summaryCall).toBeDefined();
    expect(summaryCall![0] as string).toContain('2 installed');
  });
 });
--- a/packages/mosaic/src/stages/finalize.ts
+++ b/packages/mosaic/src/stages/finalize.ts
@@ -25,14 +25,68 @@ function linkRuntimeAssets(mosaicHome: string, skipClaudeHooks: boolean): void {
  }
 }
-function syncSkills(mosaicHome: string): void {
+interface SyncSkillsResult {
  success: boolean;
  installedCount: number;
  failureReason?: string;
 }
 /**
 * Sync skills from the catalog and link only the user-selected subset.
 *
 * When `selectedSkills` is non-empty the script receives the list via
 * `MOSAIC_INSTALL_SKILLS` (colon-separated) so it can skip unlisted skills
 * during the linking phase.  An empty selection is a no-op.
 *
 * Failure modes surfaced here:
 *   - Script not found → tells the user explicitly
 *   - Script exits non-zero → stderr is captured and reported
 *   - Catalog directory missing → detected before exec, reported clearly
 */
 function syncSkills(mosaicHome: string, selectedSkills: string[]): SyncSkillsResult {
  if (selectedSkills.length === 0) {
    return { success: true, installedCount: 0 };
  }
  const script = join(mosaicHome, 'bin', 'mosaic-sync-skills');
-  if (existsSync(script)) {
+  if (!existsSync(script)) {
-    try {
+    return {
-      spawnSync('bash', [script], { timeout: 60000, stdio: 'pipe' });
+      success: false,
-    } catch {
+      installedCount: 0,
-      // Non-fatal
+      failureReason: `Skills sync script not found at ${script} — run 'mosaic sync' after installation.`,
    };
  }
  try {
    const result = spawnSync('bash', [script], {
      timeout: 60000,
      stdio: 'pipe',
      encoding: 'utf-8',
      env: {
        ...process.env,
        MOSAIC_HOME: mosaicHome,
        MOSAIC_INSTALL_SKILLS: selectedSkills.join(':'),
      },
    });
    if (result.status !== 0) {
      const stderr = (result.stderr ?? '').trim();
      return {
        success: false,
        installedCount: 0,
        failureReason: stderr
          ? `Skills sync failed: ${stderr}`
          : `Skills sync script exited with code ${(result.status ?? 'unknown').toString()}`,
      };
    }
    return { success: true, installedCount: selectedSkills.length };
  } catch (err) {
    return {
      success: false,
      installedCount: 0,
      failureReason: `Skills sync threw: ${err instanceof Error ? err.message : String(err)}`,
    };
  }
 }
@@ -124,10 +178,11 @@ export async function finalizeStage(
  const skipClaudeHooks = state.hooks?.accepted === false;
  linkRuntimeAssets(state.mosaicHome, skipClaudeHooks);
-  // 4. Sync skills
+  // 4. Sync skills (only installs the user-selected subset)
  let skillsResult: SyncSkillsResult = { success: true, installedCount: 0 };
  if (state.selectedSkills.length > 0) {
-    spin.update('Syncing skills...');
+    spin.update(`Installing ${state.selectedSkills.length.toString()} selected skill(s)...`);
-    syncSkills(state.mosaicHome);
+    skillsResult = syncSkills(state.mosaicHome, state.selectedSkills);
  }
  // 5. Run doctor
@@ -136,15 +191,27 @@ export async function finalizeStage(
  spin.stop('Installation complete');
  // Report skill install failure clearly (non-fatal but user should know)
  if (!skillsResult.success && skillsResult.failureReason) {
    p.warn(skillsResult.failureReason);
    p.warn("Run 'mosaic sync' manually after installation to install skills.");
  }
  // 6. PATH setup
  const pathAction = setupPath(state.mosaicHome, p);
  // 7. Summary
  const skillsSummary = skillsResult.success
    ? skillsResult.installedCount > 0
      ? `${skillsResult.installedCount.toString()} installed`
      : 'none selected'
    : `install failed — ${skillsResult.failureReason ?? 'unknown error'}`;
  const summary: string[] = [
    `Agent: ${state.soul.agentName ?? 'Assistant'}`,
    `Style: ${state.soul.communicationStyle ?? 'direct'}`,
    `Runtimes: ${state.runtimes.detected.join(', ') || 'none detected'}`,
-    `Skills: ${state.selectedSkills.length.toString()} selected`,
+    `Skills: ${skillsSummary}`,
    `Config: ${state.mosaicHome}`,
  ];
--- a/packages/mosaic/src/stages/gateway-bootstrap.ts
+++ b/packages/mosaic/src/stages/gateway-bootstrap.ts
@@ -158,7 +158,7 @@ export async function gatewayBootstrapStage(
      host,
      port,
      tier: 'local',
-      corsOrigin: 'http://localhost:3000',
+      corsOrigin: `http://${host}:3000`,
    }),
    admin: { name, email, password },
  };
--- a/packages/mosaic/src/stages/gateway-config-cors.spec.ts
+++ b/packages/mosaic/src/stages/gateway-config-cors.spec.ts
@@ -0,0 +1,69 @@
 import { describe, it, expect } from 'vitest';
 import { deriveCorsOrigin } from './gateway-config.js';
 describe('deriveCorsOrigin', () => {
  describe('localhost / loopback — always http', () => {
    it('localhost port 3000 → http://localhost:3000', () => {
      expect(deriveCorsOrigin('localhost', 3000)).toBe('http://localhost:3000');
    });
    it('127.0.0.1 port 3000 → http://127.0.0.1:3000', () => {
      expect(deriveCorsOrigin('127.0.0.1', 3000)).toBe('http://127.0.0.1:3000');
    });
    it('localhost port 80 omits port suffix', () => {
      expect(deriveCorsOrigin('localhost', 80)).toBe('http://localhost');
    });
    it('localhost port 443 still uses http (loopback overrides), includes port', () => {
      // 443 is the https default port, but since localhost forces http, the port
      // is NOT the default for http (80), so it must be included.
      expect(deriveCorsOrigin('localhost', 443)).toBe('http://localhost:443');
    });
    it('useHttps=false on localhost keeps http', () => {
      expect(deriveCorsOrigin('localhost', 3000, false)).toBe('http://localhost:3000');
    });
    it('useHttps=true on localhost still uses http (loopback wins)', () => {
      // Passing useHttps=true for localhost is unusual but the function honours
      // the explicit override — loopback detection only applies when useHttps is
      // undefined (auto-detect path).
      expect(deriveCorsOrigin('localhost', 3000, true)).toBe('https://localhost:3000');
    });
  });
  describe('remote hostname — defaults to https', () => {
    it('example.com port 3000 → https://example.com:3000', () => {
      expect(deriveCorsOrigin('example.com', 3000)).toBe('https://example.com:3000');
    });
    it('example.com port 443 omits port suffix', () => {
      expect(deriveCorsOrigin('example.com', 443)).toBe('https://example.com');
    });
    it('example.com port 80 → https://example.com:80 (non-default port for https)', () => {
      expect(deriveCorsOrigin('example.com', 80)).toBe('https://example.com:80');
    });
    it('useHttps=false on remote host uses http', () => {
      expect(deriveCorsOrigin('example.com', 3000, false)).toBe('http://example.com:3000');
    });
    it('useHttps=false on remote host, port 80 omits suffix', () => {
      expect(deriveCorsOrigin('example.com', 80, false)).toBe('http://example.com');
    });
  });
  describe('subdomain and non-standard hostnames', () => {
    it('sub.domain.example.com defaults to https', () => {
      expect(deriveCorsOrigin('sub.domain.example.com', 3000)).toBe(
        'https://sub.domain.example.com:3000',
      );
    });
    it('myserver.local defaults to https (not loopback)', () => {
      expect(deriveCorsOrigin('myserver.local', 8080)).toBe('https://myserver.local:8080');
    });
  });
 });
--- a/packages/mosaic/src/stages/gateway-config.ts
+++ b/packages/mosaic/src/stages/gateway-config.ts
@@ -26,6 +26,25 @@ function isHeadless(): boolean {
  return process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
 }
 // ── CORS derivation ───────────────────────────────────────────────────────────
 /**
 * Derive a full CORS origin URL from a user-provided hostname + web UI port.
 *
 * Rules:
 *   - "localhost" and "127.0.0.1" always use http (never https)
 *   - Everything else uses https by default; pass useHttps=false to override
 *   - Standard ports (80 for http, 443 for https) are omitted from the origin
 */
 export function deriveCorsOrigin(hostname: string, webUiPort: number, useHttps?: boolean): string {
  const isLocalhost = hostname === 'localhost' || hostname === '127.0.0.1';
  const proto =
    useHttps !== undefined ? (useHttps ? 'https' : 'http') : isLocalhost ? 'http' : 'https';
  const defaultPort = proto === 'https' ? 443 : 80;
  const portSuffix = webUiPort === defaultPort ? '' : `:${webUiPort.toString()}`;
  return `${proto}://${hostname}${portSuffix}`;
 }
 // ── .env helpers ──────────────────────────────────────────────────────────────
 function readEnvVarFromFile(envFile: string, key: string): string | null {
@@ -107,6 +126,14 @@ export interface GatewayConfigStageOptions {
  portOverride?: number;
  /** Skip the `npm install -g @mosaicstack/gateway` step (local build / tests). */
  skipInstall?: boolean;
  /**
   * Pre-collected provider API key (from the provider-setup stage or Quick
   * Start path). When set, the gateway-config stage will skip the interactive
   * API key prompt and use this value directly.
   */
  providerKey?: string;
  /** Provider type detected from the key prefix. */
  providerType?: 'anthropic' | 'openai' | 'none';
 }
 export interface GatewayConfigStageResult {
@@ -228,7 +255,9 @@ export async function gatewayConfigStage(
        host: existing.host,
        port: existing.port,
        tier: 'local',
-        corsOrigin: 'http://localhost:3000',
+        corsOrigin:
          readEnvVarFromFile(ENV_FILE, 'GATEWAY_CORS_ORIGIN') ??
          deriveCorsOrigin('localhost', 3000),
        regeneratedConfig: false,
      };
      return { ready: true, host: existing.host, port: existing.port };
@@ -281,7 +310,8 @@ export async function gatewayConfigStage(
      host,
      port,
      tier: 'local',
-      corsOrigin: 'http://localhost:3000',
+      corsOrigin:
        readEnvVarFromFile(ENV_FILE, 'GATEWAY_CORS_ORIGIN') ?? deriveCorsOrigin('localhost', 3000),
      regeneratedConfig: false,
    };
  } else {
@@ -292,6 +322,8 @@ export async function gatewayConfigStage(
        envFile: ENV_FILE,
        mosaicConfigFile: MOSAIC_CONFIG_FILE,
        gatewayHome: GATEWAY_HOME,
        providerKey: opts.providerKey,
        providerType: opts.providerType,
      });
    } catch (err) {
      if (err instanceof GatewayConfigValidationError) {
@@ -367,6 +399,10 @@ interface CollectOptions {
  envFile: string;
  mosaicConfigFile: string;
  gatewayHome: string;
  /** Pre-collected API key — skips the interactive prompt when set. */
  providerKey?: string;
  /** Provider type — determines the env var name for the key. */
  providerType?: 'anthropic' | 'openai' | 'none';
 }
 /** Raised by the config stage when headless env validation fails. */
@@ -395,6 +431,7 @@ async function collectAndWriteConfig(
  let valkeyUrl: string | undefined;
  let anthropicKey: string;
  let corsOrigin: string;
  let hostname: string;
  if (isHeadless()) {
    p.log('Headless mode detected — reading configuration from environment variables.');
@@ -408,7 +445,13 @@ async function collectAndWriteConfig(
    databaseUrl = process.env['MOSAIC_DATABASE_URL'];
    valkeyUrl = process.env['MOSAIC_VALKEY_URL'];
    anthropicKey = process.env['MOSAIC_ANTHROPIC_API_KEY'] ?? '';
-    corsOrigin = process.env['MOSAIC_CORS_ORIGIN'] ?? 'http://localhost:3000';
+
    // MOSAIC_CORS_ORIGIN is the full override (e.g. from CI).
    // MOSAIC_HOSTNAME is the user-friendly alternative — derive from it.
    const corsOverride = process.env['MOSAIC_CORS_ORIGIN'];
    const hostnameEnv = process.env['MOSAIC_HOSTNAME'] ?? 'localhost';
    hostname = hostnameEnv;
    corsOrigin = corsOverride ?? deriveCorsOrigin(hostnameEnv, 3000);
    if (tier === 'team') {
      const missing: string[] = [];
@@ -437,16 +480,34 @@ async function collectAndWriteConfig(
      });
    }
-    anthropicKey = await p.text({
+    if (opts.providerKey) {
-      message: 'ANTHROPIC_API_KEY (optional, press Enter to skip)',
+      anthropicKey = opts.providerKey;
-      defaultValue: '',
+      p.log(`Using API key from provider setup (${opts.providerType ?? 'unknown'}).`);
    } else {
      anthropicKey = await p.text({
        message: 'ANTHROPIC_API_KEY (optional, press Enter to skip)',
        defaultValue: '',
      });
    }
    hostname = await p.text({
      message: 'Web UI hostname (for browser access)',
      initialValue: 'localhost',
      defaultValue: 'localhost',
      placeholder: 'e.g. localhost or myserver.example.com',
    });
-    corsOrigin = await p.text({
+    // For non-localhost, ask if HTTPS is in use (defaults to yes for remote hosts)
-      message: 'CORS origin',
+    let useHttps: boolean | undefined;
-      initialValue: 'http://localhost:3000',
+    if (hostname !== 'localhost' && hostname !== '127.0.0.1') {
-      defaultValue: 'http://localhost:3000',
+      useHttps = await p.confirm({
-    });
+        message: 'Is HTTPS enabled for the web UI?',
        initialValue: true,
      });
    }
    corsOrigin = deriveCorsOrigin(hostname, 3000, useHttps);
    p.log(`CORS origin set to: ${corsOrigin}`);
  }
  const authSecret = preservedAuthSecret ?? randomBytes(32).toString('hex');
@@ -466,7 +527,11 @@ async function collectAndWriteConfig(
  }
  if (anthropicKey) {
-    envLines.push(`ANTHROPIC_API_KEY=${anthropicKey}`);
+    if (opts.providerType === 'openai') {
      envLines.push(`OPENAI_API_KEY=${anthropicKey}`);
    } else {
      envLines.push(`ANTHROPIC_API_KEY=${anthropicKey}`);
    }
  }
  writeFileSync(opts.envFile, envLines.join('\n') + '\n', { mode: 0o600 });
@@ -500,6 +565,7 @@ async function collectAndWriteConfig(
    valkeyUrl,
    anthropicKey: anthropicKey || undefined,
    corsOrigin,
    hostname,
    regeneratedConfig: true,
  };
 }
--- a/packages/mosaic/src/stages/provider-setup.spec.ts
+++ b/packages/mosaic/src/stages/provider-setup.spec.ts
@@ -0,0 +1,118 @@
 import { describe, it, expect, vi, afterEach } from 'vitest';
 import type { WizardState } from '../types.js';
 import { providerSetupStage } from './provider-setup.js';
 function buildPrompter(overrides: Partial<Record<string, unknown>> = {}) {
  return {
    intro: vi.fn(),
    outro: vi.fn(),
    note: vi.fn(),
    log: vi.fn(),
    warn: vi.fn(),
    text: vi.fn().mockResolvedValue(''),
    confirm: vi.fn().mockResolvedValue(false),
    select: vi.fn().mockResolvedValue('general'),
    multiselect: vi.fn(),
    groupMultiselect: vi.fn(),
    spinner: vi.fn().mockReturnValue({ update: vi.fn(), stop: vi.fn() }),
    separator: vi.fn(),
    ...overrides,
  };
 }
 function makeState(): WizardState {
  return {
    mosaicHome: '/tmp/mosaic',
    sourceDir: '/tmp/mosaic',
    mode: 'quick',
    installAction: 'fresh',
    soul: {},
    user: {},
    tools: {},
    runtimes: { detected: [], mcpConfigured: false },
    selectedSkills: [],
  };
 }
 describe('providerSetupStage', () => {
  const originalEnv = { ...process.env };
  afterEach(() => {
    process.env = { ...originalEnv };
  });
  it('detects Anthropic key from prefix in headless mode', async () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    process.env['MOSAIC_ANTHROPIC_API_KEY'] = 'sk-ant-api03-test123';
    const state = makeState();
    const p = buildPrompter();
    await providerSetupStage(p, state);
    expect(state.providerKey).toBe('sk-ant-api03-test123');
    expect(state.providerType).toBe('anthropic');
  });
  it('detects OpenAI key from prefix in headless mode', async () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    process.env['MOSAIC_OPENAI_API_KEY'] = 'sk-proj-test123';
    const state = makeState();
    const p = buildPrompter();
    await providerSetupStage(p, state);
    expect(state.providerKey).toBe('sk-proj-test123');
    expect(state.providerType).toBe('openai');
  });
  it('sets provider type to none when no key is provided in headless mode', async () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    delete process.env['MOSAIC_ANTHROPIC_API_KEY'];
    delete process.env['MOSAIC_OPENAI_API_KEY'];
    const state = makeState();
    const p = buildPrompter();
    await providerSetupStage(p, state);
    expect(state.providerKey).toBeUndefined();
    expect(state.providerType).toBe('none');
  });
  it('prompts for key in interactive mode', async () => {
    delete process.env['MOSAIC_ASSUME_YES'];
    // Simulate a TTY
    const origIsTTY = process.stdin.isTTY;
    Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
    const state = makeState();
    const p = buildPrompter({
      text: vi.fn().mockResolvedValue('sk-ant-api03-interactive'),
    });
    await providerSetupStage(p, state);
    expect(p.text).toHaveBeenCalled();
    expect(state.providerKey).toBe('sk-ant-api03-interactive');
    expect(state.providerType).toBe('anthropic');
    Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
  });
  it('handles empty key in interactive mode', async () => {
    delete process.env['MOSAIC_ASSUME_YES'];
    const origIsTTY = process.stdin.isTTY;
    Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
    const state = makeState();
    const p = buildPrompter({
      text: vi.fn().mockResolvedValue(''),
    });
    await providerSetupStage(p, state);
    expect(state.providerType).toBe('none');
    expect(state.providerKey).toBeUndefined();
    Object.defineProperty(process.stdin, 'isTTY', { value: origIsTTY, configurable: true });
  });
 });
--- a/packages/mosaic/src/stages/provider-setup.ts
+++ b/packages/mosaic/src/stages/provider-setup.ts
@@ -0,0 +1,54 @@
 import type { WizardPrompter } from '../prompter/interface.js';
 import type { WizardState } from '../types.js';
 import { detectProviderType } from '../constants.js';
 /**
 * Provider setup stage — collects the user's LLM API key and detects the
 * provider type from the key prefix.
 *
 * In headless mode, reads from `MOSAIC_ANTHROPIC_API_KEY` or `MOSAIC_OPENAI_API_KEY`.
 */
 export async function providerSetupStage(p: WizardPrompter, state: WizardState): Promise<void> {
  const isHeadless = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
  if (isHeadless) {
    const anthropicKey = process.env['MOSAIC_ANTHROPIC_API_KEY'] ?? '';
    const openaiKey = process.env['MOSAIC_OPENAI_API_KEY'] ?? '';
    const key = anthropicKey || openaiKey;
    state.providerKey = key || undefined;
    state.providerType = detectProviderType(key);
    return;
  }
  p.separator();
  p.note(
    'Configure your LLM provider so the agent has a brain.\n' +
      'Anthropic (Claude) and OpenAI are supported.\n' +
      'You can skip this and add a key later via `mosaic configure`.',
    'LLM Provider',
  );
  const key = await p.text({
    message: 'API key (paste your Anthropic or OpenAI key, or press Enter to skip)',
    defaultValue: '',
    placeholder: 'sk-ant-api03-... or sk-...',
  });
  if (key) {
    const provider = detectProviderType(key);
    state.providerKey = key;
    state.providerType = provider;
    if (provider === 'anthropic') {
      p.log('Detected provider: Anthropic (Claude)');
    } else if (provider === 'openai') {
      p.log('Detected provider: OpenAI');
    } else {
      p.log('Provider auto-detection failed. Key will be stored as ANTHROPIC_API_KEY.');
      state.providerType = 'anthropic';
    }
  } else {
    state.providerType = 'none';
    p.log('No API key provided. You can add one later with `mosaic configure`.');
  }
 }
--- a/packages/mosaic/src/stages/quick-start.ts
+++ b/packages/mosaic/src/stages/quick-start.ts
@@ -0,0 +1,98 @@
 import type { WizardPrompter } from '../prompter/interface.js';
 import type { ConfigService } from '../config/config-service.js';
 import type { WizardState } from '../types.js';
 import { DEFAULTS } from '../constants.js';
 import { providerSetupStage } from './provider-setup.js';
 import { runtimeSetupStage } from './runtime-setup.js';
 import { hooksPreviewStage } from './hooks-preview.js';
 import { skillsSelectStage } from './skills-select.js';
 import { finalizeStage } from './finalize.js';
 import { gatewayConfigStage } from './gateway-config.js';
 import { gatewayBootstrapStage } from './gateway-bootstrap.js';
 export interface QuickStartOptions {
  skipGateway?: boolean;
  gatewayHost?: string;
  gatewayPort?: number;
  gatewayPortOverride?: number;
  skipGatewayNpmInstall?: boolean;
 }
 /**
 * Quick Start path — minimal questions to get a working agent.
 *
 * 1. Provider API key
 * 2. Admin email + password (via gateway bootstrap)
 * 3. Everything else uses defaults.
 *
 * Target: under 90 seconds for a returning user.
 */
 export async function quickStartPath(
  prompter: WizardPrompter,
  state: WizardState,
  configService: ConfigService,
  options: QuickStartOptions,
 ): Promise<void> {
  state.mode = 'quick';
  // 1. Provider setup (first question)
  await providerSetupStage(prompter, state);
  // Apply sensible defaults for everything else
  state.soul.agentName ??= 'Mosaic';
  state.soul.roleDescription ??= DEFAULTS.roleDescription;
  state.soul.communicationStyle ??= 'direct';
  state.user.background = DEFAULTS.background;
  state.user.accessibilitySection = DEFAULTS.accessibilitySection;
  state.user.personalBoundaries = DEFAULTS.personalBoundaries;
  state.tools.gitProviders = [];
  state.tools.credentialsLocation = DEFAULTS.credentialsLocation;
  state.tools.customToolsSection = DEFAULTS.customToolsSection;
  // Runtime detection (auto, no user input in quick mode)
  await runtimeSetupStage(prompter, state);
  // Hooks (auto-accept in quick mode for Claude)
  await hooksPreviewStage(prompter, state);
  // Skills (recommended set, no user input in quick mode)
  await skillsSelectStage(prompter, state);
  // Finalize (writes configs, links runtime assets, syncs skills)
  await finalizeStage(prompter, state, configService);
  // Gateway config + bootstrap
  if (!options.skipGateway) {
    const headlessRun = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
    try {
      const configResult = await gatewayConfigStage(prompter, state, {
        host: options.gatewayHost ?? 'localhost',
        defaultPort: options.gatewayPort ?? 14242,
        portOverride: options.gatewayPortOverride,
        skipInstall: options.skipGatewayNpmInstall,
        providerKey: state.providerKey,
        providerType: state.providerType ?? 'none',
      });
      if (!configResult.ready || !configResult.host || !configResult.port) {
        if (headlessRun) {
          prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
          process.exit(1);
        }
      } else {
        const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
          host: configResult.host,
          port: configResult.port,
        });
        if (!bootstrapResult.completed) {
          prompter.warn('Admin bootstrap failed — aborting wizard.');
          process.exit(1);
        }
      }
    } catch (err) {
      prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
      throw err;
    }
  }
 }
--- a/packages/mosaic/src/stages/wizard-menu.spec.ts
+++ b/packages/mosaic/src/stages/wizard-menu.spec.ts
@@ -0,0 +1,118 @@
 import { describe, it, expect, afterEach } from 'vitest';
 import type { MenuSection } from '../types.js';
 import { detectProviderType, INTENT_PRESETS } from '../constants.js';
 /**
 * Tests for the drill-down menu system and its supporting utilities.
 *
 * The menu loop itself is in wizard.ts and is hard to unit test in isolation
 * because it orchestrates many async stages. These tests verify the building
 * blocks: provider detection, intent presets, and the WizardState shape.
 */
 describe('detectProviderType', () => {
  it('detects Anthropic from sk-ant- prefix', () => {
    expect(detectProviderType('sk-ant-api03-abc123')).toBe('anthropic');
  });
  it('detects OpenAI from sk- prefix', () => {
    expect(detectProviderType('sk-proj-abc123')).toBe('openai');
  });
  it('returns none for empty string', () => {
    expect(detectProviderType('')).toBe('none');
  });
  it('returns none for unrecognized prefix', () => {
    expect(detectProviderType('gsk_abc123')).toBe('none');
  });
 });
 describe('INTENT_PRESETS', () => {
  it('has all expected intent categories', () => {
    expect(Object.keys(INTENT_PRESETS)).toEqual(
      expect.arrayContaining([
        'general',
        'software-dev',
        'devops',
        'research',
        'content',
        'custom',
      ]),
    );
  });
  it('each preset has label, hint, and suggestedName', () => {
    for (const [key, preset] of Object.entries(INTENT_PRESETS)) {
      expect(preset.label, `${key}.label`).toBeTruthy();
      expect(preset.hint, `${key}.hint`).toBeTruthy();
      expect(preset.suggestedName, `${key}.suggestedName`).toBeTruthy();
    }
  });
  it('maps software-dev to Forge', () => {
    expect(INTENT_PRESETS['software-dev']?.suggestedName).toBe('Forge');
  });
  it('maps devops to Sentinel', () => {
    expect(INTENT_PRESETS['devops']?.suggestedName).toBe('Sentinel');
  });
 });
 describe('WizardState completedSections', () => {
  it('tracks completed sections as a Set', () => {
    const completed = new Set<MenuSection>();
    completed.add('providers');
    completed.add('identity');
    expect(completed.has('providers')).toBe(true);
    expect(completed.has('identity')).toBe(true);
    expect(completed.has('skills')).toBe(false);
    expect(completed.size).toBe(2);
  });
 });
 describe('headless backward compat', () => {
  const originalEnv = { ...process.env };
  afterEach(() => {
    process.env = { ...originalEnv };
  });
  it('MOSAIC_ASSUME_YES=1 triggers headless path', () => {
    process.env['MOSAIC_ASSUME_YES'] = '1';
    const isHeadless = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
    expect(isHeadless).toBe(true);
  });
  it('non-TTY triggers headless path', () => {
    delete process.env['MOSAIC_ASSUME_YES'];
    // In test environments, process.stdin.isTTY is typically undefined (falsy)
    const isHeadless = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
    expect(isHeadless).toBe(true);
  });
  it('all headless env vars are recognized', () => {
    // This test documents the expected env vars for headless installs.
    const headlessVars = [
      'MOSAIC_ASSUME_YES',
      'MOSAIC_ADMIN_NAME',
      'MOSAIC_ADMIN_EMAIL',
      'MOSAIC_ADMIN_PASSWORD',
      'MOSAIC_GATEWAY_PORT',
      'MOSAIC_HOSTNAME',
      'MOSAIC_CORS_ORIGIN',
      'MOSAIC_STORAGE_TIER',
      'MOSAIC_DATABASE_URL',
      'MOSAIC_VALKEY_URL',
      'MOSAIC_ANTHROPIC_API_KEY',
      'MOSAIC_AGENT_NAME',
      'MOSAIC_AGENT_INTENT',
    ];
    // Just verify none of them throw when accessed
    for (const v of headlessVars) {
      expect(() => process.env[v]).not.toThrow();
    }
  });
 });
--- a/packages/mosaic/src/types.ts
+++ b/packages/mosaic/src/types.ts
@@ -3,6 +3,19 @@ export type InstallAction = 'fresh' | 'keep' | 'reconfigure' | 'reset';
 export type CommunicationStyle = 'direct' | 'friendly' | 'formal';
 export type RuntimeName = 'claude' | 'codex' | 'opencode' | 'pi';
 export type MenuSection =
  | 'quick-start'
  | 'providers'
  | 'identity'
  | 'skills'
  | 'gateway'
  | 'advanced'
  | 'finish';
 export type AgentIntent = 'general' | 'software-dev' | 'devops' | 'research' | 'content' | 'custom';
 export type ProviderType = 'anthropic' | 'openai' | 'none';
 export interface SoulConfig {
  agentName?: string;
  roleDescription?: string;
@@ -62,6 +75,11 @@ export interface GatewayState {
  valkeyUrl?: string;
  anthropicKey?: string;
  corsOrigin: string;
  /**
   * Raw hostname the user entered (e.g. "localhost", "myserver.example.com").
   * The full CORS origin (`corsOrigin`) is derived from this + protocol + webUiPort.
   */
  hostname?: string;
  /** True when .env + mosaic.config.json were (re)generated in this run. */
  regeneratedConfig?: boolean;
  admin?: GatewayAdminState;
@@ -81,4 +99,12 @@ export interface WizardState {
  selectedSkills: string[];
  hooks?: HooksState;
  gateway?: GatewayState;
  /** Tracks which menu sections have been completed in drill-down mode. */
  completedSections?: Set<MenuSection>;
  /** The user's chosen agent intent category. */
  agentIntent?: AgentIntent;
  /** The LLM provider API key entered during setup. */
  providerKey?: string;
  /** Detected provider type based on API key prefix. */
  providerType?: ProviderType;
 }
--- a/packages/mosaic/src/wizard.ts
+++ b/packages/mosaic/src/wizard.ts
@@ -1,9 +1,8 @@
 import type { WizardPrompter } from './prompter/interface.js';
 import type { ConfigService } from './config/config-service.js';
-import type { WizardState } from './types.js';
+import type { MenuSection, WizardState } from './types.js';
 import { welcomeStage } from './stages/welcome.js';
 import { detectInstallStage } from './stages/detect-install.js';
 import { modeSelectStage } from './stages/mode-select.js';
 import { soulSetupStage } from './stages/soul-setup.js';
 import { userSetupStage } from './stages/user-setup.js';
 import { toolsSetupStage } from './stages/tools-setup.js';
@@ -13,6 +12,10 @@ import { skillsSelectStage } from './stages/skills-select.js';
 import { finalizeStage } from './stages/finalize.js';
 import { gatewayConfigStage } from './stages/gateway-config.js';
 import { gatewayBootstrapStage } from './stages/gateway-bootstrap.js';
 import { providerSetupStage } from './stages/provider-setup.js';
 import { agentIntentStage } from './stages/agent-intent.js';
 import { quickStartPath } from './stages/quick-start.js';
 import { DEFAULTS } from './constants.js';
 export interface WizardOptions {
  mosaicHome: string;
@@ -54,6 +57,7 @@ export async function runWizard(options: WizardOptions): Promise<void> {
    tools: {},
    runtimes: { detected: [], mcpConfigured: false },
    selectedSkills: [],
    completedSections: new Set<MenuSection>(),
  };
  // Apply CLI overrides (strip undefined values)
@@ -90,55 +94,304 @@ export async function runWizard(options: WizardOptions): Promise<void> {
  // Stage 2: Existing Install Detection
  await detectInstallStage(prompter, state, configService);
-  // Stage 3: Quick Start vs Advanced (skip if keeping existing)
+  // ── Headless bypass ────────────────────────────────────────────────────────
-  if (state.installAction === 'fresh' || state.installAction === 'reset') {
+  // When MOSAIC_ASSUME_YES=1 or no TTY, run the linear headless path.
-    await modeSelectStage(prompter, state);
+  // This preserves full backward compatibility with tools/install.sh --yes.
-  } else if (state.installAction === 'reconfigure') {
+  const headlessRun = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
-    state.mode = 'advanced';
+  if (headlessRun) {
    await runHeadlessPath(prompter, state, configService, options);
    return;
  }
-  // Stage 4: SOUL.md
+  // ── Interactive: Main Menu ─────────────────────────────────────────────────
  if (state.installAction === 'fresh' || state.installAction === 'reset') {
    await runMenuLoop(prompter, state, configService, options);
  } else if (state.installAction === 'reconfigure') {
    state.mode = 'advanced';
    await runMenuLoop(prompter, state, configService, options);
  } else {
    // 'keep' — skip identity setup, go straight to finalize + gateway
    await runKeepPath(prompter, state, configService, options);
  }
 }
 // ── Menu-driven interactive flow ────────────────────────────────────────────
 type MenuChoice =
  | 'quick-start'
  | 'providers'
  | 'identity'
  | 'skills'
  | 'gateway-config'
  | 'advanced'
  | 'finish';
 function menuLabel(section: MenuChoice, completed: Set<MenuSection>): string {
  const labels: Record<MenuChoice, string> = {
    'quick-start': 'Quick Start',
    providers: 'Providers',
    identity: 'Agent Identity',
    skills: 'Skills',
    'gateway-config': 'Gateway',
    advanced: 'Advanced',
    finish: 'Finish & Apply',
  };
  const base = labels[section];
  const sectionKey: MenuSection =
    section === 'gateway-config' ? 'gateway' : (section as MenuSection);
  if (completed.has(sectionKey)) {
    return `${base} [done]`;
  }
  return base;
 }
 async function runMenuLoop(
  prompter: WizardPrompter,
  state: WizardState,
  configService: ConfigService,
  options: WizardOptions,
 ): Promise<void> {
  const completed = state.completedSections!;
  for (;;) {
    const choice = await prompter.select<MenuChoice>({
      message: 'What would you like to configure?',
      options: [
        {
          value: 'quick-start',
          label: menuLabel('quick-start', completed),
          hint: 'Recommended defaults, minimal questions',
        },
        {
          value: 'providers',
          label: menuLabel('providers', completed),
          hint: 'LLM API keys (Anthropic, OpenAI)',
        },
        {
          value: 'identity',
          label: menuLabel('identity', completed),
          hint: 'Agent name, intent, persona',
        },
        {
          value: 'skills',
          label: menuLabel('skills', completed),
          hint: 'Install agent skills',
        },
        {
          value: 'gateway-config',
          label: menuLabel('gateway-config', completed),
          hint: 'Port, storage, database',
        },
        {
          value: 'advanced',
          label: menuLabel('advanced', completed),
          hint: 'SOUL.md, USER.md, TOOLS.md, runtimes, hooks',
        },
        {
          value: 'finish',
          label: menuLabel('finish', completed),
          hint: 'Write configs and start gateway',
        },
      ],
    });
    switch (choice) {
      case 'quick-start':
        await quickStartPath(prompter, state, configService, options);
        return; // Quick start is a complete flow — exit menu
      case 'providers':
        await providerSetupStage(prompter, state);
        completed.add('providers');
        break;
      case 'identity':
        await agentIntentStage(prompter, state);
        completed.add('identity');
        break;
      case 'skills':
        await skillsSelectStage(prompter, state);
        completed.add('skills');
        break;
      case 'gateway-config':
        // Gateway config is handled during Finish — mark as "configured"
        // after user reviews settings.
        await runGatewaySubMenu(prompter, state, options);
        completed.add('gateway');
        break;
      case 'advanced':
        await runAdvancedSubMenu(prompter, state);
        completed.add('advanced');
        break;
      case 'finish':
        await runFinishPath(prompter, state, configService, options);
        return; // Done
    }
  }
 }
 // ── Gateway sub-menu ─────────────────────────────────────────────────────────
 async function runGatewaySubMenu(
  prompter: WizardPrompter,
  state: WizardState,
  _options: WizardOptions,
 ): Promise<void> {
  prompter.note(
    'Gateway settings will be applied when you select "Finish & Apply".\n' +
      'Configure the settings you want to customize here.',
    'Gateway Configuration',
  );
  // For now, just let them know defaults will be used and they can
  // override during finish. The actual gateway config stage runs
  // during Finish & Apply. This menu item exists so users know
  // the gateway is part of the wizard.
  const port = await prompter.text({
    message: 'Gateway port',
    initialValue: (_options.gatewayPort ?? 14242).toString(),
    defaultValue: (_options.gatewayPort ?? 14242).toString(),
    validate: (v) => {
      const n = parseInt(v, 10);
      if (Number.isNaN(n) || n < 1 || n > 65535) return 'Port must be 1-65535';
      return undefined;
    },
  });
  // Store for later use in the gateway config stage
  _options.gatewayPort = parseInt(port, 10);
  prompter.log(`Gateway port set to ${port}. Will be applied during Finish & Apply.`);
 }
 // ── Advanced sub-menu ────────────────────────────────────────────────────────
 async function runAdvancedSubMenu(prompter: WizardPrompter, state: WizardState): Promise<void> {
  state.mode = 'advanced';
  // Run the detailed setup stages
  await soulSetupStage(prompter, state);
  // Stage 5: USER.md
  await userSetupStage(prompter, state);
  // Stage 6: TOOLS.md
  await toolsSetupStage(prompter, state);
  // Stage 7: Runtime Detection & Installation
  await runtimeSetupStage(prompter, state);
  // Stage 8: Hooks preview (Claude only — skipped if Claude not detected)
  await hooksPreviewStage(prompter, state);
 }
-  // Stage 9: Skills Selection
+// ── Finish & Apply ──────────────────────────────────────────────────────────
  await skillsSelectStage(prompter, state);
-  // Stage 10: Finalize (writes configs, links runtime assets, runs doctor)
+async function runFinishPath(
  prompter: WizardPrompter,
  state: WizardState,
  configService: ConfigService,
  options: WizardOptions,
 ): Promise<void> {
  // Apply defaults for anything not explicitly configured
  state.soul.agentName ??= 'Mosaic';
  state.soul.roleDescription ??= DEFAULTS.roleDescription;
  state.soul.communicationStyle ??= 'direct';
  state.user.background ??= DEFAULTS.background;
  state.user.accessibilitySection ??= DEFAULTS.accessibilitySection;
  state.user.personalBoundaries ??= DEFAULTS.personalBoundaries;
  state.tools.gitProviders ??= [];
  state.tools.credentialsLocation ??= DEFAULTS.credentialsLocation;
  state.tools.customToolsSection ??= DEFAULTS.customToolsSection;
  // Runtime detection if not already done
  if (state.runtimes.detected.length === 0 && !state.completedSections?.has('advanced')) {
    await runtimeSetupStage(prompter, state);
    await hooksPreviewStage(prompter, state);
  }
  // Skills defaults if not already configured
  if (!state.completedSections?.has('skills')) {
    await skillsSelectStage(prompter, state);
  }
  // Finalize (writes configs, links runtime assets, syncs skills)
  await finalizeStage(prompter, state, configService);
-  // Stages 11 & 12: Gateway config + admin bootstrap.
+  // Gateway stages
  // The unified first-run flow runs these as terminal stages so the user
  // goes from "welcome" through "admin user created" in a single cohesive
  // experience. Callers that only want the framework portion pass
  // `skipGateway: true`.
  if (!options.skipGateway) {
    const headlessRun = process.env['MOSAIC_ASSUME_YES'] === '1' || !process.stdin.isTTY;
    try {
      const configResult = await gatewayConfigStage(prompter, state, {
        host: options.gatewayHost ?? 'localhost',
        defaultPort: options.gatewayPort ?? 14242,
        portOverride: options.gatewayPortOverride,
        skipInstall: options.skipGatewayNpmInstall,
        providerKey: state.providerKey,
        providerType: state.providerType ?? 'none',
      });
      if (configResult.ready && configResult.host && configResult.port) {
        const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
          host: configResult.host,
          port: configResult.port,
        });
        if (!bootstrapResult.completed) {
          prompter.warn('Admin bootstrap failed — aborting wizard.');
          process.exit(1);
        }
      }
    } catch (err) {
      prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
      throw err;
    }
  }
 }
 // ── Headless linear path (backward compat) ──────────────────────────────────
 async function runHeadlessPath(
  prompter: WizardPrompter,
  state: WizardState,
  configService: ConfigService,
  options: WizardOptions,
 ): Promise<void> {
  // Provider setup from env vars
  await providerSetupStage(prompter, state);
  // Agent intent from env vars
  await agentIntentStage(prompter, state);
  // SOUL.md
  await soulSetupStage(prompter, state);
  // USER.md
  await userSetupStage(prompter, state);
  // TOOLS.md
  await toolsSetupStage(prompter, state);
  // Runtime Detection
  await runtimeSetupStage(prompter, state);
  // Hooks
  await hooksPreviewStage(prompter, state);
  // Skills
  await skillsSelectStage(prompter, state);
  // Finalize
  await finalizeStage(prompter, state, configService);
  // Gateway stages
  if (!options.skipGateway) {
    try {
      const configResult = await gatewayConfigStage(prompter, state, {
        host: options.gatewayHost ?? 'localhost',
        defaultPort: options.gatewayPort ?? 14242,
        portOverride: options.gatewayPortOverride,
        skipInstall: options.skipGatewayNpmInstall,
        providerKey: state.providerKey,
        providerType: state.providerType ?? 'none',
      });
      if (!configResult.ready || !configResult.host || !configResult.port) {
-        if (headlessRun) {
+        prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
-          prompter.warn('Gateway configuration failed in headless mode — aborting wizard.');
+        process.exit(1);
          process.exit(1);
        }
      } else {
        const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
          host: configResult.host,
@@ -150,12 +403,53 @@ export async function runWizard(options: WizardOptions): Promise<void> {
        }
      }
    } catch (err) {
-      // Stages normally return structured `ready: false` results for
+      prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
-      // expected failures. Anything that reaches here is an unexpected
+      throw err;
-      // runtime error — render a concise warning for UX AND re-throw so
+    }
-      // the CLI (and `tools/install.sh` auto-launch) sees a non-zero exit.
+  }
-      // Swallowing here would let headless installs report success even
+}
-      // when the gateway stage crashed.
+
 // ── Keep path (preserve existing identity) ──────────────────────────────────
 async function runKeepPath(
  prompter: WizardPrompter,
  state: WizardState,
  configService: ConfigService,
  options: WizardOptions,
 ): Promise<void> {
  // Runtime detection
  await runtimeSetupStage(prompter, state);
  // Hooks
  await hooksPreviewStage(prompter, state);
  // Skills
  await skillsSelectStage(prompter, state);
  // Finalize
  await finalizeStage(prompter, state, configService);
  // Gateway stages
  if (!options.skipGateway) {
    try {
      const configResult = await gatewayConfigStage(prompter, state, {
        host: options.gatewayHost ?? 'localhost',
        defaultPort: options.gatewayPort ?? 14242,
        portOverride: options.gatewayPortOverride,
        skipInstall: options.skipGatewayNpmInstall,
      });
      if (configResult.ready && configResult.host && configResult.port) {
        const bootstrapResult = await gatewayBootstrapStage(prompter, state, {
          host: configResult.host,
          port: configResult.port,
        });
        if (!bootstrapResult.completed) {
          prompter.warn('Admin bootstrap failed — aborting wizard.');
          process.exit(1);
        }
      }
    } catch (err) {
      prompter.warn(`Gateway setup failed: ${err instanceof Error ? err.message : String(err)}`);
      throw err;
    }
Author	SHA1	Message	Date
jason.woltje	bd76df1a50	feat(mosaic): drill-down main menu + provider-first flow + quick start (#446 )	2026-04-06 00:15:23 +00:00
jason.woltje	62b2ce2da1	docs: orchestrator close-out IUV-M02 (#445 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 23:50:55 +00:00
jason.woltje	172bacb30f	feat(mosaic): IUV-M02 — CORS/FQDN UX polish + skill installer rework (#444 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 23:44:07 +00:00
jason.woltje	43667d7349	docs: orchestrator close-out IUV-M01 — mark tasks done, append session 2 (#443 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 22:40:08 +00:00
jason.woltje	783884376c	docs: mark IUV-M01 complete — mosaic-v0.0.26 released (#436 ) (#442 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 22:31:37 +00:00
jason.woltje	c08aa6fa46	fix: add vitest.config.ts to eslint allowDefaultProject (#440 build fix) (#441 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/tag/publish Pipeline was successful Details	2026-04-05 22:01:57 +00:00