v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution

[Hmbown]

Scope update (2026-06-29)

v0.8.67 is the setup wizard plus user-global constitution lane. The release should make CodeWhale feel coherent on first launch and after update, with /constitution as the main personalization surface.

Future setup surfaces have moved out of this lane:

• Hotbar opt-in setup belongs to v0.8.68.
• Tools/MCP/skills/plugins setup belongs to later setup/tooling lanes unless only mentioned as existing commands.
• Remote/mobile/chat bridge setup belongs to v0.8.69+ remote/workbench work.

Product north star

Starting CodeWhale should feel like starting a serious workbench, not editing a pile of config files. The first-run happy path should get a new user to one verified prompt with:

1. language selected,
2. provider/key or local runtime selected,
3. default model selected and checked,
4. runtime safety posture reviewed as explicit config,
5. user-global constitution created, accepted, or deferred through /constitution,
6. ready summary that says what is configured and what can be changed later.

For users updating to v0.8.67, the same release introduces a localized constitution checkpoint. Choosing the bundled/default constitution is a valid completion path; customization is encouraged but not forced.

Key design decisions

• Global first: focus on user-global constitution. Repo-local .codewhale/constitution.json already exists and can evolve later; most ordinary repo guidance belongs in AGENTS.md.
• Structured policy, rendered prose: setup writes structured user-global policy under $CODEWHALE_HOME and renders it into prose for the model.
• Full Markdown override is advanced: $CODEWHALE_HOME/prompts/constitution.md plus CODEWHALE_ALLOW_BASE_PROMPT_OVERRIDE=1 remains an expert escape hatch, not the normal setup output.
• No model-facing indirection: the model receives final prose blocks; it is not asked to chase JSON-to-Markdown or Markdown-to-JSON references.
• Separate runtime controls: constitution text may express preferences, but applying default mode, approvals, sandbox, network, or trust remains an explicit config action owned by v0.8.67 Setup support: runtime posture card with constitution boundary #3406.
• Remove WHALE.md: v0.8.67 should stop treating WHALE.md as an active instruction/context surface. Track cleanup in v0.8.67 Setup: remove deprecated WHALE.md discovery and docs surface #3798.

First-run spine

0. Welcome / first-run vs update detection.
1. Language first, so setup and constitution screens are localized before the user writes standing law.
2. Provider + key or local runtime selection.
3. Default model + quick connectivity check where applicable.
4. Runtime safety posture, owned by v0.8.67 Setup support: runtime posture card with constitution boundary #3406.
5. Constitution creation/checkpoint: guided structured answers, optional free prose, live rendered preview.
6. Ready summary with /constitution as the primary reopen/edit surface.

Setup surface audit (2026-06-30 live)

This matrix is the #3403 closeout map against claude/v0.8.67-constitution-setup-174rj9 / PR #3861 after the foundation commits. The implementation rule for the rest of v0.8.67 is: all first-run, update-checkpoint, /setup, /constitution, doctor, and docs surfaces read/write SetupState from crates/config/src/setup_state.rs and render user-global constitution prose through UserConstitution::render_block() from crates/config/src/user_constitution.rs. Do not create a second readiness model in the TUI.

Existing setup/onboarding surfaces

