v0.8.67 Docs: constitution-first setup, localization, screenshots, and copy

[Hmbown]

Scope update (2026-06-29)

v0.8.67 is now the setup wizard plus custom constitution lane. Docs for Hotbar, tools/MCP/skills/plugins setup, and remote/mobile/chat bridge setup belong to later milestones unless they are mentioned only as existing commands or future follow-up.

This parent issue should keep the release docs focused on the first experience:

1. Welcome / first-run or update checkpoint.
2. Language choice.
3. Provider, key, default model, and live health check.
4. Runtime safety posture as explicit config, separate from constitution text.
5. /constitution and guided user-global constitution creation.
6. Ready summary and setup report.

Constitution docs direction

Docs and localized setup copy should teach this split clearly:

• Language is selected before constitution authoring so the setup screens and rendered constitution preview are in the chosen language.
• The chosen constitution language is not automatically a permanent response-language lock; per-turn/session language policy still applies unless the user explicitly chooses a language rule.
• Constitution captures standing model-facing guidance: purpose, values, verification expectations, escalation rules, communication style, privacy/memory stance, and bounded free prose.
• Runtime security controls are separate: default mode, approval policy, sandbox, network, and trust are v0.8.67 Setup support: runtime posture card with constitution boundary #3406 / /config settings. Constitution UI may suggest them but must not silently apply them.
• /constitution (v0.8.67 Setup: make /constitution the primary constitution management surface #3806) is the primary user-facing surface; /context report and doctor are audit/debug surfaces.
• AI-assisted drafting is optional; docs must describe deterministic guided setup as sufficient.

Constitution file map docs must explain

• crates/tui/src/prompts/constitution.md: bundled global Markdown Constitution, compiled into CodeWhale and normally always present.
• $CODEWHALE_HOME/constitution.json or implementation-equivalent structured file: user-global constitution produced by setup, validated as data, rendered to prose for the model.
• $CODEWHALE_HOME/prompts/constitution.md: advanced full-base-prompt override from exposed main prompt for broader use cases #3638; document as expert/escape-hatch behavior, not the default guided creator output.
• .codewhale/constitution.json: optional repo-local CodeWhale authority policy, separate from the global creator.
• AGENTS.md: ordinary repo working instructions.
• memory/handoff: lower-priority recalled state, not law.

Docs should remove WHALE.md from the active surface map. If mentioned at all, it should appear only in a finite migration note: move project instructions to AGENTS.md, and move CodeWhale-specific repo authority policy to .codewhale/constitution.json. Code removal is tracked in #3798.

Docs drift found during audit

• Provider/model docs have Xiaomi MiMo drift: direct code supports mimo-v2.5-pro-ultraspeed, but some config/docs/web facts surfaces do not list it. Child issue: v0.8.67 Docs: sync provider/model docs with Xiaomi MiMo UltraSpeed and Token Plan #3810.
• Constitution docs/web surfaces still emphasize repo-local constitution more than the new /constitution user-global setup flow. Child issue: v0.8.67 Docs: center /constitution and user-global constitution in the docs map #3811.
• This issue previously mentioned Hotbar handoff, tools setup, and remote/mobile setup as v0.8.67 scope. Those belong to v0.8.68/v0.8.69 after the milestone cleanup.

Scope

• Add setup wizard documentation to README, docs/GUIDE.md, docs/CONFIGURATION.md, and any setup/doctor docs that reference first-run or update behavior.
• Document /setup, codewhale setup, provider/model setup, safety posture setup, constitution checkpoint behavior, global constitution creator behavior, /constitution, and verification report behavior.
• Document the v0.8.67 update path: existing users must complete the constitution checkpoint once, and choosing bundled/default constitution is a valid completion path.
• Update localization strings for setup steps and ensure language selection affects the entire setup flow.
• Localize constitution checkpoint and creator copy: bundled/default, preset-generated, existing custom review, disable/restore bundled, global vs repo constitution, AGENTS.md vs constitution vs memory, validation/repair states, final report rows, and why the checkpoint appears after update.
• Capture screenshots or text snapshots for the main setup hub, provider step, safety step, constitution checkpoint, constitution creator preview, and final report.
• Remove or clearly mark stale .deepseek language where new ~/.codewhale paths should be primary, while preserving intentional compatibility notes.
• Add docs drift checks or tests where the project already has a pattern for generated command/config references.

Definition of done

• New users can follow docs or the wizard without hitting contradictory setup instructions.
• Existing users understand why v0.8.67 asks them to complete a constitution checkpoint and how to satisfy it without creating a custom constitution.
• Users understand that constitution preferences do not silently change runtime approval/sandbox/network settings.
• All user-visible setup, constitution checkpoint, and constitution creator strings are localizable or intentionally language-neutral.
• At least one non-English setup/checkpoint snapshot proves the flow does not render mostly in English.
• zh-Hans and zh-Hant have explicit coverage or documented fallback behavior for constitution checkpoint strings.
• Screenshots/snapshots match the shipped UI enough for release notes and future regression review.

Related

• Setup epic: v0.8.67 EPIC: Constitution-first setup wizard and user-global constitution #3402
• Provider/model setup: v0.8.67 Setup support: provider/model readiness card for constitution-first setup #3405
• Safety posture: v0.8.67 Setup support: runtime posture card with constitution boundary #3406
• Verification/report: v0.8.67 Setup: verification, doctor integration, setup report, and release QA matrix #3411
• First-run onboarding: v0.8.67 Setup: make first-run onboarding feel like starting CodeWhale, not editing config #3792
• Guided localized constitution creator: v0.8.67 Setup: build a guided localized constitution creator, not a blank prompt editor #3793
• Required update checkpoint: v0.8.67 Setup: require a localized constitution checkpoint after update #3794
• Remove WHALE.md: v0.8.67 Setup: remove deprecated WHALE.md discovery and docs surface #3798
• /constitution: v0.8.67 Setup: make /constitution the primary constitution management surface #3806
• Xiaomi/provider docs drift: v0.8.67 Docs: sync provider/model docs with Xiaomi MiMo UltraSpeed and Token Plan #3810
• Constitution docs map: v0.8.67 Docs: center /constitution and user-global constitution in the docs map #3811