feat(docs): mermaid theme-value guard + brand-source docs + README quickstart

- checkDiagrams: a `%%{init` block must now carry the brand's actual color values
  (ember #f26430 + warm-black #171310 from brand.json), not merely a theme directive
  — a diagram can no longer declare a theme yet render off-brand. New docs_check test
  covers both the branded-pass and missing-values-flagged cases.
- ARCHITECTURE.md: document brand.json.colors as the single color source both public
  pages derive from, and the parity/diagram guards that keep it honest.
- README: lead with a "Start in 60 seconds" block so the first screen is actionable,
  linking to the full quickstart and command reference.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019PXuKmJp92Gdo2FudNjSx2

Author: claude

ARCHITECTURE.md

@@ -240,9 +240,14 @@ every intra-repo Markdown anchor (`#x` and `path.md#x`) against the target's rea
 (GitHub-exact slugs — em-dashes yield `--`, never collapsed), killing the dead-anchor class;
 and `checkRoadmap` fails when the ROADMAP's "Now" marker trails the shipped `package.json`
 version. The two public pages
-(`landing/index.html` + the `build-pages.mjs` status page) share one set of design tokens,
-enforced for parity (plus non-empty changes list, no phantom webfont) by
-`test/pages.test.js` — so neither the docs' numbers nor the site's look can silently drift.
+(`landing/index.html` + the `build-pages.mjs` status page) derive from ONE color source —
+`brand.json.colors` (full dark + light palettes), emitted as CSS by `src/brand.js`
+(`rootTokensCss()`). `test/pages.test.js` enforces full-palette parity: every hex in
+`brand.json` must appear on both surfaces, so the palette can't fork into "two palettes
+claiming to be one" again (plus non-empty changes list, no phantom webfont, present
+social/favicon metadata). `checkDiagrams` extends the same single-source rule to Mermaid —
+every `%%{init` theme must carry the brand's ember + warm-black hexes — so neither the docs'
+numbers nor the site's look can silently drift.
 
 **Auto-release (`.github/workflows/bump.yml` + `scripts/bump.mjs`).** A push to `master`
 runs `bump.mjs auto`: it releases only when a `feat`/`fix`/`perf`/breaking commit landed

CHANGELOG.md

@@ -45,6 +45,11 @@ design` passes spacing-scale, radius-levels, and shadow-levels with a healthy
   block, with a 256-color fallback when the terminal can't do truecolor. New
   `test/statusline.test.js` smoke-tests the segments, the exact truecolor hexes, the
   fallback, and graceful degradation on minimal input.
+- **Mermaid theme-value guard.** `forge docs check`'s `checkDiagrams` now verifies each
+  `%%{init` block carries the brand's actual color values (ember + warm-black from
+  `brand.json`), not just that a theme directive is present — a diagram can no longer
+  declare a theme and still render off-brand. README leads with a `Start in 60 seconds`
+  block, and `ARCHITECTURE.md` documents `brand.json` as the single color source.
 
 ### Fixed
 

README.md

@@ -26,8 +26,21 @@ delivers them into every tool you use.
 > **Status: beta.** The core (`init`, `sync`, `substrate`, `impact`, `ledger`, guards) is
 > tested and in daily use; some flags may change before `1.0`.
 
+## Start in 60 seconds
+
+```bash
+npm install -g @codewithjuber/forgekit   # or: npm install -g github:CodeWithJuber/forgekit
+forge init                               # emit every AI tool's native config from one source
+forge doctor                             # verify providers, hooks, and MCP wiring
+```
+
+That's it — your agents now share one source of truth. The
+[full quickstart](#60-second-quickstart) walks through the loop; [Commands](#commands)
+lists everything `forge` can do.
+
 ## Contents
 
+- [Start in 60 seconds](#start-in-60-seconds)
 - [The problem](#the-problem)
 - [How it works — the loop](#how-it-works--the-loop)
 - [What you get](#what-you-get)

src/docs_check.js

@@ -200,6 +200,24 @@ function checkDiagrams(root, issues) {
           severity: "error",
           detail: `${rel}: a mermaid diagram has no branded \`%%{init\` theme — it renders in Mermaid's off-brand default`,
         });
+      } else {
+        // Presence of `%%{init` isn't enough — the theme must carry the actual brand
+        // VALUES from the single color source (brand.json.colors.dark), or a diagram can
+        // declare a theme and still render in off-brand colors. Require the load-bearing
+        // identity hexes: the ember accent and the warm-black canvas.
+        const dark = BRAND.colors?.dark ?? {};
+        for (const [role, hex] of [
+          ["ember accent (lineColor)", dark.brand],
+          ["warm-black canvas (tertiaryColor)", dark.bg],
+        ]) {
+          if (hex && !block.toLowerCase().includes(hex.toLowerCase())) {
+            issues.push({
+              check: "diagrams",
+              severity: "error",
+              detail: `${rel}: a mermaid \`%%{init\` theme is missing the brand ${role} \`${hex}\` — it declares a theme but not the brand.json colors`,
+            });
+          }
+        }
       }
       if (block.includes("\\n")) {
         issues.push({

test/docs_check.test.js

@@ -116,9 +116,13 @@ test("docsCheck: an undocumented MCP tool is flagged", () => {
   assert.ok(r.issues.some((i) => i.check === "mcp-tools" && i.detail.includes(TOOLS[0].name)));
 });
 
+// A theme that carries the actual brand color VALUES (ember #f26430 + warm-black
+// #171310), not just the `%%{init` directive.
+const BRAND_INIT =
+  "%%{init: {'theme':'base','themeVariables':{'primaryColor':'#201a15','lineColor':'#f26430','tertiaryColor':'#171310'}}}%%";
+
 test("docsCheck: a branded mermaid diagram with <br/> passes; diagrams is a checked dimension", () => {
-  const good =
-    "```mermaid\n%%{init: {'theme':'base'}}%%\nflowchart LR\n  A[\"a<br/>b\"] --> B[\"c\"]\n```\n";
+  const good = `\`\`\`mermaid\n${BRAND_INIT}\nflowchart LR\n  A["a<br/>b"] --> B["c"]\n\`\`\`\n`;
   const r = docsCheck({
     root: fixtureRoot((f) => ({
       ...f,
@@ -129,6 +133,20 @@ test("docsCheck: a branded mermaid diagram with <br/> passes; diagrams is a chec
   assert.ok(r.checked.includes("diagrams"));
 });
 
+test("docsCheck: a mermaid theme missing the brand color values is flagged", () => {
+  // Has `%%{init` but not the brand.json hexes — declares a theme, renders off-brand.
+  const bad = "```mermaid\n%%{init: {'theme':'base'}}%%\nflowchart LR\n  A --> B\n```\n";
+  const root = fixtureRoot((f) => ({
+    ...f,
+    "ARCHITECTURE.md": `${f["ARCHITECTURE.md"]}\n${bad}`,
+  }));
+  const r = docsCheck({ root });
+  assert.ok(
+    r.issues.some((i) => i.check === "diagrams" && /missing the brand/.test(i.detail)),
+    "a theme without the brand hexes is flagged",
+  );
+});
+
 test("docsCheck: an unstyled mermaid diagram (no branded theme) is flagged", () => {
   const bad = "```mermaid\nflowchart LR\n  A --> B\n```\n";
   const root = fixtureRoot((f) => ({