docs: full rewrite around one brain-first story, with professional diagrams

[CodeWithJuber]

What & why

The docs were factually correct (after #37) but hard to grok: five conflicting taglines split between "one config" and "one brain," a dense flat README, and plain default-mermaid diagrams. This is a full rewrite of the primary + community docs so a newcomer immediately understands what forgekit is and does — one positioning, one voice, one visual system.

The single through-line (brain-first): a large language model is stateless — one context window, wiped every call, with no memory, no foresight, no enforced guardrails. forgekit is the cognitive substrate that supplies exactly those three things; the cross-tool config compiler is how that brain gets delivered into 9 tools at once. "One config for every tool" is now the delivery mechanism, not the headline.

Highlights

• New showpiece hero (docs/assets/hero-dark.svg + hero-light.svg), embedded at the README top via the GitHub prefers-color-scheme <picture> pattern, drawn on the live forge dash palette so docs and product read as one system. Rendered and eyeballed in both light and dark.
• All six mermaid diagrams restyled with one shared brand theme block + a single ember accent node, so every diagram looks identical across README/ARCHITECTURE/ONBOARDING/GUIDE. ARCHITECTURE gains three new accurate diagrams: the pre-action gate pipeline, the PCM ledger + team-merge flow, and the reuse/context loop.
• README: brain-first hook, TOC + H3s for skimming, day-to-day value framed before the benchmark numbers, commands table regrouped and verified against src/cli.js — every documented forge <verb> is a real command.
• ARCHITECTURE: rebuilt around the four flows; fixes real accuracy drift — the code graph is .forge/atlas.json (not SQLite/.db), runtime is zero-dependency (serena/LSP moved to an honest "not shipped, exploring" note).
• ONBOARDING / GUIDE: brain-first intros, command-group indexes, restyled diagrams, one-liners verified against source.
• Community/meta: ACCESSIBILITY (stub → honest statement of what forge uicheck actually gates), examples/README (stub → two real copy-pasteable examples), ROADMAP / CONTRIBUTING / SUPPORT / RELEASING voice + accuracy pass (Node 20/22, not 18/20/22).
• One canonical tagline aligned across brand.json, package.json, CITATION.cff (and it already matches the landing page).

Checklist

• npm test passes — 438 pass / 0 fail / 2 skip (unchanged; the 2 skips are the Playwright-optional tier)
• npm run check passes (Biome) — clean on the touched JSON (package.json, brand.json)
• New public functions have a test — n/a, no source changes
• Conventional commit message (docs:)
• CHANGELOG.md updated under ## [Unreleased] — n/a, docs clarity pass; no shipped behavior change
• No new runtime dependency
• Substrate/docs updated if this changes substrate/router/gate/MCP — docs updated; no behavior change
• npm run typecheck passes

Risk & rollback

• Risk level: low (docs + two new SVG assets; no source/runtime change)
• Rollback plan: revert the commit

Extra checks

• Accuracy verified: every documented command exists in src/cli.js's COMMANDS; no surviving .forge/atlas.db/serena/LSP-as-shipped claims; all relative links and the new docs/assets/hero-*.svg paths resolve; both SVGs are well-formed and render in light + dark.

---

Generated by Claude Code