` is plausible and will inherit the homepage's 60px-padded, 5-column-grid footer styling. Rename rather than scope.
+
+### 6. h3 and h4 are technical reference, not display type
+
+Inner pages like `api-reference.md` use `### GET /api/health` and `### POST /api/v1/services` as section headings. Rendering these in Fraunces italic display style (the obvious choice for a "serif headings" design) makes the API reference unreadable.
+
+The rule: h1 and h2 stay Fraunces italic for page and section titles. h3 and h4 switch to Instrument Sans bold so technical reference reads as text, not as type. Add a `:has(code)` block that flips any heading containing inline code to JetBrains Mono with signal-orange code text. Add a `@supports not selector(:has(*))` fallback for older browsers.
+
+```css
+.md-typeset h3 {
+ font-family: var(--sans);
+ font-weight: 700;
+ font-size: clamp(18px, 1.6vw, 22px);
+}
+.md-typeset h1:has(code),
+.md-typeset h2:has(code),
+.md-typeset h3:has(code),
+.md-typeset h4:has(code) {
+ font-family: var(--mono);
+ font-style: normal;
+ font-weight: 700;
+}
+```
+
+### 7. Tabbed content nests boxes, fix it
+
+Material's `.md-typeset .tabbed-set` defaults to a bordered, backgrounded box. Code blocks inside also default to bordered backgrounded boxes. The result is nested rectangles with cluttered visual hierarchy.
+
+The fix: strip the `.tabbed-set` background and border. Leave only a bottom underline on `.tabbed-labels`. Let the inner code blocks be the visual statement. Tighten `pre > code` padding to ~14px so single-line install commands don't render as 70px-tall rectangles.
+
+### 8. Mermaid via Material's CSS variables, not via separate init
+
+MkDocs Material includes a Mermaid integration that reads `--md-mermaid-*` CSS variables. Don't bring in `mermaid.esm.mjs` separately like the upstream Hugo site does. Instead, set the variables in the slate scheme block:
+
+```css
+[data-md-color-scheme="slate"] {
+ --md-mermaid-node-bg-color: var(--ink-3);
+ --md-mermaid-node-fg-color: var(--paper);
+ --md-mermaid-edge-color: var(--mute);
+ /* ...full list in extra.css */
+}
+```
+
+Plus a `.md-typeset .mermaid` container restyle (dashed border, ink-3 background) for the diagram block itself.
+
+### 9. Guard inline scripts against `navigation.instant`
+
+`navigation.instant` is enabled (`mkdocs.yml`). On every navigation back to the homepage, Material rehydrates the body. Any `setInterval`, `setTimeout`, or event listener registered in an inline `
+```
+
+The `tick()` call on re-entry refreshes the displayed time without registering a new interval.
+
+### 10. Drop the light/dark toggle
+
+The canonical txn2 identity is dark only. Collapse `palette` to a single `scheme: slate`. Remove the `toggle:` blocks. Audit `extra.css` and `index.md` for orphan light-mode references (`hero-logo-light`, `prefers-color-scheme: light`, `kf-green` etc).
+
+### 11. Atmospheric overlays at low z-index
+
+`body::before` (grain) and `body::after` (vignette) are fixed viewport overlays. Place them at `z-index: 1` so they sit above the page background but below the rail (z-50) and skiplink (z-200). Vignette has no blend mode, so a higher z-index would darken interactive chrome.
+
+### 12. What Hugo does that MkDocs cannot match
+
+For reference when the next sister project chooses its adoption level:
+
+- Hugo can compile tokens.json into CSS custom properties at build time via `resources.Get` + `transform.Unmarshal`. MkDocs has no equivalent. We hand-mirror the tokens in `extra.css` `:root` and update them when upstream changes.
+- Hugo can subscribe to upstream tokens through a small extra.css that imports a generated `:root { --... }` block. MkDocs cannot. Token sync is a manual PR.
+- Hugo's partial system handles header/footer composition naturally. MkDocs uses Material template `{% block %}` overrides, which is similar but constrained to Material's block names (`announce`, `header`, `tabs`, `container`, `content`, `footer`, `scripts`).
+
+## Voice and copy
+
+Defers to upstream. Briefly:
+
+- No em-dashes (U+2014) or en-dashes (U+2013) anywhere, including code comments and template comments. Use commas, periods, colons, parentheses, slashes, hyphens.
+- No AI-tell vocabulary: `seamless`, `leverage`, `comprehensive`, `robust`, `delve`, `unleash`, `elevate`, `embark`, `tapestry`, `not just X but Y`, `as an AI`, `let me X`.
+- Sentence case for body. Lowercase for rail and label text. Title case rare.
+- Section indices: `§ 01 / title` with slash, never an em-dash.
+- Year ranges use a hyphen: `2017-2026`.
+- Verify before commit: `grep -RE "—|–" docs/ mkdocs.yml`.
+
+## Updating
+
+When the upstream `txn2/www/DESIGN.md` or `tokens.json` changes:
+
+1. Read the upstream diff. Identify which tokens, components, or rules changed.
+2. Update the matching CSS variables in `docs/stylesheets/extra.css` `:root`.
+3. If a component contract changed (padding, border, hover behavior), update the homepage template in `docs/overrides/home.html` and the matching CSS rules.
+4. Update this file's File map / Project-specific components / MkDocs Material learnings sections if a new learning emerges.
+5. Run `mkdocs build --strict` and verify in the browser before committing. Verify the home page hero, flagship cards, terminal, stack, coda, and home-footer. Verify an inner page (`/getting-started/`, `/api-reference/`) still inherits the look.
+
+Keep this file thin. If a section grows past 30 lines, ask whether it belongs upstream instead.
+
+## Downstream contract for sister projects
+
+This file is canonical only for kubefwd.com. Other sister projects (txeh, mcp-s3, mcp-trino, mcp-datahub, mcp-data-platform) considering the same adoption should:
+
+1. Use this file as a template for their own thin local DESIGN.md.
+2. Reference upstream `txn2/www/DESIGN.md` as the source of truth for tokens, typography, components, voice.
+3. Replace the kubefwd-specific sections (project-specific components, file paths, custom additions) with their own.
+4. Keep the MkDocs Material learnings section. Those apply to every MkDocs Material project.
+5. Update upstream's downstream-contract list when adding a new project.
diff --git a/docs/overrides/home.html b/docs/overrides/home.html
index 3f468052..3110d486 100644
--- a/docs/overrides/home.html
+++ b/docs/overrides/home.html
@@ -301,18 +301,19 @@