@nurix/etna 0.18.20 → 0.18.22

package/data/harnesses/code/skills/design/scripts/derive-personality.mjs

@@ -1,19 +1,35 @@
 #!/usr/bin/env node
-// skills/design/scripts/derive-personality.mjs — design.md parser, coverage gate (--check), and token emitter (--emit) for the operator-UI personality system (D29, D6).
-
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+// skills/design/scripts/derive-personality.mjs — design-tokens artifact resolver, coverage gate (--check; SCHEMA.md rules 1–12), and CSS emitter (--emit) for the operator-UI personality system (D29, D6).
+//
+// The reference consumer of data/design-tokens/SCHEMA.md: resolves an artifact directory
+// (design.tokens.json + design.resolver.json [+ design.tokens.dark.json]) through the resolver's
+// deterministic order — concatenate the set files, overlay the selected theme context, resolve
+// aliases — then validates (rules 1–12) or emits personality.css / globals.css / the <html> attributes.
+//
+// Usage: derive-personality.mjs <artifact-dir> [--check | --emit <outdir>] [--theme light|dark]
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
-// The 26 visual primitives, in emission order (names are law; no leading --).
-const PRIMITIVES = [
-  "radius", "shadow-intensity", "border-weight", "density-gap", "density-inset",
-  "font-sans", "font-mono", "font-weight-normal", "font-weight-strong", "heading-tracking",
-  "duration-unit", "duration-fast", "duration-normal", "duration-slow", "ease-default",
-  "contrast-boost",
-  "icon-stroke", "icon-size-base",
-  "sidebar-width-expanded", "sidebar-width-collapsed", "topbar-height", "side-panel-width",
-  "side-panel-width-rich", "modal-width-max", "form-max-width", "table-row-height",
-];
+const EXT = "com.nurix.design";
+
+// The 26 visual primitives and their DTCG $type, in emission order (leaf names are law; no leading --).
+const PRIMITIVE_TYPES = new Map([
+  ["radius", "dimension"], ["shadow-intensity", "number"], ["border-weight", "dimension"],
+  ["density-gap", "number"], ["density-inset", "number"],
+  ["font-sans", "fontFamily"], ["font-mono", "fontFamily"],
+  ["font-weight-normal", "fontWeight"], ["font-weight-strong", "fontWeight"],
+  ["heading-tracking", "number"],
+  ["duration-unit", "duration"], ["duration-fast", "duration"], ["duration-normal", "duration"],
+  ["duration-slow", "duration"], ["ease-default", "cubicBezier"],
+  ["contrast-boost", "number"],
+  ["icon-stroke", "number"], ["icon-size-base", "dimension"],
+  ["sidebar-width-expanded", "dimension"], ["sidebar-width-collapsed", "dimension"],
+  ["topbar-height", "dimension"], ["side-panel-width", "dimension"],
+  ["side-panel-width-rich", "dimension"], ["modal-width-max", "dimension"],
+  ["form-max-width", "dimension"], ["table-row-height", "dimension"],
+]);
+const PRIMITIVES = [...PRIMITIVE_TYPES.keys()];
 
 // The 17 semantic color tokens, in emission order.
 const SEMANTIC_TOKENS = [
@@ -32,312 +48,574 @@ const SUBSTRATE_TOKENS = [
 
 const ALL_TOKENS = [...SEMANTIC_TOKENS, ...SUBSTRATE_TOKENS];
 
+const RAMP_STEPS = ["h1", "h2", "h3", "body", "small", "caption"];
 const LEGAL_VERBOSITY = ["full", "default", "compact", "expert"];
 const LEGAL_FEEDBACK = ["subtle", "minimal"];
 const LEGAL_DENSITY = ["spacious", "standard", "dense"];
 const LEGAL_PROVENANCE = ["project", "extracted", "library", "default"];
+const LEGAL_TYPES = ["color", "dimension", "duration", "cubicBezier", "fontFamily", "fontWeight", "number", "typography"];
+const LEGAL_THEMES = ["light", "dark"];
+const MANIFEST_KEYS = ["spacing-scale", "radius-scale", "shadow-levels", "motion", "icons", "accent-count"];
 
 // Shadow-level names ranked by increasing intensity, for the ordering check.
 const SHADOW_RANK = { none: 0, "2xs": 1, xs: 2, sm: 3, md: 4, lg: 5, xl: 6, "2xl": 7 };
 
-// Strip a trailing #-comment while respecting quoted spans (hex colors are quoted, so an unquoted # is always a comment).
-function stripComment(line) {
-  let inSingle = false, inDouble = false;
-  for (let i = 0; i < line.length; i++) {
-    const c = line[i];
-    if (c === '"' && !inSingle) inDouble = !inDouble;
-    else if (c === "'" && !inDouble) inSingle = !inSingle;
-    else if (c === "#" && !inSingle && !inDouble) return line.slice(0, i);
-  }
-  return line;
+// ---------------------------------------------------------------------------
+// CSS value parsers — the parse-back authority (rule 9); byte-compatible with convert-design-md.mjs
+// ---------------------------------------------------------------------------
+
+// Round to at most 5 decimals (the srgb component precision).
+function round5(n) {
+  return Math.round(n * 1e5) / 1e5;
 }
 
-// Remove one layer of matching surrounding quotes from a scalar.
+// Strip one layer of matching surrounding quotes and unescape \" within double quotes.
 function unquote(raw) {
   const s = raw.trim();
-  if (s.length >= 2 && ((s[0] === '"' && s.at(-1) === '"') || (s[0] === "'" && s.at(-1) === "'"))) {
-    return s.slice(1, -1);
-  }
+  if (s.length >= 2 && s[0] === '"' && s.at(-1) === '"') return s.slice(1, -1).replaceAll('\\"', '"');
+  if (s.length >= 2 && s[0] === "'" && s.at(-1) === "'") return s.slice(1, -1);
   return s;
 }
 
-// Split a string on a delimiter at bracket-depth 0 and outside quotes (handles nested [] {} and quoted commas).
+// Split on a delimiter at bracket-depth 0 and outside quotes.
 function splitTopLevel(str, delim) {
   const parts = [];
-  let depth = 0, inSingle = false, inDouble = false, cur = "";
-  for (const c of str) {
-    if (c === '"' && !inSingle) { inDouble = !inDouble; cur += c; }
+  let depth = 0, inDouble = false, inSingle = false, cur = "";
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    if (c === '"' && !inSingle && str[i - 1] !== "\\") { inDouble = !inDouble; cur += c; }
     else if (c === "'" && !inDouble) { inSingle = !inSingle; cur += c; }
-    else if (!inSingle && !inDouble && (c === "[" || c === "{")) { depth++; cur += c; }
-    else if (!inSingle && !inDouble && (c === "]" || c === "}")) { depth--; cur += c; }
-    else if (!inSingle && !inDouble && c === delim && depth === 0) { parts.push(cur); cur = ""; }
+    else if (!inDouble && !inSingle && (c === "[" || c === "{" || c === "(")) { depth++; cur += c; }
+    else if (!inDouble && !inSingle && (c === "]" || c === "}" || c === ")")) { depth--; cur += c; }
+    else if (!inDouble && !inSingle && depth === 0 && c === delim) { parts.push(cur); cur = ""; }
     else cur += c;
   }
   parts.push(cur);
   return parts;
 }
 
-// Parse a scalar / inline array / inline object into a JS value.
-function parseScalar(raw) {
-  const s = raw.trim();
-  if (s.startsWith("[")) return parseInlineArray(s);
-  if (s.startsWith("{")) return parseInlineObject(s);
-  return unquote(s);
-}
-
-// Parse an inline [a, b, c] array into a JS array of parsed scalars.
-function parseInlineArray(s) {
-  const inner = s.slice(s.indexOf("[") + 1, s.lastIndexOf("]"));
-  if (inner.trim() === "") return [];
-  return splitTopLevel(inner, ",").map((x) => parseScalar(x)).filter((v) => !(typeof v === "string" && v === ""));
-}
-
-// Parse an inline { k: v, ... } object into a plain JS object.
-function parseInlineObject(s) {
-  const inner = s.slice(s.indexOf("{") + 1, s.lastIndexOf("}"));
-  const obj = {};
-  for (const part of splitTopLevel(inner, ",")) {
-    if (part.trim() === "") continue;
-    const ci = part.indexOf(":");
-    if (ci < 0) continue;
-    obj[part.slice(0, ci).trim()] = parseScalar(part.slice(ci + 1));
-  }
-  return obj;
-}
-
-// Turn a block's raw text into meaningful {indent, content} nodes (comment-stripped, blank-dropped).
-function toNodes(text) {
-  const nodes = [];
-  for (const rawLine of text.split("\n")) {
-    const line = stripComment(rawLine);
-    if (line.trim() === "") continue;
-    const indent = line.length - line.trimStart().length;
-    nodes.push({ indent, content: line.trim() });
-  }
-  return nodes;
-}
-
-// Recursively build a nested map from indentation nodes (tolerant mini-YAML for 2-space maps).
-function buildMap(nodes, start, indent) {
-  const obj = {};
-  let i = start;
-  while (i < nodes.length) {
-    const node = nodes[i];
-    if (node.indent < indent) break;
-    if (node.indent > indent) { i++; continue; }
-    const ci = node.content.indexOf(":");
-    if (ci < 0) { i++; continue; }
-    const key = node.content.slice(0, ci).trim();
-    const rest = node.content.slice(ci + 1).trim();
-    if (rest === "") {
-      if (i + 1 < nodes.length && nodes[i + 1].indent > indent) {
-        const [child, next] = buildMap(nodes, i + 1, nodes[i + 1].indent);
-        obj[key] = child;
-        i = next;
-      } else {
-        obj[key] = {};
-        i++;
-      }
-    } else {
-      obj[key] = parseScalar(rest);
-      i++;
-    }
+// Parse any corpus color string (oklch / #rrggbb / #rrggbbaa / rgb() / rgba()) into a typed DTCG color $value.
+function parseColorCss(css) {
+  const s = css.trim();
+  let m = /^oklch\(\s*([-\d.]+)\s+([-\d.]+)\s+([-\d.]+)\s*(?:\/\s*([\d.]+%?)\s*)?\)$/.exec(s);
+  if (m) {
+    const value = { colorSpace: "oklch", components: [parseFloat(m[1]), parseFloat(m[2]), parseFloat(m[3])] };
+    if (m[4] !== undefined) value.alpha = m[4].endsWith("%") ? round5(parseFloat(m[4]) / 100) : parseFloat(m[4]);
+    return value;
+  }
+  m = /^#([0-9a-fA-F]{6})([0-9a-fA-F]{2})?$/.exec(s);
+  if (m) {
+    const bytes = [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16));
+    const value = { colorSpace: "srgb", components: bytes.map((b) => round5(b / 255)), hex: `#${m[1].toLowerCase()}` };
+    if (m[2] !== undefined) value.alpha = round5(parseInt(m[2], 16) / 255);
+    return value;
   }
-  return [obj, i];
+  m = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/.exec(s);
+  if (m) {
+    const bytes = [m[1], m[2], m[3]].map(Number);
+    const hex = "#" + bytes.map((b) => b.toString(16).padStart(2, "0")).join("");
+    const value = { colorSpace: "srgb", components: bytes.map((b) => round5(b / 255)), hex };
+    if (m[4] !== undefined) value.alpha = parseFloat(m[4]);
+    return value;
+  }
+  throw new Error(`unparseable color: ${JSON.stringify(css)}`);
 }
 
-// Parse a fenced-block body into a nested object via the mini-YAML parser.
-function parseBlock(text) {
-  const [obj] = buildMap(toNodes(text), 0, 0);
-  return obj;
+// Parse a tracking string ("0" | "0em" | "-0.015em") into its em-multiplier number.
+function parseTrackingCss(css) {
+  const m = /^([+-]?\d*\.?\d+)(em)?$/.exec(css.trim());
+  if (!m) throw new Error(`unparseable tracking: ${JSON.stringify(css)}`);
+  return parseFloat(m[1]);
 }
 
-// Extract the body of the fenced block whose info-string ends with the given label (e.g. "design-primitives").
-function extractFencedBlock(source, label) {
-  const lines = source.split("\n");
-  const openRe = new RegExp("^`{3,}\\s*yaml\\s+" + label + "\\s*$");
-  const closeRe = /^`{3,}\s*$/;
-  let capturing = false;
-  const body = [];
-  for (const line of lines) {
-    if (!capturing) {
-      if (openRe.test(line.trim())) capturing = true;
-      continue;
+// Parse "cubic-bezier(x1,y1,x2,y2)" into its four numbers.
+function parseCubicBezierCss(css) {
+  const m = /^cubic-bezier\(\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*,\s*([-\d.]+)\s*\)$/.exec(css.trim());
+  if (!m) throw new Error(`unparseable cubic-bezier: ${JSON.stringify(css)}`);
+  return [1, 2, 3, 4].map((i) => parseFloat(m[i]));
+}
+
+// Parse a font stack string into its array of unquoted family names.
+function parseFontStackCss(css) {
+  return splitTopLevel(css, ",").map((p) => unquote(p)).filter((p) => p !== "");
+}
+
+// Parse a ramp letterSpacing string ("+0.02em" | "-0.28px" | "0") into an em multiplier, px scaled by fontSize.
+function parseLetterSpacingCss(css, fontSizePx) {
+  const m = /^([+-]?\d*\.?\d+)(em|px)?$/.exec(css.trim());
+  if (!m) throw new Error(`unparseable letterSpacing: ${JSON.stringify(css)}`);
+  const n = parseFloat(m[1]);
+  return m[2] === "px" ? round5(n / fontSizePx) : n;
+}
+
+function parseDimensionCss(css) {
+  const m = /^(-?\d*\.?\d+)px$/.exec(css.trim());
+  if (!m) throw new Error(`unparseable dimension: ${JSON.stringify(css)}`);
+  return { value: parseFloat(m[1]), unit: "px" };
+}
+
+function parseDurationCss(css) {
+  const m = /^(\d*\.?\d+)ms$/.exec(css.trim());
+  if (!m) throw new Error(`unparseable duration: ${JSON.stringify(css)}`);
+  return { value: parseFloat(m[1]), unit: "ms" };
+}
+
+function parseNumberCss(css) {
+  const n = parseFloat(css.trim());
+  if (Number.isNaN(n) || !/^[+-]?\d*\.?\d+$/.test(css.trim())) throw new Error(`unparseable number: ${JSON.stringify(css)}`);
+  return n;
+}
+
+// ---------------------------------------------------------------------------
+// Serialization — the schema's deterministic byte forms for tokens without preserved .css
+// ---------------------------------------------------------------------------
+
+// Serialize a concrete $value to its deterministic CSS byte form (the fallback when .css is absent).
+function serializeValue(type, value) {
+  if (type === "dimension" || type === "duration") return `${value.value}${value.unit}`;
+  if (type === "number" || type === "fontWeight") return String(value);
+  if (type === "cubicBezier") return `cubic-bezier(${value.join(", ")})`;
+  if (type === "fontFamily") {
+    return (Array.isArray(value) ? value : [value]).map((f) => (/\s/.test(f) ? `"${f}"` : f)).join(", ");
+  }
+  if (type === "color") {
+    if (value.colorSpace === "srgb" && value.hex) return value.hex;
+    return `oklch(${value.components.join(" ")}${value.alpha !== undefined ? ` / ${value.alpha}` : ""})`;
+  }
+  return String(value);
+}
+
+// ---------------------------------------------------------------------------
+// Artifact loading & resolution (SCHEMA.md resolver section — deterministic order)
+// ---------------------------------------------------------------------------
+
+// True when a $value is an alias reference string ("{path.to.token}").
+function isAlias(v) {
+  return typeof v === "string" && /^\{[^}]+\}$/.test(v);
+}
+
+// True when a node is a token (an object carrying $type).
+function isToken(node) {
+  return node !== null && typeof node === "object" && !Array.isArray(node) && "$type" in node;
+}
+
+// Collect every token in a tree as a path → token map ($-prefixed keys are metadata, not groups).
+function collectTokens(root) {
+  const tokens = new Map();
+  const walk = (node, path) => {
+    if (isToken(node)) { tokens.set(path.join("."), node); return; }
+    if (node !== null && typeof node === "object" && !Array.isArray(node)) {
+      for (const [k, v] of Object.entries(node)) if (!k.startsWith("$")) walk(v, [...path, k]);
     }
-    if (closeRe.test(line.trim())) return body.join("\n");
-    body.push(line);
-  }
-  return capturing ? body.join("\n") : null;
-}
-
-// Parse the leading --- frontmatter into a flat object.
-function parseFrontmatter(source) {
-  const m = /^---\s*\n([\s\S]*?)\n---\s*(\n|$)/.exec(source);
-  if (!m) return null;
-  const obj = {};
-  for (const rawLine of m[1].split("\n")) {
-    const line = stripComment(rawLine);
-    const ci = line.indexOf(":");
-    if (ci < 0) continue;
-    obj[line.slice(0, ci).trim()] = unquote(line.slice(ci + 1));
-  }
-  return obj;
-}
-
-// Parse a whole design.md into its three parsed parts.
-function parseDesignMd(source) {
-  const frontmatter = parseFrontmatter(source);
-  const primitivesText = extractFencedBlock(source, "design-primitives");
-  const manifestText = extractFencedBlock(source, "lever-manifest");
-  return {
-    frontmatter,
-    primitives: primitivesText == null ? null : parseBlock(primitivesText),
-    manifest: manifestText == null ? null : parseBlock(manifestText),
   };
+  walk(root, []);
+  return tokens;
+}
+
+// Overlay one modifier file onto the base at token-path granularity; an overlay may only
+// override paths that exist in the base, never introduce new ones.
+function overlayTree(base, overlay, file, errors, path = []) {
+  for (const [key, value] of Object.entries(overlay)) {
+    if (key.startsWith("$")) continue;
+    const here = [...path, key];
+    if (!(key in base)) {
+      errors.push(`rule 1 — resolver overlay ${file}: introduces ${here.join(".")}, absent from the base set`);
+      continue;
+    }
+    if (isToken(value) || isToken(base[key]) || typeof value !== "object" || value === null) {
+      base[key] = value;
+    } else {
+      overlayTree(base[key], value, file, errors, here);
+    }
+  }
 }
 
-// True when a parsed leaf is a bare "hint:" pending judgment.
-function isHint(value) {
-  return typeof value === "string" && value.trim().startsWith("hint:");
+// Concatenate a later set file onto the accumulated base (a later file overrides per token path; new paths are legal here).
+function concatTree(base, add) {
+  for (const [key, value] of Object.entries(add)) {
+    if (key.startsWith("$")) continue;
+    if (!(key in base) || isToken(value) || isToken(base[key]) || typeof value !== "object" || value === null) {
+      base[key] = value;
+    } else {
+      concatTree(base[key], value);
+    }
+  }
 }
 
-// True when a leaf is present as a non-empty scalar.
-function isFilled(value) {
-  return typeof value === "string" && value.trim() !== "";
+// Load and resolve one artifact directory: parse files (rule 1), concatenate sets, build one
+// resolved view per theme context. Returns null when the artifact is unreadable.
+function loadArtifact(dir, errors) {
+  const readJson = (name) => {
+    const path = join(dir, name);
+    if (!existsSync(path)) { errors.push(`rule 1 — ${name}: missing`); return null; }
+    try {
+      return JSON.parse(readFileSync(path, "utf8"));
+    } catch (e) {
+      errors.push(`rule 1 — ${name}: unparseable JSON (${e.message})`);
+      return null;
+    }
+  };
+
+  const base = readJson("design.tokens.json");
+  const resolver = readJson("design.resolver.json");
+  if (base === null || resolver === null) return null;
+
+  if (resolver.schema !== "design-resolver/v1") {
+    errors.push(`rule 1 — design.resolver.json: schema must be "design-resolver/v1" (found ${JSON.stringify(resolver.schema)})`);
+  }
+  if (!Array.isArray(resolver.sets) || resolver.sets.length === 0) {
+    errors.push("rule 1 — design.resolver.json: sets must be a non-empty array");
+    return null;
+  }
+  const themeModifier = (resolver.modifiers ?? []).find((m) => m?.name === "theme");
+  for (const m of resolver.modifiers ?? []) {
+    if (m?.name !== "theme") errors.push(`rule 1 — design.resolver.json: unknown modifier ${JSON.stringify(m?.name)} (exactly one modifier today: theme)`);
+  }
+  if (!themeModifier) {
+    errors.push("rule 1 — design.resolver.json: missing the theme modifier");
+    return null;
+  }
+  if (themeModifier.default !== "light") errors.push("rule 1 — design.resolver.json: theme default must be light (light-first)");
+  if (!Array.isArray(themeModifier.contexts?.light) || themeModifier.contexts.light.length !== 0) {
+    errors.push("rule 1 — design.resolver.json: the light context must be the empty overlay [] (the base set is the light rendering)");
+  }
+
+  // Every file the resolver references exists beside it — and parses.
+  const files = new Map([["design.tokens.json", base]]);
+  const referenced = new Set(["design.tokens.json"]);
+  const loadReferenced = (name, where) => {
+    referenced.add(name);
+    if (files.has(name)) return;
+    const doc = readJson(name);
+    if (doc === null) errors.push(`rule 1 — resolver ${where} references ${name}`);
+    else files.set(name, doc);
+  };
+  for (const set of resolver.sets) {
+    for (const name of set?.values ?? []) loadReferenced(name, `set "${set.name}"`);
+  }
+  for (const [context, names] of Object.entries(themeModifier.contexts ?? {})) {
+    for (const name of names ?? []) loadReferenced(name, `theme context "${context}"`);
+  }
+
+  // The dark file exists exactly when the resolver's dark context names it.
+  const darkNamed = (themeModifier.contexts?.dark ?? []).includes("design.tokens.dark.json");
+  const darkExists = existsSync(join(dir, "design.tokens.dark.json"));
+  if (darkNamed && !darkExists) errors.push("rule 1 — design.tokens.dark.json: named by the resolver's dark context but absent");
+  if (!darkNamed && darkExists) errors.push("rule 1 — design.tokens.dark.json: present but not named by a resolver dark context");
+
+  // Resolution: concatenate the set files in array order, then one view per theme context.
+  const merged = {};
+  for (const set of resolver.sets) {
+    for (const name of set?.values ?? []) {
+      if (files.has(name)) concatTree(merged, files.get(name));
+    }
+  }
+  const views = new Map();
+  for (const [context, names] of Object.entries(themeModifier.contexts ?? {})) {
+    const view = structuredClone(merged);
+    for (const name of names ?? []) {
+      if (files.has(name)) overlayTree(view, files.get(name), name, errors);
+    }
+    views.set(context, view);
+  }
+
+  return { base, resolver, files, views, payload: base?.$extensions?.[EXT] };
+}
+
+// Follow an alias chain to its final concrete token; records rule-6 errors (dangling refs, cycles, type mismatches).
+function resolveAlias(ref, tokens, expectedType, context, errors) {
+  const seen = new Set();
+  let cur = ref;
+  while (isAlias(cur)) {
+    const path = cur.slice(1, -1);
+    if (seen.has(path)) { errors.push(`rule 6 — ${context}: alias cycle through {${path}}`); return null; }
+    seen.add(path);
+    const target = tokens.get(path);
+    if (!target) { errors.push(`rule 6 — ${context}: alias {${path}} does not resolve`); return null; }
+    if (expectedType && target.$type !== expectedType) {
+      errors.push(`rule 6 — ${context}: alias {${path}} resolves to $type ${target.$type} (want ${expectedType})`);
+      return null;
+    }
+    if (!isAlias(target.$value)) return target;
+    cur = target.$value;
+  }
+  return null;
+}
+
+// The emitted CSS string for a token path: follow aliases, prefer the preserved .css, fall back
+// to the schema's deterministic serialization.
+function cssFor(path, tokens, errors) {
+  const token = tokens.get(path);
+  if (!token) { errors.push(`emit — ${path}: token not found`); return ""; }
+  let target = token;
+  if (isAlias(token.$value)) {
+    target = resolveAlias(token.$value, tokens, token.$type, path, errors);
+    if (!target) return "";
+  }
+  const css = target.$extensions?.[EXT]?.css;
+  if (typeof css === "string") return css;
+  return serializeValue(target.$type, target.$value);
 }
 
-// True when an array of numeric-ish values is strictly ascending.
-function isAscending(arr) {
-  const nums = arr.map((v) => parseFloat(v));
-  if (nums.some((n) => Number.isNaN(n))) return false;
-  for (let i = 1; i < nums.length; i++) if (!(nums[i] > nums[i - 1])) return false;
-  return true;
+// ---------------------------------------------------------------------------
+// Validation — SCHEMA.md rules 1–12 (rule 12 is enforced at emit time)
+// ---------------------------------------------------------------------------
+
+// True when a token's $value is absent or vacuously empty.
+function isEmptyValue(v) {
+  return v === undefined || v === null || v === "" || (Array.isArray(v) && v.length === 0);
 }
 
-// Run the coverage gate; return { errors: string[] }.
-function runCoverageGate(doc) {
-  const errors = [];
-  const { frontmatter, primitives, manifest } = doc;
-
-  // Rule 1 — frontmatter with schema and legal provenance.
-  if (!frontmatter) {
-    errors.push("frontmatter: missing --- frontmatter block");
-  } else {
-    if (frontmatter.schema !== "design-md/v1") {
-      errors.push(`frontmatter: schema must be "design-md/v1" (found ${frontmatter.schema ?? "nothing"})`);
+// Verify a preserved-css color token: parse-back equality plus the srgb hex round-trip.
+function verifyColorParseBack(name, token, errors) {
+  const css = token.$extensions?.[EXT]?.css;
+  if (typeof css !== "string" || isAlias(token.$value)) return;
+  let reparsed;
+  try { reparsed = parseColorCss(css); } catch (e) { errors.push(`rule 9 — ${name}: ${e.message}`); return; }
+  if (JSON.stringify(reparsed) !== JSON.stringify(token.$value)) {
+    errors.push(`rule 9 — ${name}: parse-back mismatch — css ${JSON.stringify(css)} → ${JSON.stringify(reparsed)} != $value ${JSON.stringify(token.$value)}`);
+    return;
+  }
+  if (token.$value.colorSpace === "srgb") {
+    const viaHex = parseColorCss(token.$value.hex);
+    if (JSON.stringify(viaHex.components) !== JSON.stringify(token.$value.components)) {
+      errors.push(`rule 9 — ${name}: srgb components do not round-trip through hex ${token.$value.hex}`);
     }
-    if (!LEGAL_PROVENANCE.includes(frontmatter.provenance)) {
-      errors.push(`frontmatter: provenance must be one of ${LEGAL_PROVENANCE.join("|")} (found ${frontmatter.provenance ?? "nothing"})`);
+  }
+}
+
+// Rule 9 for one non-color token carrying a preserved string .css: parsing it must reproduce $value.
+function verifyScalarParseBack(name, token, css, errors) {
+  if (isAlias(token.$value)) return; // an aliased token takes the target's .css; rule 6 owns alias integrity
+  try {
+    if (token.$type === "cubicBezier") {
+      if (JSON.stringify(parseCubicBezierCss(css)) !== JSON.stringify(token.$value)) errors.push(`rule 9 — ${name}: css ${JSON.stringify(css)} != $value`);
+    } else if (token.$type === "fontFamily") {
+      if (JSON.stringify(parseFontStackCss(css)) !== JSON.stringify(token.$value)) errors.push(`rule 9 — ${name}: css ${JSON.stringify(css)} != $value`);
+    } else if (token.$type === "number") {
+      if (parseTrackingCss(css) !== token.$value) errors.push(`rule 9 — ${name}: css ${JSON.stringify(css)} != $value ${token.$value}`);
+    } else if (token.$type === "dimension") {
+      if (JSON.stringify(parseDimensionCss(css)) !== JSON.stringify(token.$value)) errors.push(`rule 9 — ${name}: css ${JSON.stringify(css)} != $value`);
+    } else if (token.$type === "duration") {
+      if (JSON.stringify(parseDurationCss(css)) !== JSON.stringify(token.$value)) errors.push(`rule 9 — ${name}: css ${JSON.stringify(css)} != $value`);
+    } else if (token.$type === "fontWeight") {
+      if (parseNumberCss(css) !== token.$value) errors.push(`rule 9 — ${name}: css ${JSON.stringify(css)} != $value ${token.$value}`);
     }
+  } catch (e) {
+    errors.push(`rule 9 — ${name}: ${e.message}`);
   }
+}
 
-  // Rule 2 — both machine blocks present and parseable.
-  if (!primitives) errors.push("block: missing or unparseable `yaml design-primitives` block");
-  if (!manifest) errors.push("block: missing or unparseable `yaml lever-manifest` block");
-  if (!primitives || !manifest) return { errors };
+// Run the full coverage gate (rules 1–11) over one artifact directory; returns everything emit needs.
+function runCheck(dir, theme) {
+  const errors = [];
+  const artifact = loadArtifact(dir, errors);
+  if (!artifact) return { errors };
+  const { base, files, views, payload } = artifact;
 
-  // Rule 3 — every primitive assigned or hinted.
-  for (const key of PRIMITIVES) {
-    const v = primitives[key];
-    if (v === undefined) errors.push(`missing primitive: ${key}`);
-    else if (!isFilled(v)) errors.push(`empty primitive: ${key}`);
+  if (!views.has(theme)) {
+    errors.push(`rule 1 — resolver: --theme ${theme} requested but the resolver carries no ${theme} context`);
+    return { errors };
   }
 
-  // Rule 4 — dials, tier, and traits.
-  if (!LEGAL_VERBOSITY.includes(primitives.verbosity)) {
-    errors.push(`dial verbosity: must be one of ${LEGAL_VERBOSITY.join("|")} (found ${primitives.verbosity ?? "nothing"})`);
+  // Rule 2 — the file-level payload on the base root.
+  if (!payload || typeof payload !== "object") {
+    errors.push(`rule 2 — payload: missing $extensions["${EXT}"] on the base file's root group`);
+    return { errors };
   }
-  if (!LEGAL_FEEDBACK.includes(primitives.feedback)) {
-    errors.push(`dial feedback: must be one of ${LEGAL_FEEDBACK.join("|")} (found ${primitives.feedback ?? "nothing"})`);
+  if (payload.schema !== "design-tokens/v1") errors.push(`rule 2 — payload.schema: must be "design-tokens/v1" (found ${JSON.stringify(payload.schema)})`);
+  if (payload.dtcg !== "2025.10") errors.push(`rule 2 — payload.dtcg: must be "2025.10" (found ${JSON.stringify(payload.dtcg)})`);
+  if (typeof payload.product !== "string" || payload.product.trim() === "") errors.push("rule 2 — payload.product: missing or empty");
+  if (!LEGAL_PROVENANCE.includes(payload.provenance)) errors.push(`rule 2 — payload.provenance: must be one of ${LEGAL_PROVENANCE.join("|")} (found ${JSON.stringify(payload.provenance)})`);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(payload.sourced ?? "")) errors.push(`rule 2 — payload.sourced: must be an ISO date (found ${JSON.stringify(payload.sourced)})`);
+  if (!LEGAL_VERBOSITY.includes(payload.verbosity)) errors.push(`rule 2 — payload.verbosity: must be one of ${LEGAL_VERBOSITY.join("|")} (found ${JSON.stringify(payload.verbosity)})`);
+  if (!LEGAL_FEEDBACK.includes(payload.feedback)) errors.push(`rule 2 — payload.feedback: must be one of ${LEGAL_FEEDBACK.join("|")} (found ${JSON.stringify(payload.feedback)})`);
+  if (!LEGAL_DENSITY.includes(payload["density-tier"])) errors.push(`rule 2 — payload.density-tier: must be one of ${LEGAL_DENSITY.join("|")} (found ${JSON.stringify(payload["density-tier"])})`);
+  if (!Array.isArray(payload["product-traits"]) || payload["product-traits"].length === 0) errors.push("rule 2 — payload.product-traits: must be a non-empty array");
+  const lm = payload["lever-manifest"];
+  for (const key of MANIFEST_KEYS) {
+    if (lm?.[key] === undefined) errors.push(`rule 2 — payload.lever-manifest.${key}: missing`);
   }
-  if (!LEGAL_DENSITY.includes(primitives["density-tier"])) {
-    errors.push(`density-tier: must be one of ${LEGAL_DENSITY.join("|")} (found ${primitives["density-tier"] ?? "nothing"})`);
+
+  const lightView = views.get("light");
+  const lightTokens = collectTokens(lightView);
+
+  // Rule 3 — all 26 primitives present with the exact $type, each assigned or hinted.
+  for (const [key, type] of PRIMITIVE_TYPES) {
+    const t = lightView.primitive?.[key];
+    if (!isToken(t)) { errors.push(`rule 3 — primitive.${key}: missing`); continue; }
+    if (t.$type !== type) errors.push(`rule 3 — primitive.${key}: $type ${JSON.stringify(t.$type)} (want ${type})`);
+    if (isEmptyValue(t.$value)) errors.push(`rule 3 — primitive.${key}: empty $value`);
   }
-  const traits = primitives["product-traits"];
-  if (!Array.isArray(traits) || traits.length === 0) {
-    errors.push("product-traits: must be a non-empty list");
+
+  // Rule 4 — all 34 color roles present, typed color, legal colorSpace, .css present (via alias when aliased).
+  for (const role of ALL_TOKENS) {
+    const t = lightView.color?.[role];
+    if (!isToken(t)) { errors.push(`rule 4 — color.${role}: missing`); continue; }
+    if (t.$type !== "color") { errors.push(`rule 4 — color.${role}: $type ${JSON.stringify(t.$type)} (want color)`); continue; }
+    const target = isAlias(t.$value) ? resolveAlias(t.$value, lightTokens, "color", `color.${role}`, []) : t;
+    if (!target) continue; // dangling alias — rule 6 reports it
+    if (!["oklch", "srgb"].includes(target.$value?.colorSpace)) errors.push(`rule 4 — color.${role}: colorSpace ${JSON.stringify(target.$value?.colorSpace)} (want oklch|srgb)`);
+    if (typeof target.$extensions?.[EXT]?.css !== "string") errors.push(`rule 4 — color.${role}: missing preserved .css`);
   }
 
-  // Rule 5 — every color token valued under color-tokens.light.
-  const light = manifest["color-tokens"] && manifest["color-tokens"].light;
-  if (!light || typeof light !== "object") {
-    errors.push("color-tokens.light: missing color-tokens.light map");
-  } else {
-    for (const token of ALL_TOKENS) {
-      const v = light[token];
-      if (v === undefined) errors.push(`missing color token: ${token}`);
-      else if (!isFilled(v)) errors.push(`empty color token: ${token}`);
+  // Rule 5 — typography coverage: the three families and the six-step ramp with all five sub-values.
+  for (const fam of ["heading", "body", "mono"]) {
+    const t = lightView.typography?.family?.[fam];
+    if (!isToken(t) || t.$type !== "fontFamily") errors.push(`rule 5 — typography.family.${fam}: missing or not $type fontFamily`);
+  }
+  for (const step of RAMP_STEPS) {
+    const t = lightView.typography?.ramp?.[step];
+    if (!isToken(t) || t.$type !== "typography") { errors.push(`rule 5 — typography.ramp.${step}: missing or not $type typography`); continue; }
+    for (const sub of ["fontFamily", "fontSize", "fontWeight", "letterSpacing", "lineHeight"]) {
+      if (t.$value?.[sub] === undefined) errors.push(`rule 5 — typography.ramp.${step}.${sub}: missing sub-value`);
     }
   }
 
-  // Rule 6 — scales, motion, fonts, icons, accent-count.
-  const scaleCheck = (name, arr, allowAscending = true) => {
-    if (!Array.isArray(arr) || arr.length === 0) errors.push(`${name}: must be a non-empty list`);
-    else if (allowAscending && !isAscending(arr)) errors.push(`${name}: values must be ascending (found ${arr.join(", ")})`);
-  };
-  scaleCheck("spacing-scale", manifest["spacing-scale"]);
-  scaleCheck("radius-scale", manifest["radius-scale"]);
-
-  const shadow = manifest["shadow-levels"];
-  if (!Array.isArray(shadow) || shadow.length === 0) {
-    errors.push("shadow-levels: must be a non-empty list");
-  } else {
-    const ranks = shadow.map((s) => SHADOW_RANK[String(s).trim()]);
-    if (ranks.every((r) => r !== undefined)) {
-      for (let i = 1; i < ranks.length; i++) {
-        if (!(ranks[i] > ranks[i - 1])) { errors.push(`shadow-levels: must be ordered by increasing intensity (found ${shadow.join(", ")})`); break; }
+  // Rule 6 — alias integrity over every resolved context view (aliases resolve after overlay).
+  const SUB_TYPES = { fontFamily: "fontFamily", fontWeight: "fontWeight", letterSpacing: "number", fontSize: "dimension", lineHeight: "number" };
+  for (const [context, view] of views) {
+    const tokens = collectTokens(view);
+    const label = context === "light" ? "" : ` [${context}]`;
+    for (const [path, token] of tokens) {
+      if (isAlias(token.$value)) resolveAlias(token.$value, tokens, token.$type, `${path}${label}`, errors);
+      if (token.$type === "typography" && token.$value && typeof token.$value === "object") {
+        for (const [sub, want] of Object.entries(SUB_TYPES)) {
+          const v = token.$value[sub];
+          if (isAlias(v)) resolveAlias(v, tokens, want, `${path}.${sub}${label}`, errors);
+        }
       }
     }
   }
 
-  const motion = manifest.motion;
-  if (!motion || typeof motion !== "object") {
-    errors.push("motion: missing motion block");
-  } else {
-    scaleCheck("motion.durations", motion.durations);
-    if (!Array.isArray(motion.easings) || motion.easings.length === 0) errors.push("motion.easings: must be a non-empty list");
-  }
+  // Rule 7 — manifest scales.
+  if (lm && typeof lm === "object") {
+    const ascending = (arr) => arr.every((v, i) => i === 0 || v > arr[i - 1]);
+    for (const key of ["spacing-scale", "radius-scale"]) {
+      if (!Array.isArray(lm[key]) || lm[key].length === 0 || !ascending(lm[key])) errors.push(`rule 7 — lever-manifest.${key}: must be non-empty ascending (found ${JSON.stringify(lm[key])})`);
+    }
+    if (!Array.isArray(lm.motion?.durations) || lm.motion.durations.length === 0 || !ascending(lm.motion.durations)) errors.push(`rule 7 — lever-manifest.motion.durations: must be non-empty ascending (found ${JSON.stringify(lm.motion?.durations)})`);
+    if (!Array.isArray(lm.motion?.easings) || lm.motion.easings.length === 0) errors.push("rule 7 — lever-manifest.motion.easings: must be non-empty");
+    const shadows = lm["shadow-levels"];
+    const ranks = (Array.isArray(shadows) ? shadows : []).map((s) => SHADOW_RANK[s]);
+    if (ranks.length === 0 || ranks.some((r) => r === undefined) || !ascending(ranks)) {
+      errors.push(`rule 7 — lever-manifest.shadow-levels: must be non-empty, drawn from ${Object.keys(SHADOW_RANK).join(" ")}, strictly increasing (found ${JSON.stringify(shadows)})`);
+    }
+    if (typeof lm.icons?.family !== "string" || lm.icons.family === "") errors.push("rule 7 — lever-manifest.icons.family: missing or empty");
+    if (!(lm["accent-count"] >= 1)) errors.push(`rule 7 — lever-manifest.accent-count: must be >= 1 (found ${JSON.stringify(lm?.["accent-count"])})`);
 
-  const fonts = manifest.fonts;
-  if (!fonts || typeof fonts !== "object") {
-    errors.push("fonts: missing fonts block");
-  } else {
-    if (!isFilled(fonts.sans)) errors.push("fonts.sans: missing or empty");
-    if (!isFilled(fonts.mono)) errors.push("fonts.mono: missing or empty");
+    // Rule 8 — the look's own base values sit on its own allowlist.
+    const radius = lightView.primitive?.radius?.$value?.value;
+    if (Array.isArray(lm["radius-scale"]) && radius !== undefined && !lm["radius-scale"].includes(radius)) {
+      errors.push(`rule 8 — primitive.radius: ${radius} not on lever-manifest.radius-scale`);
+    }
+    for (const key of ["duration-fast", "duration-normal", "duration-slow"]) {
+      const ms = lightView.primitive?.[key]?.$value?.value;
+      if (Array.isArray(lm.motion?.durations) && ms !== undefined && !lm.motion.durations.includes(ms)) {
+        errors.push(`rule 8 — primitive.${key}: ${ms} not in lever-manifest.motion.durations`);
+      }
+    }
+    const ease = lightView.primitive?.["ease-default"];
+    if (isToken(ease) && Array.isArray(lm.motion?.easings)) {
+      const easeCss = typeof ease.$extensions?.[EXT]?.css === "string" ? ease.$extensions[EXT].css : serializeValue("cubicBezier", ease.$value);
+      if (!lm.motion.easings.includes(easeCss)) errors.push(`rule 8 — primitive.ease-default: ${JSON.stringify(easeCss)} not in lever-manifest.motion.easings`);
+    }
   }
 
-  const icons = manifest.icons;
-  if (!icons || typeof icons !== "object") {
-    errors.push("icons: missing icons block");
-  } else {
-    if (!isFilled(icons.family)) errors.push("icons.family: missing or empty");
-    if (icons.stroke === undefined || String(icons.stroke).trim() === "") errors.push("icons.stroke: missing or empty");
+  // Rule 9 — parse-back for every token carrying a preserved .css, per file.
+  for (const [fileName, doc] of files) {
+    const prefix = fileName === "design.tokens.json" ? "" : `${fileName} `;
+    for (const [path, token] of collectTokens(doc)) {
+      const css = token.$extensions?.[EXT]?.css;
+      if (css === undefined) continue;
+      const name = `${prefix}${path}`;
+      if (token.$type === "color") {
+        verifyColorParseBack(name, token, errors);
+      } else if (typeof css === "string") {
+        verifyScalarParseBack(name, token, css, errors);
+      } else if (token.$type === "typography" && typeof css === "object" && css !== null) {
+        if (typeof css.letterSpacing === "string" && typeof token.$value?.letterSpacing === "number" && typeof token.$value?.fontSize?.value === "number") {
+          try {
+            const reparsed = parseLetterSpacingCss(css.letterSpacing, token.$value.fontSize.value);
+            if (reparsed !== token.$value.letterSpacing) errors.push(`rule 9 — ${name}: letterSpacing css ${css.letterSpacing} → ${reparsed} != ${token.$value.letterSpacing}`);
+          } catch (e) {
+            errors.push(`rule 9 — ${name}: ${e.message}`);
+          }
+        }
+      }
+    }
   }
 
-  const accent = parseFloat(manifest["accent-count"]);
-  if (Number.isNaN(accent) || accent < 1) errors.push(`accent-count: must be >= 1 (found ${manifest["accent-count"] ?? "nothing"})`);
+  // Rule 10 — the dark file, when present, carries exactly the 34-role color group and nothing else.
+  const darkDoc = files.get("design.tokens.dark.json");
+  if (darkDoc !== undefined) {
+    const rootKeys = Object.keys(darkDoc).filter((k) => !k.startsWith("$"));
+    if (rootKeys.length !== 1 || rootKeys[0] !== "color") errors.push(`rule 10 — design.tokens.dark.json: root groups ${JSON.stringify(rootKeys)} (want exactly ["color"])`);
+    if (darkDoc.$extensions?.[EXT] !== undefined) errors.push("rule 10 — design.tokens.dark.json: carries a payload (the base file is the payload's single carrier)");
+    for (const role of ALL_TOKENS) {
+      const t = darkDoc.color?.[role];
+      if (!isToken(t)) { errors.push(`rule 10 — dark color.${role}: missing`); continue; }
+      if (t.$type !== "color") { errors.push(`rule 10 — dark color.${role}: $type ${JSON.stringify(t.$type)} (want color)`); continue; }
+      if (isAlias(t.$value)) continue; // resolves post-overlay; rules 4/6 cover it on the dark view
+      if (!["oklch", "srgb"].includes(t.$value?.colorSpace)) errors.push(`rule 10 — dark color.${role}: colorSpace ${JSON.stringify(t.$value?.colorSpace)} (want oklch|srgb)`);
+      if (typeof t.$extensions?.[EXT]?.css !== "string") errors.push(`rule 10 — dark color.${role}: missing preserved .css`);
+    }
+    for (const role of Object.keys(darkDoc.color ?? {})) {
+      if (!ALL_TOKENS.includes(role)) errors.push(`rule 10 — dark color.${role}: not a legal role`);
+    }
+  }
 
-  return { errors };
-}
+  // Rule 11 — only the eight legal $type values appear, in any file.
+  for (const [fileName, doc] of files) {
+    const prefix = fileName === "design.tokens.json" ? "" : `${fileName} `;
+    for (const [path, token] of collectTokens(doc)) {
+      if (!LEGAL_TYPES.includes(token.$type)) errors.push(`rule 11 — ${prefix}${path}: illegal $type ${JSON.stringify(token.$type)}`);
+    }
+  }
 
-// Collect every bare "hint:" leaf across primitives, dials, and color tokens for the emit refusal.
-function collectBareHints(doc) {
+  // Rule 12 inventory — every token still carrying a hint (passes --check; --emit refuses).
   const hints = [];
-  const { primitives, manifest } = doc;
-  if (primitives) {
-    for (const key of [...PRIMITIVES, "verbosity", "feedback", "density-tier"]) {
-      if (isHint(primitives[key])) hints.push({ key, text: primitives[key].trim().slice(5).trim() });
+  for (const [fileName, doc] of files) {
+    const prefix = fileName === "design.tokens.json" ? "" : `${fileName} `;
+    for (const [path, token] of collectTokens(doc)) {
+      const hint = token.$extensions?.[EXT]?.hint;
+      if (hint !== undefined) hints.push({ key: `${prefix}${path}`, text: String(hint) });
     }
   }
-  const light = manifest && manifest["color-tokens"] && manifest["color-tokens"].light;
-  if (light) {
-    for (const token of ALL_TOKENS) {
-      if (isHint(light[token])) hints.push({ key: `color-tokens.light.${token}`, text: light[token].trim().slice(5).trim() });
-    }
+
+  return { errors, payload, views, hints, hasDark: files.has("design.tokens.dark.json") };
+}
+
+// ---------------------------------------------------------------------------
+// Emitter feed — flatten the resolved views into the value map the emitters consume
+// ---------------------------------------------------------------------------
+
+// Assemble the emitters' document: 26 primitive CSS strings + the payload dials, and the
+// 34-role CSS string map per theme (preferring each token's preserved .css).
+function buildEmitterDoc(views, payload, errors) {
+  const lightTokens = collectTokens(views.get("light"));
+  const primitives = {};
+  for (const key of PRIMITIVES) primitives[key] = cssFor(`primitive.${key}`, lightTokens, errors);
+  primitives.verbosity = payload.verbosity;
+  primitives.feedback = payload.feedback;
+  primitives["density-tier"] = payload["density-tier"];
+
+  const colorTokens = { light: {} };
+  for (const role of ALL_TOKENS) colorTokens.light[role] = cssFor(`color.${role}`, lightTokens, errors);
+
+  if (views.has("dark")) {
+    const darkTokens = collectTokens(views.get("dark"));
+    colorTokens.dark = {};
+    for (const role of ALL_TOKENS) colorTokens.dark[role] = cssFor(`color.${role}`, darkTokens, errors);
   }
-  return hints;
+
+  return { primitives, manifest: { "color-tokens": colorTokens } };
 }
 
+// ---------------------------------------------------------------------------
+// Emitters (values come from the token artifact; non-comment output is v1 byte-identical)
+// ---------------------------------------------------------------------------
+
 // Derive a rosterless data-style slug from the product name.
 function slugify(name) {
   return String(name || "project").toLowerCase().trim()
@@ -388,28 +666,48 @@ function buildStyleBlockLines(primitives) {
   return lines.join("\n");
 }
 
-// Emit the full src/styles/personality.css content for a passing document.
-function emitPersonalityCss(doc, slug) {
+// Emit the full src/styles/personality.css content for a passing artifact.
+function emitPersonalityCss(doc, slug, meta) {
   const p = doc.primitives;
   const light = doc.manifest["color-tokens"].light;
   const density = p["density-tier"];
   const verbosity = p.verbosity;
   const feedback = p.feedback;
 
+  const dark = doc.manifest["color-tokens"].dark;
+
   const semanticLines = SEMANTIC_TOKENS.map((t) => `  --${t}: ${light[t]};`).join("\n");
   const substrateLines = SUBSTRATE_TOKENS.map((t) => `  --${t}: ${light[t]};`).join("\n");
   const styleLines = buildStyleBlockLines(p);
 
+  const darkSection = dark
+    ? `/* ── Dark theme — OPT-IN ONLY (this look ships a dark overlay). ──
+ * design.tokens.dark.json remaps all 34 color tokens; <html data-theme="dark">
+ * opts in. Light stays the default. */
+[data-theme="dark"] {
+  /* semantic (17) */
+${SEMANTIC_TOKENS.map((t) => `  --${t}: ${dark[t]};`).join("\n")}
+  /* substrate (17, the D6 set) — popover/secondary/chart/sidebar the library consumes */
+${SUBSTRATE_TOKENS.map((t) => `  --${t}: ${dark[t]};`).join("\n")}
+}`
+    : `/* ── Dark theme — OPT-IN ONLY. ──
+ * Emitted only when the artifact ships a design.tokens.dark.json dark overlay.
+ * Light stays the default; this block never appears for a light-only project.
+[data-theme="dark"] {
+  --background: ...; --foreground: ...; ... all 34 tokens remapped ...
+} */`;
+
   return `/* src/styles/personality.css — operator-UI personality tokens (emitted; do not hand-edit).
  *
- * Active personality — code is the cache. There is no JSON sidecar; these values
- * and the <html data-*> attributes in index.html ARE the state. To change the look,
- * edit the resolved design.md and re-run derive-personality.mjs --emit.
+ * Active personality — code is the cache. These values and the <html data-*>
+ * attributes in index.html are emitted from the design-tokens artifact. To change
+ * the look, edit design.tokens.json and re-run derive-personality.mjs --emit.
  *   style:     ${slug}   (<html data-style="${slug}">)   — the project's own personality (rosterless)
  *   density:   ${density}   (<html data-density="${density}">)
  *   verbosity: ${verbosity}   (<html data-verbosity="${verbosity}">)
  *   feedback:  ${feedback}   (<html data-feedback="${feedback}">)
- *   theme:     light   (<html data-theme="light">)   — light is the default; dark is opt-in
+ *   theme:     ${meta.theme}   (<html data-theme="${meta.theme}">)   — light is the default; dark is opt-in
+ *   artifact:  design.tokens.json (resolved via design.resolver.json)   — provenance: ${meta.provenance}, sourced ${meta.sourced}
  *
  * Semantic-token doctrine: components name purpose (bg-card, text-foreground, border-border);
  * this file resolves those names to values. Components never use dark: prefixes or literal colors.
@@ -480,8 +778,8 @@ ${substrateLines}
 }
 
 /* ── The project personality: the single [data-style] block (D3, rosterless). ──
- * Named after the project — not a preset. This materializes the design.md
- * design-primitives block: all 26 primitives + the derived temporal. It is the
+ * Named after the project — not a preset. This materializes the artifact's
+ * primitive token group: all 26 primitives + the derived temporal. It is the
  * one block improve/extract rewrites. density-gap/inset are governed refs, so
  * the global tier and per-surface step still compose. */
 [data-style="${slug}"] {
@@ -508,16 +806,11 @@ ${styleLines}
  * A surface element carries data-density-step; it re-derives one step off the
  * inherited base. Reads --density-base-* (never itself) so it composes with the
  * tier and never absolutely overrides it. The recomputed --density-gap flows into
- * the library's p-*/gap-* through the @theme --spacing remap. */
+ * the library's p-* and gap-* through the @theme --spacing remap. */
 [data-density-step="tighter"] { --density-gap: calc(var(--density-base-gap) * 0.85); --density-inset: calc(var(--density-base-inset) * 0.85); }
 [data-density-step="looser"]  { --density-gap: calc(var(--density-base-gap) * 1.15); --density-inset: calc(var(--density-base-inset) * 1.15); }
 
-/* ── Dark theme — OPT-IN ONLY. ──
- * Emitted only when the design.md ships a lever-manifest color-tokens.dark map.
- * Light stays the default; this block never appears for a light-only project.
-[data-theme="dark"] {
-  --background: ...; --foreground: ...; ... all 34 tokens remapped ...
-} */
+${darkSection}
 
 /* ── Accessibility ── */
 @media (prefers-reduced-motion: reduce) {
@@ -548,7 +841,7 @@ function emitGlobalsCss(doc) {
 /* CASCADE CONTRACT 2: this four-step order is LOAD-BEARING. The library's
  * styles.css ships its own :root token defaults and its own @theme radius scale;
  * our @theme MUST come AFTER the import to win the radius scale and own every
- * mapping. rules/general.md (frontend section) states the same order — co-authority. */
+ * mapping. rules/frontend.md states the same order — co-authority. */
 @import "./personality.css";          /* 1. token source (must be first) */
 @import "tailwindcss";                /* 2. framework */
 @import "@nurix/components/styles.css"; /* 3. library (before our @theme) */
@@ -561,9 +854,9 @@ function emitGlobalsCss(doc) {
   --radius-lg: var(--radius);
   --radius-xl: calc(var(--radius) + 4px);
 
-  /* density remap — the single line that scales ALL library spacing. Every p-*/gap-*
-   * is calc(var(--spacing) × N); driving --spacing off --density-gap flows the tier
-   * AND the per-surface density step into the library's internals. */
+  /* density remap — the single line that scales ALL library spacing. Every p-* and
+   * gap-* is calc(var(--spacing) x N); driving --spacing off --density-gap flows the
+   * tier AND the per-surface density step into the library's internals. */
   --spacing: calc(0.25rem * var(--density-gap));
 
   /* shadow — alpha rides --shadow-intensity (matches the library's shadow-xs/sm/md/lg use) */
@@ -611,18 +904,18 @@ ${colorMaps}
 }
 
 // Emit the index.html <html> attribute snippet the shell must carry.
-function emitIndexHtmlAttributes(doc, slug) {
+function emitIndexHtmlAttributes(doc, slug, meta) {
   const p = doc.primitives;
   return `<!-- Personality state lives in these <html data-*> attributes — code is the cache.
-     There is no sidecar JSON. To change the look, edit the resolved design.md and
-     re-run derive-personality.mjs --emit; to nudge one axis, edit an attribute here. -->
+     The design-tokens artifact is the source. To change the look, edit design.tokens.json
+     and re-run derive-personality.mjs --emit; to nudge one axis, edit an attribute here. -->
 <html
   lang="en"
   data-style="${slug}"
   data-density="${p["density-tier"]}"
   data-verbosity="${p.verbosity}"
   data-feedback="${p.feedback}"
-  data-theme="light"
+  data-theme="${meta.theme}"
 >
 `;
 }
@@ -633,64 +926,71 @@ function writeFileEnsured(path, content) {
   writeFileSync(path, content);
 }
 
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
 // Print usage and exit non-zero.
 function usage() {
-  process.stderr.write("usage: derive-personality.mjs <design.md> [--check | --emit <outdir>]\n");
+  process.stderr.write("usage: derive-personality.mjs <artifact-dir> [--check | --emit <outdir>] [--theme light|dark]\n");
   process.exit(2);
 }
 
-// Entry point: parse argv, run --check or --emit.
+// Entry point: parse argv, run --check or --emit over the artifact directory.
 function main() {
   const argv = process.argv.slice(2);
-  let designPath = null;
+  let artifactDir = null;
   let mode = "check";
   let outdir = null;
+  let theme = "light";
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--check") mode = "check";
     else if (a === "--emit") { mode = "emit"; outdir = argv[++i] ?? null; }
-    else if (!a.startsWith("-") && designPath === null) designPath = a;
+    else if (a === "--theme") { theme = argv[++i] ?? null; }
+    else if (!a.startsWith("-") && artifactDir === null) artifactDir = a;
     else usage();
   }
-  if (!designPath) usage();
+  if (!artifactDir) usage();
   if (mode === "emit" && !outdir) usage();
+  if (!LEGAL_THEMES.includes(theme)) usage();
 
-  let source;
-  try {
-    source = readFileSync(designPath, "utf8");
-  } catch {
-    process.stderr.write(`error: cannot read ${designPath}\n`);
-    process.exit(2);
-  }
-
-  const doc = parseDesignMd(source);
-  const { errors } = runCoverageGate(doc);
-  const slug = slugify(doc.frontmatter && doc.frontmatter.product);
+  const { errors, payload, views, hints, hasDark } = runCheck(artifactDir, theme);
 
   if (errors.length > 0) {
-    process.stderr.write(`coverage gate FAILED (${designPath}): ${errors.length} issue(s)\n`);
+    process.stderr.write(`check FAILED (${artifactDir}): ${errors.length} issue(s)\n`);
     for (const e of errors) process.stderr.write(`  - ${e}\n`);
     process.exit(1);
   }
 
+  const slug = slugify(payload.product);
+
   if (mode === "check") {
-    const provenance = doc.frontmatter.provenance;
-    process.stdout.write(`coverage gate PASSED (${designPath}): 26 primitives, verbosity/feedback/density-tier, 34 color tokens, scales OK — provenance=${provenance}, style=${slug}\n`);
+    const hintNote = hints.length > 0 ? `, ${hints.length} hint(s) outstanding (emit will refuse)` : "";
+    process.stdout.write(`check PASSED (${artifactDir}): rules 1–11 OK — 26 primitives, 34 color roles, typography 3+6, payload/manifest/parse-back OK — provenance=${payload.provenance}, style=${slug}, theme=${theme}${hasDark ? ", dark overlay present" : ""}${hintNote}\n`);
     process.exit(0);
   }
 
-  // --emit: refuse while any bare hint remains.
-  const hints = collectBareHints(doc);
+  // Rule 12 — emission precondition: refuse while any token carries a hint.
   if (hints.length > 0) {
-    process.stderr.write(`emit REFUSED (${designPath}): ${hints.length} unresolved hint(s) — resolve each to a concrete value before emission.\n`);
+    process.stderr.write(`emit REFUSED (${artifactDir}): ${hints.length} unresolved hint(s) — rule 12: every gated token must be concrete before emission.\n`);
     for (const h of hints) process.stderr.write(`  - ${h.key}: hint: ${h.text}\n`);
-    process.stderr.write("  Resolve with judgment and record the rationale: \"<key>: <value>   # derived: <rationale>\", then re-run --emit.\n");
+    process.stderr.write("  Resolve each with judgment: set the real $value, delete the hint key, record the rationale in $description — then re-run --emit.\n");
+    process.exit(1);
+  }
+
+  const emitErrors = [];
+  const doc = buildEmitterDoc(views, payload, emitErrors);
+  if (emitErrors.length > 0) {
+    process.stderr.write(`emit FAILED (${artifactDir}): ${emitErrors.length} issue(s)\n`);
+    for (const e of emitErrors) process.stderr.write(`  - ${e}\n`);
     process.exit(1);
   }
 
-  const personalityCss = emitPersonalityCss(doc, slug);
+  const meta = { provenance: payload.provenance, sourced: payload.sourced, theme };
+  const personalityCss = emitPersonalityCss(doc, slug, meta);
   const globalsCss = emitGlobalsCss(doc);
-  const htmlAttrs = emitIndexHtmlAttributes(doc, slug);
+  const htmlAttrs = emitIndexHtmlAttributes(doc, slug, meta);
   const personalityPath = join(outdir, "src/styles/personality.css");
   const globalsPath = join(outdir, "src/styles/globals.css");
   const attrsPath = join(outdir, "index-html-attributes.txt");