v0.8.67 Setup: audit current setup/onboarding surfaces and define the unified setup state model

[Hmbown]

Product shape

This is the foundation issue for the whole v0.8.67 setup lane. The deliverable is not user-visible UI — it is (a) one accurate map of the setup/onboarding surfaces that already exist in the codebase, and (b) one shared setup state model that every other step (#3404–#3412) reads and writes. Done well, a future agent can implement any single step by reading this issue's state model plus that step's issue, without re-deriving what "configured", "skipped", "verified", or "ready" mean.

Proposed setup state model

A single persisted setup-state record under ~/.codewhale/ (exact path/section decided here, written via the #3410 persistence layer), keyed per lane/version. Each wizard step writes one entry:

• step — canonical step id: language, provider_model, trust_sandbox, tools_mcp, hotbar, remote_runtime, constitution, verification.
• status — not_started | recommended | optional | deferred | in_progress | verified | needs_action | failed | skipped.
• required — whether the lane blocks "ready" without it (first-run vs update differ).
• result — short safe summary string (provider name, model id, mode name, health) — never secrets.
• version — lane that last wrote it (e.g. "0.8.67"), so /setup, doctor, and the context report can show staleness.

Lane readiness rule (decided here, enforced by #3404/#3411):

• First-run "ready" requires language, provider_model (key verified), and trust_sandbox at verified, plus an explicit constitution choice. Everything else is optional/deferred.
• Update "ready" requires the constitution checkpoint complete for 0.8.67; everything else is inherited from existing config.

The exact serialization (a setup_state section in config vs a sidecar file) is this issue's decision, but it must survive config migration (#3410) and round-trip through comment-preserving writes.

Non-goals

• Not building wizard UI in this issue — that is v0.8.67 Setup: implement the setup wizard shell, navigation, resume, and /setup entry point #3404 onward. This issue lands the map + the state model + a status matrix on v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402.
• Not migrating users' existing config; only classifying migration hazards and linking follow-ups.
• Not removing any existing setup surface yet — classify each as reusable / partial / stale / superseded; deprecation is a later decision.

Problem

Before building the full setup wizard, we need a map of the setup surfaces that already exist and a state model that can unify them. CodeWhale already has language/API-key/trust onboarding, codewhale setup, codewhale remote-setup, /config, /provider, MCP setup, skills/plugins setup, Hotbar setup, doctor checks, and config migration behavior.

Scope

• Audit existing setup/onboarding code and docs, including:
  • crates/tui/src/tui/onboarding/*
  • crates/tui/src/main.rs Setup and onboarding paths
  • crates/tui/src/remote_setup/*
  • /config, /provider, /mcp, /skills, plugin commands
  • docs/CONFIGURATION.md, docs/GUIDE.md, docs/MCP.md, docs/rfcs/REMOTE_SETUP_DESIGN.md
• Define a setup state model: fresh install, partial setup, existing user, skipped step, failed step, verified step, and needs-attention step.
• Decide what is first-run only vs re-openable through /setup.
• Identify obsolete or conflicting copy, especially legacy .deepseek vs .codewhale language.
• Update v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402 with a status matrix and proposed step order.

Definition of done

• v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402 has a current setup surface map and step dependency order.
• Existing setup code is classified as reusable, partial, stale, or superseded.
• Every later setup issue can name the state it reads/writes.
• Contradictions and migration hazards are linked to follow-up issues.

Safe fallback

• The state model must default existing users to verified/inherited for surfaces they already configured, so an update never looks like a fresh, broken setup.
• An unreadable or missing setup-state record falls back to deriving status from existing config (key present? provider set? trust chosen?) rather than forcing the whole wizard.
• The audit is read-only analysis plus a v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402 matrix update — it must not change any user files.

Verifiable acceptance

• v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402 body contains a current setup-surface map and a step dependency order.
• Every existing setup surface is classified: reusable / partial / stale / superseded.
• The setup state model (step ids, status enum, required-vs-optional rule, version field) is written here or in a linked design note, and v0.8.67 Setup: implement the setup wizard shell, navigation, resume, and /setup entry point #3404–v0.8.67 Docs: constitution-first setup, localization, screenshots, and copy #3412 each name the state they read/write.
• First-run vs update readiness rules are explicit and testable.
• Contradictions and legacy .deepseek vs .codewhale migration hazards are listed with follow-up issue links.
• No user config is modified by the audit.

Related

• Epic / status-matrix target: v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402
• Wizard shell that consumes the state model: v0.8.67 Setup: implement the setup wizard shell, navigation, resume, and /setup entry point #3404
• Persistence of setup state: v0.8.67 Setup: config persistence, migration, secret handling, and rollback #3410
• Verification that reads statuses: v0.8.67 Setup: verification, doctor integration, setup report, and release QA matrix #3411