v0.8.67 Setup: implement the setup wizard shell, navigation, resume, and `/setup` entry point

[Hmbown]

Product shape

The wizard shell is the spine of setup: one overlay/controller that holds the step list, current step, per-step status (from the #3403 state model), and summary. To the user it should feel like a single guided flow with consistent back/next/skip/retry affordances and a live progress indicator — whether they hit it on first run or reopen it with /setup six months later. To implementers it is the contract that lets a new step plug in without reinventing navigation, persistence, or status rendering.

Concrete implementation surface

• Entry points: the /setup slash command (TUI) and codewhale setup (CLI, already delegates to the TUI at crates/cli/src/lib.rs).
• Likely new home: a wizard controller + step trait under crates/tui/src/tui/setup/, reusing crates/tui/src/tui/onboarding/ (welcome, language, api_key, trust_directory) as the first steps, backed by the state model from v0.8.67 Setup: audit current setup/onboarding surfaces and define the unified setup state model #3403.
• Status/summary rendering should reuse the existing localization path (crates/tui/src/localization.rs, MessageId + tr(locale, id)).
• Config writes go through the transactional persistence in v0.8.67 Setup: config persistence, migration, secret handling, and rollback #3410 — never directly from a step.

Non-goals

• Not implementing step contents (provider, trust, tools, …) — those are v0.8.67 Setup support: provider/model readiness card for constitution-first setup #3405–v0.8.67 Setup: remote, mobile, chat bridge, and runtime API step #3409. This issue lands navigation, state plumbing, resume, and the /setup entry point.
• Not defining a separate state model — it consumes the one v0.8.67 Setup: audit current setup/onboarding surfaces and define the unified setup state model #3403 defines.
• Not requiring a restart to enter or leave setup; /setup opens and returns within a normal session.

Safe fallback

• Cancel / exit-without-saving leaves all config untouched (no partial writes; enforced via v0.8.67 Setup: config persistence, migration, secret handling, and rollback #3410).
• Resume must not re-ask already-verified steps unless the underlying config changed since they were written.
• If a step errors or panics, the shell returns to the step list with that step marked failed/needs_action — never a dead-end.

Problem

A full CodeWhale setup flow needs a reusable wizard shell before individual setup steps can be implemented cleanly. The shell should work for first-run onboarding and for existing users who run /setup later.

Scope

• Add a setup wizard overlay/controller with step list, current step, completed/skipped/failed status, and summary state.
• Add a /setup slash command or equivalent TUI entry point that opens the wizard without requiring a restart.
• Decide CLI relationship with codewhale setup: reuse the same state model where practical, or document why CLI and TUI differ.
• Support navigation: next, back, skip, retry, save/apply, cancel, and exit-without-saving where relevant.
• Support resume of partial setup without re-asking completed steps unless config has changed.
• Add tests for navigation state, skip/resume, cancellation, and status summarization.

Definition of done

• Fresh install and existing-user setup both enter the same setup state model.
• /setup opens the wizard from a normal TUI session.
• Steps can be added without each one inventing navigation and persistence behavior.
• Wizard shell tests cover step transitions, skip, retry, resume, cancel, and summary states.

Localization / UX

• All navigation chrome (titles, next/back/skip/retry/done, status labels) uses localization IDs, not hardcoded English; the first-run language choice applies immediately.
• Status words map 1:1 to the v0.8.67 Setup: audit current setup/onboarding surfaces and define the unified setup state model #3403 status enum, so reports and localized labels share one vocabulary.

Doctor / docs expectations

• codewhale doctor can report overall setup readiness and which steps are skipped/needs_action by reading the same state.
• Docs (v0.8.67 Docs: constitution-first setup, localization, screenshots, and copy #3412) describe /setup, resume, and skip semantics.

Acceptance criteria

• Fresh install and existing users enter the same state model and wizard.
• /setup opens the wizard from a normal TUI session without a restart.
• Navigation supports next, back, skip, retry, apply, and cancel; cancel changes nothing.
• Partial setup can be interrupted and resumed with step state preserved; verified steps are not re-asked.
• A new step can be added by implementing the step trait, without touching navigation or persistence.
• Tests cover step transitions, skip, retry, resume, cancel, and summary states.

Related

• Epic: v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402 · State model: v0.8.67 Setup: audit current setup/onboarding surfaces and define the unified setup state model #3403 · End-to-end onboarding contract: v0.8.67 Setup: make first-run onboarding feel like starting CodeWhale, not editing config #3792
• Persistence/rollback: v0.8.67 Setup: config persistence, migration, secret handling, and rollback #3410 · Verification/doctor: v0.8.67 Setup: verification, doctor integration, setup report, and release QA matrix #3411 · Docs/copy: v0.8.67 Docs: constitution-first setup, localization, screenshots, and copy #3412