Surface	Current code/docs	Classification	v0.8.67 action
TUI first-run onboarding (crates/tui/src/tui/onboarding/*, App::initial_onboarding_state, tui/ui.rs key handling)	Marker-based Welcome -> Language -> ApiKey -> TrustDirectory -> Tips, writes .onboarded, locale settings, API key, and workspace trust.	Partial / reusable	Reuse language picker, localization patterns, key masking/validation, trust writer, and modal/event plumbing. Replace the product spine and persistence with SetupState; welcome and tips copy are stale because they center API key/trust, not constitution.
Existing-user trust/API-key gates	Returning users can be dropped into API-key or workspace-trust gates even after .onboarded.	Reusable support behavior	Derive inherited state from existing config/trust facts. Keep noninteractive/headless from hanging; unresolved readiness becomes needs_action or deferred, not a blocking fresh install.
codewhale setup / codewhale-tui setup (main.rs::run_setup)	Scaffolds MCP, skills, tools, plugins; has --status and --clean; prints DeepSeek Setup; no constitution state.	Partial / stale for this lane	Keep as legacy utility/scaffold surface. /setup wizard shell (#3404) should be constitution-first and state-backed; tools/MCP/plugins are SetupStep::ToolsMcp optional/deferred for v0.8.67. Rename/copy polish belongs with #3412.
setup --status and doctor setup guidance	Reports API key source, model, MCP/skills/tools/plugins, sandbox, .env, and legacy state.	Partial / reusable	Reuse as #3411 reporting substrate, but add setup-state summary and secret-redacted setup report. Current copy mentions codewhale setup --migrate, but no SetupArgs flag exists on this branch; treat that as stale/conflicting copy.
/provider, provider picker, /model surfaces	Switch/view provider/model and can show existing route state. Full configured-provider route manager work belongs to #3830.	Reusable support card	#3405 should read the effective route and write only SetupStep::ProviderModel (verified, needs_action, deferred, safe result). Do not pull the full provider manager into the wizard.
/config and config audit/runtime controls	Can inspect and persist approval/sandbox/shell/default-mode settings.	Reusable authority surface	#3406 runtime posture card reads effective config and writes SetupStep::TrustSandbox plus runtime_posture_source. Constitution autonomy remains guidance only and never mutates these controls.
/mcp, /skills, tools/plugins setup	Existing commands and docs are useful, but tooling setup is explicitly outside v0.8.67 except status rows.	Reusable / deferred	Show compact “available later” status if needed; record SetupStep::ToolsMcp as optional or deferred. Do not block ready on MCP/tools/plugins.
Hotbar setup (/hotbar, tui/hotbar/setup.rs) and feature-intro nudge	Real UI exists and post-onboarding copy currently points users to Hotbar/Fleet.	Superseded for v0.8.67 first-run	Hotbar opt-in setup is v0.8.68. Do not include it in the v0.8.67 wizard except as deferred SetupStep::Hotbar. First-run summary should point to /constitution, not Hotbar/Fleet as the main next step.
Fleet setup (/fleet setup, fleet views)	Real loadout UI exists, unrelated to constitution-first setup.	Deferred / unrelated	Keep out of this lane except avoiding contradictory copy in final report/docs.
remote_setup/* and docs/rfcs/REMOTE_SETUP_DESIGN.md	Generate-only cloud/chat deploy bundle; RFC now points toward local/Tailscale-first remote lanes.	Superseded for v0.8.67 / deferred to v0.8.69+	Do not wire into constitution setup. Track as SetupStep::RemoteRuntime optional/deferred only if surfaced in a status report.
Repo-local constitution (.codewhale/constitution.json) and project-context renderer	Existing repo constitution is a separate local-law layer and already has prompt-rendering precedent.	Reusable pattern	Mirror its separate system-block pattern for user-global constitution. User-global $CODEWHALE_HOME/constitution.json is not repo-local .codewhale/constitution.json.
Expert base-prompt override ($CODEWHALE_HOME/prompts/constitution.md + CODEWHALE_ALLOW_BASE_PROMPT_OVERRIDE=1)	Documented advanced escape hatch for replacing the base prompt segment.	Reusable advanced path	/constitution should detect/report it as ConstitutionChoice::ExpertOverride / ConstitutionSource::ExpertOverride, not guide normal users into it.
WHALE.md docs/discovery	Docs still describe deprecated reading below AGENTS.md.	Stale / pending removal	#3798 owns removal and docs cleanup. v0.8.67 setup copy should not recommend WHALE.md.
Legacy .deepseek paths and trust markers	Still supported for migration/fallback, including onboarding marker and trust marker checks.	Reusable migration fallback with hazards	Preserve for inherited-state derivation and compatibility; do not create new .deepseek state from v0.8.67 setup. Audit/doc stale references under #3412/#3798.

Step/state ownership for v0.8.67

Product step	SetupState fields	Owner issue(s)	Ready semantics
Welcome / restore / inherited-state detection	SetupState::load(), SetupState::derive_inherited(InheritedConfigFacts), inherited	#3404, #3411	Missing/corrupt state falls back to inherited facts; existing users are not treated as broken fresh installs.
Language	steps[Language], constitution_language	#3404, #3793, #3794	First-run needs Language verified. Update checkpoint can inherit language but should still localize the checkpoint UI or use tested fallback copy.
Provider/model readiness card	steps[ProviderModel].status/result/version	#3405	verified is ideal; needs_action still reaches ready with an actionable summary; deferred is allowed where the user chooses bundled/default constitution and proceeds.
Runtime posture card	steps[TrustSandbox], runtime_posture_source	#3406, #3736	First-run needs inherited or confirmed posture. Constitution autonomy preference may recommend posture but never applies it. No v0.8.67 “Auto” mode.
Constitution choice / guided creator / review	constitution_choice, constitution_source, constitution_validity, constitution_preview_hash, constitution_preview_version, steps[Constitution]	#3793, #3806	Any explicit choice (bundled, guided custom, expert override, or deferred) satisfies first-run; empty/unreadable custom files become reportable validity, not silent success.
Update checkpoint	constitution_checkpoint_completed_for, constitution_choice, constitution_language	#3794	Update readiness for 0.8.67 is the checkpoint version match. Choosing bundled/default is a valid completion. Noninteractive/headless defers and proceeds with bundled law.
Ready summary / doctor / QA	steps[*], derived first_run_ready(), update_ready(version), redacted setup report	#3411, #3412	Report contains no secrets and names skipped/deferred/needs-action steps. It should point users back to /constitution as the primary personalization surface.
Tools/MCP, Hotbar, RemoteRuntime	steps[ToolsMcp], steps[Hotbar], steps[RemoteRuntime]	Later lanes plus #3411 status rows	Optional/deferred in v0.8.67; never blocks first-run/update ready.

Dependency order now

1. Keep PR feat: v0.8.67 constitution-first setup — model-assisted onboarding, runtime posture, cleanup #3861 foundation green: persistence, setup_state, and user_constitution are the shared vocabulary.
2. Wire UserConstitution::render_block() as a separate system block after the byte-stable base/tool-catalog head, mirroring repo-constitution block assembly.
3. Build v0.8.67 Setup: implement the setup wizard shell, navigation, resume, and /setup entry point #3404/v0.8.67 Setup: require a localized constitution checkpoint after update #3794 wizard/checkpoint shell on SetupState; it may start compact, but it must not write a second marker-only setup model.
4. Build v0.8.67 Setup: make /constitution the primary constitution management surface #3806 /constitution as the reopen/edit/report surface for the same state and structured file.
5. Add v0.8.67 Setup support: provider/model readiness card for constitution-first setup #3405 provider/model and v0.8.67 Setup support: runtime posture card with constitution boundary #3406/v0.8.67: Separate work mode from approval policy before any Auto loop #3736 runtime posture as compact readiness cards, not full managers.
6. Add v0.8.67 Setup: verification, doctor integration, setup report, and release QA matrix #3411 doctor/report/QA and v0.8.67 Docs: constitution-first setup, localization, screenshots, and copy #3412 docs/localization once the runtime surfaces exist.
7. Treat chore(cleanup): remove dormant TUI tab collaboration subsystem #3838-chore(cleanup): trim unused model catalog refresh/write helpers #3842 cleanup and the hotbar/agent lane (v0.8.67: Ship Hotbar slot editor v1 with route-switch actions #3831/v0.8.67: Restore web_search/fetch_url/web.run to explore sub-agent catalogs #3834/v0.8.67: Add parent/child tool-catalog parity guardrail and restore patch/FIM parity for implementers #3836/v0.8.67: Make Agents sidebar reconcile sub-agent completion/cancellation in real time #3837/v0.8.67: Ship ModalShell v1 for release-blocking menus #3829) as parallel release work, not prerequisites for constitution-first setup.

Current contradictions / follow-up hooks

• crates/tui/src/tui/onboarding/welcome.rs now centers constitution-first setup: language, provider readiness, CodeWhale constitution, bundled/default completion, and /constitution return path.
• App::feature_intro_content() now centers setup readiness and /constitution; Hotbar/Fleet remain visible only as optional later surfaces (4235b665e).
• run_setup and run_setup_status now use CodeWhale Setup/Status headers (78e6aff1a).
• Doctor legacy-state copy no longer points to nonexistent codewhale setup --migrate; it now tells users to start CodeWhale once to trigger safe migration where available, then rerun codewhale doctor (78e6aff1a).
• Active docs now describe WHALE.md as ignored/deprecated migration input, not a read instruction surface; remaining WHALE.md mentions are migration warnings, tests, or unrelated CodeWhale naming.

Child issues

• v0.8.67 Setup: audit current setup/onboarding surfaces and define the unified setup state model #3403 Audit current setup/onboarding surfaces and define the unified setup state model
• v0.8.67 Setup: implement the setup wizard shell, navigation, resume, and /setup entry point #3404 Implement the setup wizard shell, navigation, resume, and /setup entry point
• v0.8.67 Setup support: provider/model readiness card for constitution-first setup #3405 Provider/model setup step: catalog, auth, model picker, and live health checks
• v0.8.67 Setup support: runtime posture card with constitution boundary #3406 Trust, approvals, sandbox, network, and privacy setup step
• v0.8.67 Setup: config persistence, migration, secret handling, and rollback #3410 Config persistence, migration, secret handling, and rollback for setup changes
• v0.8.67 Setup: verification, doctor integration, setup report, and release QA matrix #3411 Setup verification, doctor integration, and release QA matrix
• v0.8.67 Docs: constitution-first setup, localization, screenshots, and copy #3412 Docs, screenshots, localization, and constitution copy refresh
• v0.8.67 Setup: make first-run onboarding feel like starting CodeWhale, not editing config #3792 Make first-run onboarding feel like starting CodeWhale, not editing config
• v0.8.67 Setup: build a guided localized constitution creator, not a blank prompt editor #3793 Guided global constitution creator, not a blank prompt editor
• v0.8.67 Setup: require a localized constitution checkpoint after update #3794 Required localized constitution checkpoint after update
• v0.8.67 Setup: remove deprecated WHALE.md discovery and docs surface #3798 Remove deprecated WHALE.md discovery and docs surface
• v0.8.67 Setup: make /constitution the primary constitution management surface #3806 Make /constitution the primary constitution management surface
• v0.8.67 Docs: sync provider/model docs with Xiaomi MiMo UltraSpeed and Token Plan #3810 Sync provider/model docs with Xiaomi MiMo UltraSpeed and Token Plan
• v0.8.67 Docs: center /constitution and user-global constitution in the docs map #3811 Center /constitution and user-global constitution in the docs map

Definition of done

• A fresh user can complete setup without leaving CodeWhale except where an external provider token page is unavoidable.
• The minimum first-run path succeeds with one provider/key or local runtime, one default model, and one explicit constitution choice.
• Updating users complete the v0.8.67 constitution checkpoint once; choosing bundled/default is valid.
• Existing users can run /setup and /constitution without losing current config or sessions.
• Each setup step can be skipped, resumed, and verified.
• The complete onboarding path is covered by automated tests or a documented release QA script from a clean CODEWHALE_HOME.
• The global constitution creator uses guided questions, bounded free prose, preview, enable/disable, and reporting.
• The update checkpoint and constitution builder are localized across shipped setup languages or have documented, tested fallback behavior.
• The final setup report contains no secrets.
• Docs, doctor output, and release notes match the wizard behavior.

Non-goals for v0.8.67

• Not Hotbar setup. Hotbar is hidden by default in v0.8.66 and opt-in setup moves to v0.8.68.
• Not tools/MCP/skills/plugins setup beyond preserving existing commands and avoiding contradictory docs.
• Not remote/mobile/chat bridge setup or provisioning.
• Not a general settings REPL or replacement for /config, /provider, and related commands.
• Not re-translating the bundled prompts/constitution.md; setup UI and generated user constitution can be localized, while the bundled global floor remains the canonical source.
• Not auto-installing untrusted tools or auto-running server commands.
• Not rewriting existing user config, sessions, project overlays, or repo .codewhale/constitution.json.

Safe fallback

• Any step can be skipped; skipped/deferred steps surface in the report and never block the TUI from opening.
• If the wizard is interrupted or a step fails, existing config is left intact.
• Noninteractive/headless launches never hang on the interactive wizard; they fall back to bundled defaults and emit a documented setup-incomplete signal.
• First-run with a key that fails validation still reaches the ready screen with a needs-action provider status and an actionable next step.
• If the update constitution checkpoint cannot render interactively, defer to the bundled constitution and record checkpoint_deferred rather than blocking work.