v0.8.69: Promote existing repo docs into full website documentation with parity checks

[Hmbown]

Why this matters

The repo already has substantial documentation, but the website only exposes a compressed docs page and links back to GitHub for depth. That leaves codewhale.net behind the actual project: a user cannot learn CodeWhale's current runtime, provider, safety, MCP, sub-agent, fleet, WhaleFlow, install, troubleshooting, and contribution story without jumping through raw repository docs.

A professional coding-agent site should make the docs first-class while preserving the repo docs as source material or a synchronized source of truth.

Current behavior

• The website Docs page has ten top-level anchor sections (web/app/[locale]/docs/page.tsx:16): Constitution, Modes, Tools, Approval & Sandbox, Configuration, MCP, Skills, Providers, Fin, Shortcuts.
• The README points to a much broader docs set (README.md:238 through README.md:250): Guide, Install, Configuration, Providers, Modes, Sub-agents, Architecture, Fleet, WhaleFlow, MCP, Runtime API, Model Lab, Keybindings, Sandbox, Accessibility, Docker, Memory, and more.
• The docs page intro sends users to docs/ARCHITECTURE.md for the full architecture walk-through instead of surfacing that content in the site (web/app/[locale]/docs/page.tsx:60).
• The repo contains many current docs files under docs/, including docs/GUIDE.md, docs/INSTALL.md, docs/PROVIDERS.md, docs/SUBAGENTS.md, docs/TOOL_SURFACE.md, docs/FLEET.md, docs/WHALEFLOW_AUTHORING.md, and docs/RUNTIME_API.md.

Desired behavior

1. Define a docs source-of-truth strategy: import/transform repo Markdown, curate MDX pages, or maintain paired pages with drift checks.
2. Expose the major docs areas on the website with stable routes and navigation.
3. Add parity checks so website docs do not keep advertising old APIs or miss new first-class surfaces.
4. Preserve multilingual support: at minimum, English and Chinese docs must stay aligned; additional locales should have a documented fallback/translation state.
5. Keep GitHub links available for contributors, but make the website the best entry point for users.

Repro or evidence

nl -ba README.md | sed -n '235,252p'
nl -ba 'web/app/[locale]/docs/page.tsx' | sed -n '15,39p;42,66p'
find docs -maxdepth 1 -type f -name '*.md' | sort

The README promises a broader docs surface than the site route currently provides.

Acceptance criteria

• A docs map lists every first-class website docs page and the corresponding repo source/doc owner.
• Website docs include or link through structured routes for install, user guide, configuration, providers/models, modes, tools, sub-agents, MCP, skills, hooks, sandbox/approvals, runtime API, fleet/WhaleFlow, troubleshooting, and contribution.
• The website no longer relies on a single monolithic Docs page as the only product documentation surface.
• A drift/parity check catches stale website docs for at least version, tool names, provider list, and key command/install snippets.
• English and Chinese routes are aligned, with a documented fallback for not-yet-translated pages.
• cd web && npm run lint && npm run test && npm run build passes.

Related

• v0.8.69: Make codewhale.net feel like a mature product site #3413 broader website/docs hub.
• v0.8.69: Remove stale website references to retired sub-agent lifecycle tools #3414 stale sub-agent lifecycle copy.
• v0.8.69: Add a website fact-drift gate for version, providers, and tool inventory #3415 generated fact drift gate.
• v0.8.59: Define README + website localization matrix, source text, and drift checks #3090 localization matrix/source text/drift checks.