Problem

codewhale.net should read as a mature product surface: polished, trustworthy, well-structured, and clear enough that new users, serious adopters, contributors, and partners understand the project without digging through repository docs. The homepage redesign (#3762, landed 2026-06-29) moved the site to a docs-portal presentation, and v0.9.1 carried the truthful-roadmap slice (#3418). What remains is the rest of the product-led information architecture: trust/security and provenance surfaces, real documentation depth on-site instead of links out to GitHub markdown, and a deliberate support/contact story — presentation quality and IA, not overclaiming.

Current evidence

Landed (verify before extending):

• Primary nav is slim and product-led: Docs, Install, Community, Contribute + GitHub, theme toggle, locale switcher (web/components/nav.tsx:9-21).
• Homepage is a portal: hero + quickstart, "Start here" topics, documentation index, community section, with facts (version/providers/license) injected from the derived-facts pipeline (web/app/[locale]/page.tsx, 197 lines; web/lib/facts.ts, web/scripts/derive-facts.mjs runs on prebuild).
• /docs is a hub with search over a canonical topic registry: DocsSearch (web/app/[locale]/docs/page.tsx), DOC_TOPICS in web/lib/docs-map.ts (15 topics, categorized getting-started/core-concepts/reference/extending/operations, each mapped to its repo source file).
• Drift gates exist: web/scripts/check-docs.mjs (every topic's repo source must exist; version/command parity) and web/scripts/check-facts.mjs — the anti-stale-facts machinery v0.8.69: Remove stale website references to retired sub-agent lifecycle tools #3414/v0.8.69: Add a website fact-drift gate for version, providers, and tool inventory #3415 asked for.
• Footer already carries trust primitives: Product links (Docs/Install/Models/Runtime/App preview), Project links (GitHub/Issues/Contribute/MIT license), a provenance line ("Canonical source and releases: github.com/Hmbown/CodeWhale"), mirror links (CNB, npmmirror, Gitee behind GITEE_ENABLED), and a Security mailto (web/components/footer.tsx).
• Security headers + locale routing in web/middleware.ts; locale lifecycle model (shipped/partial/planned/deferred) in web/lib/i18n/config.ts; a dedicated redirect worker under web/redirect/.
• Routes today: home, install, docs (+ docs/constitution, docs/modes, docs/tools), models, runtime, community, contribute, roadmap, faq, feed, digest, constitution, admin (web/app/[locale]/).

Gaps (the residual this issue now tracks):

• No trust/security page: the footer's Security entry is a mailto:; SECURITY.md (repo root), sandbox/permissions material (docs/SANDBOX.md), and mirror/provenance copy (docs/CNB_MIRROR.md) have no website surface.
• Docs depth is mostly off-site: only 3 of 15 DOC_TOPICS have on-site pages (constitution, modes, tools; install/providers route to /install and /models); the other 10 render as external ↗ links to GitHub markdown (topicIsExternal, web/app/[locale]/page.tsx:23-34).
• Registry blind spots: DOC_TOPICS has no skills topic (repo ships docs/skills/) and no safety/security topic.
• Support/contact surface is undefined beyond the Security mailto and an unlinked FAQ route; support expectations (what users can expect, where to ask) are stated nowhere.
• No published site map naming the target product/docs/trust/community/roadmap/support/provenance surfaces.

Scope

1. Write the target site map (product, install, docs, trust/security, community, roadmap, contact/support, provenance) and land it with the first PR so later slices cite it.
2. Build the trust/security surface: license, security model and reporting path (from SECURITY.md), local-first behavior, sandbox/permissions summary, official-source provenance and release/install verification, provider neutrality, support expectations. Link it from footer (replacing the bare mailto) and, if the site map says so, from nav.
3. Extend DOC_TOPICS with the missing topics (at minimum skills and safety/security) and keep check-docs green.
4. Bring the highest-traffic external topics on-site following the existing pattern (web/app/[locale]/docs/tools/page.tsx + web/components/docs-sidebar.tsx), rather than ↗ GitHub links; keep repo markdown canonical and let the drift gates enforce parity.
5. Define the support/contact story: FAQ placement, issue/discussion entry points, and what response expectations are honest for a community project.
6. Keep community and multilingual content visible as proof (portal community section, /community) without letting it crowd the product hierarchy; feed locale expansion through the i18n/config.ts lifecycle instead of duplicating v0.8.59: Define README + website localization matrix, source text, and drift checks #3090-v0.9.2: Ship Korean, Spanish, and Brazilian Portuguese website locales (READMEs landed) #3093 here.
7. Preserve URLs: existing routes continue to resolve or redirect (middleware + web/redirect/).

Phases

1. Phase 1 — site map + trust/provenance surface. Scope 1, 2, 5. Mostly copy and IA; sources exist in SECURITY.md, README.md, docs/CNB_MIRROR.md, docs/SANDBOX.md. Coordinates with v0.8.69: Add official-site and mirror provenance copy to codewhale.net #3421 (trust/provenance and mirror copy).
   • Done when: a trust/security page ships, footer/nav link it, and the site map is committed.
2. Phase 2 — docs depth on-site. Scope 3, 4. Registry-first: extend DOC_TOPICS, then convert topics to pages in priority order (guide, configuration, providers, subagents, mcp, skills, troubleshooting ahead of the rest).
   • Done when: the acceptance topic list resolves to structured on-site navigation, and npm run check:docs still passes.
3. Phase 3 — product-surface polish. Scope 6, 7 plus the runtime/integrations product surface fed by v0.8.69: Add a public Runtime API and integrations page to codewhale.net #3419; verify no stale facts can render (v0.8.69: Remove stale website references to retired sub-agent lifecycle tools #3414/v0.8.69: Add a website fact-drift gate for version, providers, and tool inventory #3415 pipeline covers new pages too).
   • Done when: nav/footer/site map match, old URLs redirect, and drift gates cover every new surface.

Key files

• web/components/nav.tsx
• web/components/footer.tsx
• web/app/[locale]/page.tsx
• web/app/[locale]/docs/page.tsx
• web/lib/docs-map.ts
• web/components/docs-sidebar.tsx
• web/components/docs-search.tsx
• web/scripts/check-docs.mjs
• web/lib/i18n/config.ts
• web/middleware.ts
• SECURITY.md
• docs/CNB_MIRROR.md

Acceptance criteria

• A committed site map names the product, docs, trust, community, roadmap, contact/support, and provenance surfaces.
• A trust/security page presents license, security model + reporting path, local-first behavior, provenance/mirrors, release/install verification, provider neutrality, and support expectations — without overclaiming.
• Navigation/footer include trust, contact/support, docs, provenance, GitHub, and community links.
• /docs offers structured on-site topic navigation covering install, usage, config, providers/models, tools, sub-agents, MCP, skills, hooks, safety, troubleshooting, and contribution paths (registry-backed, not ad-hoc pages).
• Community and multilingual content remain visible but do not crowd the product hierarchy.
• Existing routes continue to resolve or redirect.
• Drift gates stay green: every topic maps to a real repo source; no stale version/provider facts render.

Verification

cd web && npm run lint && npm run test && npm run build
cd web && npm run check:docs && npm run check:facts

Out of scope

• Runtime/TUI changes (this is the website only).
• The roadmap-truthfulness slice (v0.9.1: Reconcile the website roadmap with retired web UI/share-link plans and Workrooms #3418, carried in v0.9.1).
• New locale rollouts themselves (v0.8.59: Define README + website localization matrix, source text, and drift checks #3090-v0.9.2: Ship Korean, Spanish, and Brazilian Portuguese website locales (READMEs landed) #3093 own that; this issue only keeps the IA ready for them).
• Marketing claims that outrun the product.

Related

• feat(web): redesign homepage with trust strip, GitHub nav link, and mirror footer (#3413) #3762 (merged) — homepage/portal redesign this builds on.
• v0.9.1: Reconcile the website roadmap with retired web UI/share-link plans and Workrooms #3418 — truthful roadmap slice (v0.9.1).
• v0.8.69: Add a public Runtime API and integrations page to codewhale.net #3419 — runtime/integrations product surface (feeds Phase 3).
• v0.8.69: Add official-site and mirror provenance copy to codewhale.net #3421 — trust/provenance and mirror copy (feeds Phase 1).
• v0.8.69: Remove stale website references to retired sub-agent lifecycle tools #3414, v0.8.69: Add a website fact-drift gate for version, providers, and tool inventory #3415 — stale-fact protections; the facts/check-docs pipeline is their landing.
• v0.8.59: Define README + website localization matrix, source text, and drift checks #3090, v0.9.2: Bring the website to parity with existing Japanese and Vietnamese README locales #3091, v0.9.2: Add Russian README and website localization with Cyrillic QA #3092, v0.9.2: Ship Korean, Spanish, and Brazilian Portuguese website locales (READMEs landed) #3093 — website/README localization expansion; feed the multilingual plan, not duplicated here.

Triage note: body restructured for agent execution on 2026-07-18; retarget comment folded in; stale nav/homepage/docs evidence replaced with the current portal-era anchors. Original wording preserved in edit history.