voidforge-build 23.11.3 → 23.12.0

package/dist/docs/patterns/autonomous-ops-triage-policy.md

@@ -0,0 +1,102 @@
+# Autonomous Operations Triage Policy
+
+**Scope:** Ops-flavored projects (infrastructure repos, monitoring daemons, homelab automation, scheduled-task systems) where the assistant is invoked autonomously and must decide whether to act, propose, or escalate without the operator present.
+
+**Status:** Pattern v1 (v23.11.4). Promoted by Wong from field reports #337, #336, #334.
+
+**Why this exists:** Two operators independently reinvented the same 4-bucket model across three projects (threadplex-ops, 1999collection M30-M32, 1999collection M20-M28). The pattern is reusable across all infrastructure repos. Codifying it stops the reinvention.
+
+## The 4-Bucket Model
+
+Classify every proposed autonomous action into exactly one bucket:
+
+| Bucket | Action | When | Logging | Operator Notification |
+|--------|--------|------|---------|----------------------|
+| **A — Self-resolving** | Auto-execute | Action is fully reversible, low-blast-radius, has a clear procedure, and was authorized in a durable instruction (CLAUDE.md, agent definition, prior issue) | Append to ops log | None unless asked |
+| **B — Runbook-safe** | Follow runbook procedure | Action is documented in a runbook, has been executed successfully before, and operator pre-approved the runbook | Append to ops log with runbook ID | Summary at next session start |
+| **C — Operator-approval required** | Propose via Telegram button / GitHub issue / explicit message; WAIT | Action has medium blast radius, irreversible side effects, OR runbook ambiguity | Log proposal + decision | Active notification (Telegram, Slack, email per project) |
+| **D — Hard-never** | Log + escalate; NEVER attempt | Action is on the forbidden list (e.g., production rollback without ticket, secret rotation without quorum, destructive migration without approval) | Log attempt + escalation | Active high-priority alert |
+
+## Pairing with SessionStart Hook
+
+Ops projects should pair this policy with a `.claude/settings.json` SessionStart hook that injects current state and a reminder of the policy:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "command": "bash .claude/hooks/session-start.sh",
+        "description": "Inject current ops state + triage policy reminder"
+      }
+    ]
+  }
+}
+```
+
+The hook script outputs the current pending-action set (read from `logs/pending-actions.json` or similar) plus a one-line reminder pointing at this policy file.
+
+### Visibility rule
+
+**SessionStart hook output is context-only — the assistant must `echo` the relevant portions back to the operator at session start.** Otherwise the operator has no visual confirmation that the hook fired and the policy is live. Both #337 and #336 documented operators discovering that hooks were silently running with no visibility — both reinvented an explicit echo step. Make it part of the policy from day one.
+
+## Decision Tree (Each Proposed Action)
+
+```
+Is the action on the forbidden list (D)?
+  Yes → Log attempt, raise high-priority alert, STOP.
+  No  → Continue.
+
+Does the action have an approved runbook (B)?
+  Yes → Execute runbook, log with runbook ID. STOP.
+  No  → Continue.
+
+Is the action fully reversible AND low blast radius AND pre-authorized in durable instructions (A)?
+  Yes → Execute, log. STOP.
+  No  → Bucket C: propose to operator, wait, do not execute until approved.
+```
+
+## Logging Format
+
+Each ops log entry should record:
+
+```jsonl
+{
+  "timestamp": "2026-05-12T19:42:00Z",
+  "bucket": "A|B|C|D",
+  "action": "short description",
+  "decision": "executed|proposed|escalated|skipped",
+  "rationale": "why this bucket",
+  "runbook_id": "RB-007 if applicable",
+  "operator_notified": false,
+  "outcome": "success|failed|pending"
+}
+```
+
+JSON Lines (one object per line) keeps the log greppable and append-only.
+
+## Adoption Checklist
+
+For a new ops-flavored project:
+
+- [ ] Pick the buckets that apply (most projects use all four)
+- [ ] Write the forbidden list (Bucket D) FIRST — concrete and exhaustive
+- [ ] Document each runbook (Bucket B) with a fixed ID, expected outcome, and rollback procedure
+- [ ] Set up the SessionStart hook + echo step
+- [ ] Configure the operator-notification channel (Telegram bot, GitHub issue, etc.)
+- [ ] Establish the ops log path and rotation policy
+- [ ] Add a one-line reminder of this policy to the project's `CLAUDE.md` Personality section
+
+## Non-Goals
+
+This pattern is NOT:
+
+- A replacement for `/campaign` or `/build` — those are user-driven workflows with human pacing
+- A general agent-permissioning model — settings.json `allow`/`deny` lists handle tool-level permissions
+- A substitute for tested code — Bucket A actions still need their own correctness verification
+
+## See Also
+
+- `docs/patterns/daemon-process.ts` — daemon lifecycle, PID management, signal handling
+- `docs/methods/HEARTBEAT.md` — long-running ops job scheduling
+- `docs/methods/FIELD_MEDIC.md` — post-mortem analysis for ops incidents

package/dist/docs/patterns/daemon-process.ts

@@ -325,6 +325,95 @@ function createLogger(logPath: string): { log: (msg: string) => void; close: ()
   };
 }
 
+// ── .env Parsing (literal, $-safe) ────────────────────
+// field report #344 F1: never source secrets via `export $(cat .env)` /
+// `eval "$(cat .env)"`. The shell performs variable expansion and word
+// splitting on the RHS, so a `$`-bearing secret — bcrypt hashes
+// ($2b$...), JWTs, Postgres URLs with `$` in the password, anything with
+// `$VAR`/`${...}`/backticks — gets mangled or silently truncated. Parse
+// literally instead: read each line, split on the FIRST `=` only, and keep
+// the value byte-for-byte (no expansion, no eval). For shells, the
+// equivalent is `while IFS='=' read -r k v; do export "$k=$v"; done < .env`
+// — note IFS='=' and `read -r` (raw, no backslash processing), which never
+// re-expands the value.
+//
+// Prefer a runtime-native loader where available — it sidesteps the shell
+// entirely:
+//   - Node 20.6+: `node --env-file=.env daemon.js` (literal parse, no shell).
+//   - systemd:    `EnvironmentFile=/etc/voidforge/heartbeat.env` (also literal;
+//                 unit-file `Environment=` lines do NOT undergo shell expansion).
+// Use this helper only when you must parse `.env` in-process.
+
+function parseDotenv(contents: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const rawLine of contents.split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    // Skip blanks and comments. A leading `export ` prefix is tolerated.
+    const trimmed = line.trimStart();
+    if (trimmed === '' || trimmed.startsWith('#')) continue;
+    const body = trimmed.startsWith('export ') ? trimmed.slice(7) : trimmed;
+
+    // Split on the FIRST `=` only — values may legitimately contain `=`.
+    const eq = body.indexOf('=');
+    if (eq < 0) continue; // not a KEY=VALUE line — ignore, don't guess
+    const key = body.slice(0, eq).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) continue; // invalid env name
+
+    let value = body.slice(eq + 1);
+    // Strip a single layer of matching surrounding quotes. Inside quotes the
+    // value is taken LITERALLY — no `$` expansion, no eval — which is the
+    // whole point: `PASS='p@$$w0rd'` keeps its `$$` intact.
+    if (value.length >= 2 &&
+        ((value[0] === '"' && value[value.length - 1] === '"') ||
+         (value[0] === "'" && value[value.length - 1] === "'"))) {
+      value = value.slice(1, -1);
+    } else {
+      // Unquoted: trim trailing inline whitespace only (POSIX-ish), never
+      // touch interior `$` characters.
+      value = value.trimEnd();
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+// ── systemd hardening stanza (Node daemons) ───────────
+// field report #344 F3: when running this daemon under systemd, harden the
+// unit — but DO NOT set `MemoryDenyWriteExecute=true` for a Node/V8 process.
+// V8's JIT allocates pages that are written and then executed (it manages its
+// own W^X internally); MDWE forbids any write+exec mapping, so the daemon
+// takes a SIGTRAP and dies at boot, usually before it logs a single line. The
+// safe, high-value sandbox flags below give most of MDWE's benefit without the
+// JIT collision:
+//
+//   [Unit]
+//   Description=VoidForge Heartbeat daemon
+//   After=network-online.target
+//   Wants=network-online.target
+//
+//   [Service]
+//   Type=simple
+//   ExecStart=/usr/bin/node /opt/voidforge/daemon.js
+//   EnvironmentFile=/etc/voidforge/heartbeat.env   # literal parse — see #344 F1
+//   Restart=on-failure
+//   RestartSec=5
+//
+//   # Hardening — keep these:
+//   NoNewPrivileges=true        # no setuid/setgid privilege escalation
+//   ProtectSystem=full          # /usr, /boot, /etc mounted read-only
+//   ProtectHome=true            # /home, /root, /run/user hidden
+//   PrivateTmp=true             # private /tmp + /var/tmp namespace
+//   # MemoryDenyWriteExecute=true  # <-- OMITTED ON PURPOSE: breaks V8 JIT
+//                                  #     (SIGTRAP at boot). Re-enable ONLY for
+//                                  #     Go/Rust/static daemons with no JIT.
+//
+//   [Install]
+//   WantedBy=multi-user.target
+//
+// Go, Rust, and other AOT-compiled daemons emit no executable pages at
+// runtime, so for THEM you can and should keep `MemoryDenyWriteExecute=true`.
+// The omission above is V8-specific, not a general weakening.
+
 export {
   writePidFile, checkStalePid, removePidFile,
   generateSessionToken, validateToken,
@@ -333,6 +422,7 @@ export {
   setupSignalHandlers,
   JobScheduler,
   createLogger,
+  parseDotenv,
   PID_FILE, SOCKET_PATH, TOKEN_FILE, STATE_FILE, LOG_FILE,
 };
 export type { DaemonState, HeartbeatState, ScheduledJob };

package/dist/docs/patterns/deploy-preflight.ts

@@ -4,13 +4,17 @@
  * Reference implementation for .claude/commands/deploy.md Step 2.5.
  * Scans the deploy artifact directory BEFORE upload. Exits non-zero on any hit.
  *
- * Evidence: field reports #305 (32-day credential leak), #303 (methodology exposure).
+ * Evidence: field reports #305 (32-day credential leak), #303 (methodology exposure),
+ * #343 F7 (stop-build-start loop mislabeled "blue-green" → 502 window every deploy).
  *
  * Key principles:
  * - Scan the deploy payload directory, NOT the repo root.
  * - Never auto-filter — a hit means the operator must investigate.
  * - Never print secret content; only paths + pattern IDs.
  * - Allowlist escape hatch via DEPLOY_PREFLIGHT_ALLOW (comma-separated globs).
+ * - Deploy-strategy claims must be backed by a real mechanism: a comment that
+ *   says "blue-green"/"zero-downtime" without an atomic swap (rename, container
+ *   swap, or LB cutover) is a lie that ships a 502 window (#343 F7).
  *
  * Usage:
  *   npx tsx docs/patterns/deploy-preflight.ts ./dist
@@ -55,11 +59,82 @@ const TEXT_EXTENSIONS = new Set([
 ]);
 
 interface Hit {
-  kind: 'name' | 'content';
+  kind: 'name' | 'content' | 'strategy';
   path: string;
   patternId: string;
 }
 
+// ---------- deploy-strategy nomenclature check (field report #343 F7) ----------
+// A stop-build-start loop mislabeled "blue-green"/"zero-downtime" still drops the
+// old process before the new one is live, producing a 502 window on every deploy.
+// The comment lies; the mechanism doesn't. This flags scripts whose comments CLAIM
+// blue-green / zero-downtime but where no atomic-swap mechanism is detectable —
+// temp-build-then-rename, container/image swap, or load-balancer cutover.
+
+// File shapes that can carry a deploy strategy worth checking.
+const DEPLOY_SCRIPT_EXTENSIONS = new Set([
+  '.sh', '.bash', '.zsh', '.yml', '.yaml', '.ps1',
+]);
+const DEPLOY_SCRIPT_BASENAMES = new Set([
+  'Dockerfile', 'Procfile', 'Makefile',
+]);
+
+// Comments that CLAIM an atomic deploy strategy.
+const STRATEGY_CLAIM_RE = /\b(blue[\s/_-]?green|zero[\s/_-]?downtime|hot[\s/_-]?swap|atomic\s+deploy(?:ment)?)\b/i;
+
+// Any one of these signals a real atomic-swap mechanism is present.
+const ATOMIC_SWAP_SIGNALS: { id: string; re: RegExp }[] = [
+  // temp build dir then rename/symlink-swap into place (release-then-link pattern)
+  { id: 'rename-swap', re: /\b(?:mv|rename|ln\s+-s(?:fn|nf|f)?)\b[^\n]*\b(?:current|live|release|active|prod(?:uction)?)\b/i },
+  { id: 'symlink-current', re: /\bln\s+-s(?:fn|nf|f)?\b[^\n]*\bcurrent\b/i },
+  // container / image swap: new container up, traffic moved, old removed
+  { id: 'container-swap', re: /\bdocker\b[^\n]*\b(?:run|up|--scale|service\s+update)\b|\bdocker[\s-]compose\b[^\n]*\bup\b[^\n]*\b(?:--no-recreate|--scale)\b|\bcontainer[\s_-]?swap\b/i },
+  { id: 'orchestrator-rollout', re: /\b(?:kubectl\s+rollout|helm\s+upgrade|nomad\s+job\s+run|ecs\b[^\n]*update-service)\b/i },
+  // load-balancer / proxy cutover: register new target, then drain/deregister old
+  { id: 'lb-cutover', re: /\b(?:register-targets|deregister-targets|modify-listener|switchover|traffic[\s_-]?shift|weighted[\s_-]?routing|upstream)\b/i },
+  { id: 'proxy-reload', re: /\b(?:nginx\s+-s\s+reload|caddy\s+reload|envoy\b[^\n]*config|haproxy\b[^\n]*reload)\b/i },
+];
+
+// Sequences that betray a stop-build-start loop (kill old, then start new).
+// Used only to strengthen the signal — a claim with NO atomic mechanism is
+// already a hit; this just confirms the anti-pattern is actively present.
+const STOP_START_RE = /\b(?:kill|stop|down|terminate|systemctl\s+stop|pm2\s+stop|docker\s+stop|docker\s+rm)\b[\s\S]{0,400}?\b(?:start|up|run|systemctl\s+start|pm2\s+start|npm\s+(?:run\s+)?start|node\b)/i;
+
+function scanStrategy(fullPath: string, relPath: string): string | null {
+  const base = relPath.split(sep).pop() ?? '';
+  const ext = extname(fullPath).toLowerCase();
+  const looksLikeDeployScript =
+    DEPLOY_SCRIPT_EXTENSIONS.has(ext) ||
+    DEPLOY_SCRIPT_BASENAMES.has(base) ||
+    /deploy|release|rollout|cutover/i.test(base);
+  if (!looksLikeDeployScript) return null;
+
+  let stats;
+  try {
+    stats = statSync(fullPath);
+  } catch {
+    return null;
+  }
+  if (stats.size > 2_000_000) return null;
+
+  let buf: string;
+  try {
+    buf = readFileSync(fullPath, 'utf8');
+  } catch {
+    return null;
+  }
+
+  if (!STRATEGY_CLAIM_RE.test(buf)) return null; // no claim, nothing to verify
+  const hasAtomicSwap = ATOMIC_SWAP_SIGNALS.some((s) => s.re.test(buf));
+  if (hasAtomicSwap) return null; // claim is backed by a real mechanism
+
+  // Claim present, no atomic-swap mechanism. Distinguish the worst case:
+  // an actual stop-build-start loop wearing a blue-green label.
+  return STOP_START_RE.test(buf)
+    ? 'strategy-mislabel-stop-start'
+    : 'strategy-claim-no-atomic-swap';
+}
+
 function globToRegex(glob: string): RegExp {
   const escaped = glob
     .replace(/[.+^${}()|[\]\\]/g, '\\$&')
@@ -167,6 +242,14 @@ function main(): void {
     const contentHit = scanContent(fullPath);
     if (contentHit) {
       hits.push({ kind: 'content', path: relPath, patternId: contentHit });
+      continue; // a secret hit is already terminal; don't double-report this file
+    }
+
+    // Deploy-strategy nomenclature check (field report #343 F7): a script whose
+    // comments claim blue-green / zero-downtime but ships no atomic-swap mechanism.
+    const strategyHit = scanStrategy(fullPath, relPath);
+    if (strategyHit) {
+      hits.push({ kind: 'strategy', path: relPath, patternId: strategyHit });
     }
   }
 

package/dist/docs/patterns/design-tokens.ts

@@ -0,0 +1,338 @@
+/**
+ * Pattern: Semantic Design Tokens (primitive -> semantic -> CSS custom properties)
+ *
+ * Key principles:
+ * - NO raw color or type values in components. Components reference SEMANTIC
+ *   tokens only (e.g., `surface.raised`, `text.muted`, `font.size.body`) —
+ *   never primitives (e.g., `#4f46e5`, `gray-200`, `16px`).
+ * - Two layers: PRIMITIVES (the raw palette/scale — every hex, every step of
+ *   the type scale) and SEMANTIC roles (what a thing MEANS — `accent`,
+ *   `danger`, `border.subtle`). Semantic roles map TO primitives.
+ * - Tokens are emitted as CSS custom properties (`--vf-color-accent`) so a
+ *   theme override is a `:root[data-theme=...]` block — not a recompile.
+ * - A palette or type pivot becomes a TOKEN edit (re-point semantic roles at
+ *   different primitives), not a component-by-component rewrite.
+ *
+ * The trap (field report #351, #3): a rebrand asked for a new accent color and
+ * a tighter type scale. Components had hardcoded `#4f46e5` and `text-[15px]`
+ * inline in 60+ files. The "one color change" turned into a 60-file grep-and-
+ * replace that missed five spots (shipped a two-tone accent for a week) and
+ * couldn't support a dark theme at all because the values had no indirection.
+ * Scoping all color/type to semantic tokens makes the pivot a single edit.
+ *
+ * Agents: Galadriel (design system), Legolas (code), Samwise (a11y contrast)
+ *
+ * Framework adaptations:
+ *   React/Next.js: This file — emit CSS vars into a <style> at the root, read
+ *     them via Tailwind theme extension or plain `var(--vf-...)`.
+ *   Tailwind: map semantic tokens into `theme.extend.colors` /
+ *     `theme.extend.fontSize` as `var(--vf-...)` so `bg-accent` resolves to the
+ *     token (see the Tailwind block at the bottom).
+ *   Vue/Svelte: same CSS-var output; bind `data-theme` on a root element.
+ *   Django/Rails templates: emit the `:root` block from `tokensToCss()` into a
+ *     server-rendered <style> tag in the base layout; components use `var(...)`.
+ *
+ * Pairs with /docs/patterns/component.tsx (components consume tokens, never
+ * raw values) and /docs/patterns/combobox.tsx (a11y-critical surfaces).
+ */
+
+// ── Layer 1: Primitives (the raw palette + scales) ───────────────────────────
+// These are the ONLY place raw values live. Name them by what they ARE
+// (a swatch index, a scale step), never by what they're FOR. A primitive
+// never appears directly in a component.
+
+export const primitives = {
+  color: {
+    // Neutral ramp
+    white: '#ffffff',
+    black: '#0a0a0a',
+    gray50: '#f9fafb',
+    gray100: '#f3f4f6',
+    gray200: '#e5e7eb',
+    gray500: '#6b7280',
+    gray700: '#374151',
+    gray900: '#111827',
+    // Brand ramp
+    indigo500: '#6366f1',
+    indigo600: '#4f46e5',
+    indigo700: '#4338ca',
+    // Status ramps
+    red500: '#ef4444',
+    red600: '#dc2626',
+    green500: '#22c55e',
+    amber500: '#f59e0b',
+  },
+  // Type scale — a modular scale, not arbitrary pixels.
+  fontSize: {
+    xs: '0.75rem',
+    sm: '0.875rem',
+    base: '1rem',
+    lg: '1.125rem',
+    xl: '1.5rem',
+    '2xl': '2rem',
+  },
+  fontWeight: {
+    regular: '400',
+    medium: '500',
+    semibold: '600',
+    bold: '700',
+  },
+  lineHeight: {
+    tight: '1.2',
+    normal: '1.5',
+    relaxed: '1.7',
+  },
+  fontFamily: {
+    sans: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+    mono: 'ui-monospace, "SF Mono", "Cascadia Code", monospace',
+  },
+} as const;
+
+type PrimitiveColor = keyof typeof primitives.color;
+type PrimitiveFontSize = keyof typeof primitives.fontSize;
+type PrimitiveFontWeight = keyof typeof primitives.fontWeight;
+type PrimitiveLineHeight = keyof typeof primitives.lineHeight;
+type PrimitiveFontFamily = keyof typeof primitives.fontFamily;
+
+// ── Layer 2: Semantic tokens (what a thing MEANS) ────────────────────────────
+// A semantic token is a NAME FOR A ROLE that points at a primitive. Components
+// reference these. Re-point them to pivot the whole product. The shape is the
+// contract — a theme override must provide every role, so the type system
+// guarantees no role is left un-themed.
+
+export type SemanticTokens = {
+  color: {
+    'bg.canvas': PrimitiveColor; // page background
+    'bg.raised': PrimitiveColor; // cards, popovers
+    'text.default': PrimitiveColor;
+    'text.muted': PrimitiveColor;
+    'text.on-accent': PrimitiveColor; // text placed on top of `accent`
+    'border.subtle': PrimitiveColor;
+    accent: PrimitiveColor; // primary action / brand
+    'accent.hover': PrimitiveColor;
+    danger: PrimitiveColor;
+    success: PrimitiveColor;
+    warning: PrimitiveColor;
+  };
+  type: {
+    'size.caption': PrimitiveFontSize;
+    'size.body': PrimitiveFontSize;
+    'size.heading': PrimitiveFontSize;
+    'size.display': PrimitiveFontSize;
+    'weight.body': PrimitiveFontWeight;
+    'weight.emphasis': PrimitiveFontWeight;
+    'leading.body': PrimitiveLineHeight;
+    'leading.heading': PrimitiveLineHeight;
+    'family.ui': PrimitiveFontFamily;
+    'family.code': PrimitiveFontFamily;
+  };
+};
+
+// ── Worked example, step 1: define the default (light) theme ─────────────────
+// Every semantic role points at a primitive. This is the whole brand surface —
+// change these mappings and the product re-skins. Note: no hex here, only
+// references into `primitives`.
+
+export const lightTheme: SemanticTokens = {
+  color: {
+    'bg.canvas': 'white',
+    'bg.raised': 'gray50',
+    'text.default': 'gray900',
+    'text.muted': 'gray500',
+    'text.on-accent': 'white',
+    'border.subtle': 'gray200',
+    accent: 'indigo600',
+    'accent.hover': 'indigo700',
+    danger: 'red600',
+    success: 'green500',
+    warning: 'amber500',
+  },
+  type: {
+    'size.caption': 'sm',
+    'size.body': 'base',
+    'size.heading': 'xl',
+    'size.display': '2xl',
+    'weight.body': 'regular',
+    'weight.emphasis': 'semibold',
+    'leading.body': 'normal',
+    'leading.heading': 'tight',
+    'family.ui': 'sans',
+    'family.code': 'mono',
+  },
+};
+
+// ── Worked example, step 2: a theme override (dark) ──────────────────────────
+// Because color roles are indirection, a dark theme is just a different
+// primitive mapping. The type scale is unchanged here — override only what
+// differs. A full rebrand would supply a new `primitives.color` ramp AND a new
+// mapping; both still live in tokens, never in components.
+
+export const darkTheme: SemanticTokens = {
+  color: {
+    'bg.canvas': 'black',
+    'bg.raised': 'gray900',
+    'text.default': 'gray50',
+    'text.muted': 'gray500',
+    'text.on-accent': 'white',
+    'border.subtle': 'gray700',
+    accent: 'indigo500', // lighter accent reads better on dark canvas
+    'accent.hover': 'indigo600',
+    danger: 'red500',
+    success: 'green500',
+    warning: 'amber500',
+  },
+  type: lightTheme.type, // type scale is theme-invariant in this example
+};
+
+// ── Emit: semantic tokens -> CSS custom properties ───────────────────────────
+// `--vf-color-<role>` and `--vf-type-<role>`, with `.` and braces flattened to
+// `-`. The variable VALUE is the resolved primitive, so consumers never touch
+// primitives directly. Emit one block per theme keyed by `data-theme`.
+
+const CSS_VAR_PREFIX = '--vf';
+
+function cssVarName(group: 'color' | 'type', role: string): string {
+  // 'accent.hover' -> '--vf-color-accent-hover'
+  const safeRole = role.replace(/[.\s]+/g, '-');
+  return `${CSS_VAR_PREFIX}-${group}-${safeRole}`;
+}
+
+function resolveColor(role: PrimitiveColor): string {
+  return primitives.color[role];
+}
+
+function resolveType(
+  tokenKey: keyof SemanticTokens['type'],
+  ref: string,
+): string {
+  if (tokenKey.startsWith('size.')) return primitives.fontSize[ref as PrimitiveFontSize];
+  if (tokenKey.startsWith('weight.')) return primitives.fontWeight[ref as PrimitiveFontWeight];
+  if (tokenKey.startsWith('leading.')) return primitives.lineHeight[ref as PrimitiveLineHeight];
+  if (tokenKey.startsWith('family.')) return primitives.fontFamily[ref as PrimitiveFontFamily];
+  throw new Error(`Unknown type token group: ${tokenKey}`);
+}
+
+/** Build the `--vf-*` declarations for one theme as `key: value` lines. */
+export function themeToDeclarations(tokens: SemanticTokens): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [role, ref] of Object.entries(tokens.color)) {
+    out[cssVarName('color', role)] = resolveColor(ref as PrimitiveColor);
+  }
+  for (const [role, ref] of Object.entries(tokens.type)) {
+    out[cssVarName('type', role)] = resolveType(
+      role as keyof SemanticTokens['type'],
+      ref as string,
+    );
+  }
+  return out;
+}
+
+/**
+ * Render every theme into a single CSS string: `:root` carries the default
+ * theme, `[data-theme="<name>"]` carries each override. Drop this into a
+ * <style> tag (React: dangerouslySetInnerHTML; templates: server-render).
+ */
+export function tokensToCss(themes: {
+  default: SemanticTokens;
+  overrides?: Record<string, SemanticTokens>;
+}): string {
+  const block = (selector: string, decls: Record<string, string>): string => {
+    const body = Object.entries(decls)
+      .map(([k, v]) => `  ${k}: ${v};`)
+      .join('\n');
+    return `${selector} {\n${body}\n}`;
+  };
+
+  const parts = [block(':root', themeToDeclarations(themes.default))];
+  for (const [name, theme] of Object.entries(themes.overrides ?? {})) {
+    parts.push(block(`[data-theme="${name}"]`, themeToDeclarations(theme)));
+  }
+  return parts.join('\n\n');
+}
+
+// ── Worked example, step 3: consume tokens in a component ─────────────────────
+// The component references SEMANTIC tokens via `var(--vf-...)` — never a hex,
+// never a pixel literal. Swapping `data-theme` on any ancestor re-themes it
+// with zero component changes. This is the payoff: the pivot lives in tokens.
+
+import type { CSSProperties, PropsWithChildren } from 'react';
+
+const tokenColor = (role: keyof SemanticTokens['color']): string =>
+  `var(${cssVarName('color', role)})`;
+const tokenType = (role: keyof SemanticTokens['type']): string =>
+  `var(${cssVarName('type', role)})`;
+
+export function CalloutCard({ children }: PropsWithChildren): JSX.Element {
+  const style: CSSProperties = {
+    background: tokenColor('bg.raised'),
+    color: tokenColor('text.default'),
+    border: `1px solid ${tokenColor('border.subtle')}`,
+    borderRadius: 8,
+    padding: '1rem 1.25rem',
+    fontFamily: tokenType('family.ui'),
+    fontSize: tokenType('size.body'),
+    lineHeight: tokenType('leading.body'),
+  };
+  const ctaStyle: CSSProperties = {
+    background: tokenColor('accent'),
+    color: tokenColor('text.on-accent'),
+    fontWeight: tokenType('weight.emphasis'),
+    border: 'none',
+    borderRadius: 6,
+    padding: '0.5rem 0.875rem',
+    marginTop: '0.75rem',
+    cursor: 'pointer',
+  };
+  return (
+    <section style={style}>
+      {children}
+      {/* No #hex, no 15px — only token references. A rebrand never touches this file. */}
+      <button type="button" style={ctaStyle}>
+        Continue
+      </button>
+    </section>
+  );
+}
+
+// To mount the themes once at the app root (Next.js: in a Server Component
+// layout, or a root <style> in app/layout.tsx):
+//
+//   const css = tokensToCss({ default: lightTheme, overrides: { dark: darkTheme } });
+//   // <style dangerouslySetInnerHTML={{ __html: css }} />
+//   // then: <html data-theme={prefersDark ? 'dark' : undefined}> ... </html>
+//
+// produces, e.g.:
+//   :root { --vf-color-accent: #4f46e5; --vf-type-size-body: 1rem; ... }
+//   [data-theme="dark"] { --vf-color-accent: #6366f1; ... }
+
+// ── Tailwind adaptation ──────────────────────────────────────────────────────
+// Map semantic tokens into the Tailwind theme as `var(--vf-...)`, so utility
+// classes (`bg-accent`, `text-muted`, `text-body`) resolve to tokens and a
+// theme swap still flows through `data-theme`. Components keep using semantic
+// utilities — never `bg-[#4f46e5]`.
+//
+//   // tailwind.config.ts
+//   export default {
+//     theme: {
+//       extend: {
+//         colors: {
+//           canvas: 'var(--vf-color-bg-canvas)',
+//           raised: 'var(--vf-color-bg-raised)',
+//           accent: { DEFAULT: 'var(--vf-color-accent)', hover: 'var(--vf-color-accent-hover)' },
+//           muted: 'var(--vf-color-text-muted)',
+//         },
+//         fontSize: {
+//           caption: 'var(--vf-type-size-caption)',
+//           body: 'var(--vf-type-size-body)',
+//           heading: 'var(--vf-type-size-heading)',
+//         },
+//       },
+//     },
+//   };
+//
+// Lint guardrail (field report #351): forbid raw hex/px in component source so
+// the indirection can't be bypassed. Stylelint: `color-no-hex` + a custom
+// `declaration-property-value-disallowed-list` for `font-size: /\d+px/`; for
+// className strings, an ESLint `no-restricted-syntax` rule banning Tailwind
+// arbitrary-value brackets in color/size utilities (e.g. `bg-[#...]`,
+// `text-[15px]`). The token layer only pays off if primitives can't leak past it.