@nurix/etna 0.19.11 → 0.19.13

package/data/harnesses/code/skills/design/scripts/convert-design-md.mjs

@@ -1,1312 +0,0 @@
-#!/usr/bin/env node
-// skills/design/scripts/convert-design-md.mjs — mechanical design.md → design-tokens converter (schema design-tokens/v2, DTCG 2025.10): parses each source's frontmatter + two machine blocks + §3 type ramp, emits design.tokens.json / design.tokens.dark.json / design.resolver.json per data/design-tokens/SCHEMA.md (running the v1→v2 upgrade transform over each converted entry), self-validates (schema rules 2–10 + the v2 groups), offers --upgrade-v2 to run the same idempotent transform over existing artifact directories, and --strip to remove the machine blocks (and their orphaned prose references) from source files once the byte-match gate passes.
-//
-// Usage:
-//   node convert-design-md.mjs                     convert every entry (nurix.md + library/*.md), then validate
-//   node convert-design-md.mjs --only <slug>       convert/validate a single entry
-//   node convert-design-md.mjs --validate          validate existing artifacts only (no conversion)
-//   node convert-design-md.mjs --upgrade-v2        idempotent v1→v2 migration over data/design-tokens/*/, then validate
-//   node convert-design-md.mjs --report <file>     also write the JSON conversion report to <file>
-//   node convert-design-md.mjs --strip <file...>   remove both machine blocks + orphaned prose from the named
-//                                                  .md files IN PLACE (explicit paths required — never implicit)
-
-import { mkdirSync, readFileSync, writeFileSync, existsSync, readdirSync } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const scriptsDir = dirname(fileURLToPath(import.meta.url));
-const skillDir = dirname(scriptsDir);
-const designMdDir = join(skillDir, "data", "design-md");
-const tokensDir = join(skillDir, "data", "design-tokens");
-
-// ---------------------------------------------------------------------------
-// Vocabulary (names are law — mirrors data/design-tokens/SCHEMA.md)
-// ---------------------------------------------------------------------------
-
-// The 26 v1 source primitives in emission order, with their DTCG $type (the design.md machine
-// blocks carry these; primitive.stagger-unit is added by the v1→v2 upgrade transform).
-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 27 v2 primitives with stagger-unit in its emission slot (after ease-default).
-const PRIMITIVE_TYPES_V2 = new Map(
-  [...PRIMITIVE_TYPES].flatMap(([k, t]) => (k === "ease-default" ? [[k, t], ["stagger-unit", "duration"]] : [[k, t]])),
-);
-
-// The 34 v1 source color roles in emission order (17 semantic + 17 substrate; the machine blocks carry these).
-const COLOR_ROLES = [
-  "background", "foreground", "card", "card-foreground", "muted", "muted-foreground",
-  "border", "input", "ring", "primary", "primary-foreground", "accent", "accent-foreground",
-  "destructive", "destructive-foreground", "success", "warning",
-  "popover", "popover-foreground", "secondary", "secondary-foreground",
-  "chart-1", "chart-2", "chart-3", "chart-4", "chart-5",
-  "sidebar", "sidebar-foreground", "sidebar-primary", "sidebar-primary-foreground",
-  "sidebar-accent", "sidebar-accent-foreground", "sidebar-border", "sidebar-ring",
-];
-
-// The 36 v2 roles: the dark-ladder pair (surface-raised/surface-overlay) closes the semantic set at 19.
-const COLOR_ROLES_V2 = COLOR_ROLES.flatMap((r) => (r === "warning" ? [r, "surface-raised", "surface-overlay"] : [r]));
-
-const RAMP_STEPS = ["h1", "h2", "h3", "body", "small", "caption"];
-const RAMP_STEPS_V2 = [...RAMP_STEPS, "display"];
-const ELEVATION_TOKENS = ["sm", "md", "lg", "overlay"];
-// Source §3 row names that fill the caption slot when no literal `caption` row exists.
-const CAPTION_ALIASES = ["caption", "eyebrow / caption", "eyebrow", "label", "mono-label"];
-
-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", "shadow", "gradient"];
-const SHADOW_RANK = { none: 0, "2xs": 1, xs: 2, sm: 3, md: 4, lg: 5, xl: 6, "2xl": 7, overlay: 8 };
-const EXT = "com.nurix.design";
-
-// Provisional values worn when a source key is a `hint:` (the Nurix defaults, per SCHEMA.md examples).
-const HINT_PROVISIONALS = new Map([
-  ["radius", "6px"], ["shadow-intensity", "0.4"], ["border-weight", "1px"], ["density-gap", "1"],
-  ["density-inset", "1"], ["font-sans", "Inter, system-ui, sans-serif"],
-  ["font-mono", "Geist Mono, ui-monospace, SFMono-Regular, monospace"],
-  ["font-weight-normal", "400"], ["font-weight-strong", "600"], ["heading-tracking", "-0.01em"],
-  ["duration-unit", "50ms"], ["duration-fast", "100ms"], ["duration-normal", "150ms"],
-  ["duration-slow", "250ms"], ["ease-default", "cubic-bezier(0.4,0,0.2,1)"], ["contrast-boost", "1"],
-  ["icon-stroke", "1.75"], ["icon-size-base", "16px"], ["sidebar-width-expanded", "248px"],
-  ["sidebar-width-collapsed", "56px"], ["topbar-height", "52px"], ["side-panel-width", "420px"],
-  ["side-panel-width-rich", "640px"], ["modal-width-max", "560px"], ["form-max-width", "640px"],
-  ["table-row-height", "40px"],
-]);
-
-// ---------------------------------------------------------------------------
-// Low-level text helpers
-// ---------------------------------------------------------------------------
-
-// Split a raw line at its first unquoted, whitespace-preceded '#': { body, comment|null }.
-function splitLineComment(line) {
-  let inDouble = false, inSingle = false;
-  for (let i = 0; i < line.length; i++) {
-    const c = line[i];
-    if (c === '"' && !inSingle && line[i - 1] !== "\\") inDouble = !inDouble;
-    else if (c === "'" && !inDouble) inSingle = !inSingle;
-    else if (c === "#" && !inDouble && !inSingle && (i === 0 || /\s/.test(line[i - 1]))) {
-      return { body: line.slice(0, i).replace(/\s+$/, ""), comment: line.slice(i + 1).trim() };
-    }
-  }
-  return { body: line.replace(/\s+$/, ""), comment: null };
-}
-
-// 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) === '"') return s.slice(1, -1).replaceAll('\\"', '"');
-  if (s.length >= 2 && s[0] === "'" && s.at(-1) === "'") return s.slice(1, -1);
-  return s;
-}
-
-// Split on a delimiter at bracket-depth 0 and outside quotes.
-function splitTopLevel(str, delim) {
-  const parts = [];
-  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 (!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;
-}
-
-// Round to at most 5 decimals (the srgb component precision).
-function round5(n) {
-  return Math.round(n * 1e5) / 1e5;
-}
-
-function fail(msg) {
-  console.error(`convert-design-md: ${msg}`);
-  process.exit(1);
-}
-
-// ---------------------------------------------------------------------------
-// CSS value parsers (single source of truth — conversion AND parse-back verify use these)
-// ---------------------------------------------------------------------------
-
-// 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;
-  }
-  m = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/.exec(s);
-  if (!m) m = /^rgba?\(\s*(\d+)\s+(\d+)\s+(\d+)\s*(?:\/\s*([\d.]+%?)\s*)?\)$/.exec(s); // modern space syntax
-  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 = m[4].endsWith("%") ? round5(parseFloat(m[4]) / 100) : parseFloat(m[4]);
-    return value;
-  }
-  throw new Error(`unparseable color: ${JSON.stringify(css)}`);
-}
-
-// Parse one shadow-list string (the elevation byte form) into the DTCG layer array; byte-compatible
-// with derive-personality.mjs. A layer alpha may ride calc(A * var(--shadow-intensity)) — A is the alpha.
-function parseShadowCss(css) {
-  return splitTopLevel(css, ",").map((layerRaw) => {
-    const s = layerRaw.trim();
-    const colorStart = s.search(/rgba?\(|oklch\(|hsla?\(|#[0-9a-fA-F]/);
-    if (colorStart < 0) throw new Error(`shadow layer names no color: ${JSON.stringify(s)}`);
-    const colorCss = s.slice(colorStart).trim().replace(/calc\(\s*([\d.]+)\s*\*\s*var\(--shadow-intensity\)\s*\)/, "$1");
-    const dims = s.slice(0, colorStart).trim().split(/\s+/);
-    if (dims.length < 3 || dims.length > 4) throw new Error(`shadow layer wants 3-4 lengths: ${JSON.stringify(s)}`);
-    const dim = (d) => (d === "0" ? { value: 0, unit: "px" } : parseDimensionCss(d));
-    return {
-      color: parseColorCss(colorCss),
-      offsetX: dim(dims[0]),
-      offsetY: dim(dims[1]),
-      blur: dim(dims[2]),
-      spread: dims[3] !== undefined ? dim(dims[3]) : { value: 0, unit: "px" },
-    };
-  });
-}
-
-// 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]);
-}
-
-// 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;
-}
-
-// ---------------------------------------------------------------------------
-// Source parsing — frontmatter, the two machine blocks, the §3 ramp table
-// ---------------------------------------------------------------------------
-
-function parseFrontmatter(source) {
-  const m = /^---\s*\n([\s\S]*?)\n---\s*\n/.exec(source);
-  if (!m) return null;
-  const out = {};
-  for (const raw of m[1].split("\n")) {
-    const { body } = splitLineComment(raw);
-    const ci = body.indexOf(":");
-    if (ci > 0) out[body.slice(0, ci).trim()] = unquote(body.slice(ci + 1));
-  }
-  return out;
-}
-
-// Extract the raw body of the ```yaml <label> fenced block, or null.
-function extractFencedBlock(source, label) {
-  const re = new RegExp("^`{3,}\\s*yaml\\s+" + label + "\\s*$", "m");
-  const open = re.exec(source);
-  if (!open) return null;
-  const start = source.indexOf("\n", open.index) + 1;
-  const close = /^`{3,}\s*$/m.exec(source.slice(start));
-  if (!close) return null;
-  return source.slice(start, start + close.index);
-}
-
-// Parse the design-primitives block, keeping raw value strings and per-line comments.
-function parsePrimitivesBlock(text) {
-  const entries = new Map();
-  const standalone = [];
-  for (const raw of text.split("\n")) {
-    if (raw.trim() === "") continue;
-    const { body, comment } = splitLineComment(raw);
-    if (body.trim() === "") { if (comment !== null) standalone.push(comment); continue; }
-    const m = /^([a-z-]+):\s*(.*)$/.exec(body.trim());
-    if (!m) throw new Error(`unparseable design-primitives line: ${JSON.stringify(raw)}`);
-    entries.set(m[1], { raw: m[2].trim(), comment });
-  }
-  return { entries, standalone };
-}
-
-// Parse an inline flow array "[a, b, c]" into raw scalar strings.
-function parseFlowArray(raw) {
-  const inner = raw.trim().replace(/^\[/, "").replace(/\]$/, "");
-  return splitTopLevel(inner, ",").map((p) => unquote(p)).filter((p) => p !== "");
-}
-
-// Parse an inline flow object "{ k: v, ... }" into raw scalar/array values keyed by name.
-function parseFlowObject(raw) {
-  const inner = raw.trim().replace(/^\{/, "").replace(/\}$/, "");
-  const out = {};
-  for (const part of splitTopLevel(inner, ",")) {
-    if (part.trim() === "") continue;
-    const ci = part.indexOf(":");
-    const key = part.slice(0, ci).trim();
-    const val = part.slice(ci + 1).trim();
-    out[key] = val.startsWith("[") ? parseFlowArray(val) : unquote(val);
-  }
-  return out;
-}
-
-// Parse the lever-manifest block: scalars, the light/dark color maps (with comments), non-token comments.
-function parseManifestBlock(text) {
-  const out = { scalars: new Map(), light: new Map(), dark: null, standalone: [] };
-  let section = null;
-  for (const raw of text.split("\n")) {
-    if (raw.trim() === "") continue;
-    const { body, comment } = splitLineComment(raw);
-    if (body.trim() === "") { if (comment !== null) out.standalone.push({ where: "lever-manifest", comment }); continue; }
-    const indent = body.length - body.trimStart().length;
-    const t = body.trim();
-    if (indent === 0) {
-      const m = /^([a-z-]+):\s*(.*)$/.exec(t);
-      if (!m) throw new Error(`unparseable lever-manifest line: ${JSON.stringify(raw)}`);
-      if (m[1] === "color-tokens") {
-        section = "color-tokens";
-        if (comment !== null) out.standalone.push({ where: "color-tokens", comment });
-        continue;
-      }
-      section = null;
-      out.scalars.set(m[1], { raw: m[2].trim(), comment });
-    } else if (["color-tokens", "light", "dark"].includes(section) && indent === 2 && /^(light|dark):$/.test(t)) {
-      section = t.slice(0, -1) === "light" ? "light" : "dark";
-      if (section === "dark") out.dark = new Map();
-      if (comment !== null) out.standalone.push({ where: `color-tokens.${section}`, comment });
-    } else if ((section === "light" || section === "dark") && indent >= 4) {
-      const m = /^([a-z0-9-]+):\s*(.+)$/.exec(t);
-      if (!m) throw new Error(`unparseable color-token line: ${JSON.stringify(raw)}`);
-      (section === "light" ? out.light : out.dark).set(m[1], { raw: unquote(m[2]), comment });
-    } else {
-      throw new Error(`unexpected lever-manifest structure: ${JSON.stringify(raw)}`);
-    }
-  }
-  return out;
-}
-
-// Extract the §3 typography table as header-mapped rows: { name, role, family, size, weight }.
-function parseRampTable(source) {
-  const sec = /^## 3\b.*?\n([\s\S]*?)(?=^## \d|\n```yaml )/m.exec(source);
-  if (!sec) return null;
-  const lines = sec[1].split("\n").filter((l) => l.trim().startsWith("|"));
-  if (lines.length < 3) return null;
-  const cells = (l) => l.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
-  const header = cells(lines[0]).map((h) => h.toLowerCase());
-  const col = (name) => header.findIndex((h) => h.includes(name));
-  const iStep = col("step"), iRole = col("role"), iFam = col("family"), iSize = col("size"), iWeight = col("weight");
-  const rows = [];
-  for (const line of lines.slice(2)) {
-    const c = cells(line);
-    if (c.length < header.length) continue;
-    rows.push({
-      name: c[iStep], role: c[iRole], family: iFam >= 0 ? c[iFam] : null,
-      size: c[iSize], weight: c[iWeight],
-    });
-  }
-  return rows;
-}
-
-// ---------------------------------------------------------------------------
-// Conversion — one source entry → the token artifact
-// ---------------------------------------------------------------------------
-
-// Build one primitive token (typed $value, comment → $description, preserved css / hint where the schema requires).
-function buildPrimitiveToken(key, rawValue, comment, notes) {
-  const type = PRIMITIVE_TYPES.get(key);
-  const token = { $type: type };
-  let raw = rawValue;
-  let hint = null;
-  if (raw.startsWith("hint:")) {
-    hint = raw.slice(5).trim();
-    raw = HINT_PROVISIONALS.get(key);
-    notes.hints.push({ key, hint });
-  }
-  const ext = {};
-  if (type === "dimension") {
-    token.$value = parseDimensionCss(raw);
-    if (`${token.$value.value}px` !== raw) notes.irregularities.push(`primitive ${key}: non-canonical byte form ${JSON.stringify(raw)}`);
-  } else if (type === "duration") {
-    token.$value = parseDurationCss(raw);
-    if (`${token.$value.value}ms` !== raw) notes.irregularities.push(`primitive ${key}: non-canonical byte form ${JSON.stringify(raw)}`);
-  } else if (type === "fontWeight") {
-    token.$value = parseNumberCss(raw);
-  } else if (type === "cubicBezier") {
-    token.$value = parseCubicBezierCss(raw);
-    ext.css = raw;
-  } else if (type === "fontFamily") {
-    token.$value = parseFontStackCss(raw);
-    ext.css = raw;
-  } else if (key === "heading-tracking") {
-    token.$value = parseTrackingCss(raw);
-    ext.css = raw;
-  } else {
-    token.$value = parseNumberCss(raw);
-    if (String(token.$value) !== raw) notes.irregularities.push(`primitive ${key}: non-canonical byte form ${JSON.stringify(raw)}`);
-  }
-  if (comment !== null) { token.$description = comment; notes.migrated++; }
-  if (hint !== null) ext.hint = hint;
-  if (Object.keys(ext).length > 0) token.$extensions = { [EXT]: ext };
-  return token;
-}
-
-// Build one color token: typed $value + mandatory preserved css; comment → $description.
-function buildColorToken(css, comment, notes) {
-  const token = { $type: "color", $value: parseColorCss(css) };
-  if (comment !== null) { token.$description = comment; notes.migrated++; }
-  token.$extensions = { [EXT]: { css } };
-  return token;
-}
-
-// Interpret one §3 weight·tracking cell → { weight, tracking, trackingCss, mono, parenWeights }.
-function parseWeightCell(cell, fontSizePx) {
-  const cleaned = cell.replace(/`/g, "");
-  const parenWeights = [...cleaned.matchAll(/\((\d{3})\)/g)].map((m) => Number(m[1]));
-  const rest = cleaned.replace(/\([^)]*\)/g, " ");
-  const tokens = rest.split(/[·,]/).map((t) => t.trim()).filter((t) => t !== "");
-  let weight = null, tracking = null, trackingCss = null, mono = false;
-  for (const tok of tokens) {
-    if (/^font-weight-strong$/.test(tok)) weight = "{primitive.font-weight-strong}";
-    else if (/^font-weight-normal$/.test(tok)) weight = "{primitive.font-weight-normal}";
-    else if (/^heading-tracking$/.test(tok)) tracking = "{primitive.heading-tracking}";
-    else if (/^[+-]?\d*\.?\d+(em|px)$/.test(tok)) { tracking = parseLetterSpacingCss(tok, fontSizePx); trackingCss = tok; }
-    else if (/^\d{3}$/.test(tok) && weight === null) weight = Number(tok);
-    else if (tok === "0") tracking = 0;
-    else if (/\bfont-mono\b|^mono\b/.test(tok)) mono = true;
-    // remaining words (uppercase, sentence case, no tracking, positive, …) are usage prose — the .md keeps them
-  }
-  return { weight, tracking, trackingCss, mono, parenWeights };
-}
-
-// Build typography.family.* + the six-step typography.ramp.* from the §3 table rows.
-function buildTypography(rows, primitives, notes) {
-  const family = {
-    heading: { $type: "fontFamily", $value: "{primitive.font-sans}" },
-    body: { $type: "fontFamily", $value: "{primitive.font-sans}" },
-    mono: { $type: "fontFamily", $value: "{primitive.font-mono}" },
-  };
-  if (rows === null) throw new Error("no §3 typography table found");
-
-  // Map source rows onto the six fixed step names; leftovers are reported, never emitted.
-  const bySlot = new Map();
-  const leftovers = [];
-  for (const row of rows) {
-    const name = row.name.toLowerCase();
-    if (RAMP_STEPS.includes(name) && !bySlot.has(name)) bySlot.set(name, row);
-    else leftovers.push(row);
-  }
-  if (!bySlot.has("caption")) {
-    for (const alias of CAPTION_ALIASES) {
-      const i = leftovers.findIndex((r) => r.name.toLowerCase() === alias);
-      if (i >= 0) {
-        const row = leftovers.splice(i, 1)[0];
-        bySlot.set("caption", row);
-        notes.ramp.push(`caption ← source step \`${row.name}\``);
-        break;
-      }
-    }
-  }
-  for (const row of leftovers) notes.ramp.push(`unmapped §3 row \`${row.name}\` (${row.role}) — no ramp slot`);
-
-  // The look pairs a serif display face the machine blocks don't carry — note it, alias stays font-sans.
-  const serifRows = [...bySlot.values()].filter((r) => r.family && /serif/i.test(r.family) && !/sans/i.test(r.family));
-  if (serifRows.length > 0) {
-    family.heading.$description =
-      "source §3 pairs a serif display family for " + serifRows.map((r) => r.name).join("/") +
-      "; its stack is prose-carried (the agent applies it by hand) — aliased to font-sans mechanically";
-    notes.ramp.push(`serif heading family noted on typography.family.heading (rows: ${serifRows.map((r) => r.name).join(", ")})`);
-  }
-
-  const ramp = {};
-  for (const step of RAMP_STEPS) {
-    let row = bySlot.get(step);
-    let synthesized = null;
-    if (!row) {
-      row = bySlot.get("body");
-      if (!row) throw new Error(`§3 table lacks both \`${step}\` and \`body\` rows`);
-      synthesized = `synthesized: source §3 ramp carries no \`${step}\` step; values copied from body (role: ${row.role})`;
-      notes.ramp.push(`${step} synthesized from body (missing in source §3 table)`);
-    }
-    const sm = /(\d+(?:\.\d+)?)px\s*\/\s*(\d+(?:\.\d+)?)/.exec(row.size);
-    if (!sm) throw new Error(`unparseable §3 size cell for ${step}: ${JSON.stringify(row.size)}`);
-    const fontSize = parseFloat(sm[1]);
-    const cell = parseWeightCell(row.weight, fontSize);
-
-    // A parenthetical weight that contradicts the aliased primitive is a source irregularity.
-    for (const pw of cell.parenWeights) {
-      const aliasKey = cell.weight === "{primitive.font-weight-strong}" ? "font-weight-strong"
-        : cell.weight === "{primitive.font-weight-normal}" ? "font-weight-normal" : null;
-      if (aliasKey && parseNumberCss(primitives.get(aliasKey).raw) !== pw) {
-        notes.irregularities.push(`§3 ${step}: parenthetical weight (${pw}) contradicts primitive ${aliasKey}: ${primitives.get(aliasKey).raw}`);
-      }
-    }
-    if (cell.weight === null) {
-      cell.weight = "{primitive.font-weight-normal}";
-      notes.ramp.push(`${step}: §3 row names no weight — defaulted to font-weight-normal`);
-    }
-
-    const monoFamily = cell.mono || (row.family !== null && /^mono/i.test(row.family));
-    const familyAlias = monoFamily ? "{typography.family.mono}"
-      : (step === "h1" || step === "h2" || step === "h3") ? "{typography.family.heading}"
-      : "{typography.family.body}";
-
-    const token = {
-      $type: "typography",
-      $value: {
-        fontFamily: familyAlias,
-        fontSize: { value: fontSize, unit: "px" },
-        lineHeight: parseFloat(sm[2]),
-        fontWeight: cell.weight,
-        letterSpacing: cell.tracking === null ? 0 : cell.tracking,
-      },
-    };
-    const descriptions = [];
-    if (step === "caption") descriptions.push(row.role);
-    if (synthesized) descriptions.push(synthesized);
-    if (descriptions.length > 0) token.$description = descriptions.join(" — ");
-    if (cell.trackingCss !== null) token.$extensions = { [EXT]: { css: { letterSpacing: cell.trackingCss } } };
-    ramp[step] = token;
-    if (cell.trackingCss !== null && cell.trackingCss.endsWith("px")) {
-      notes.ramp.push(`${step}: px tracking ${cell.trackingCss} → ${token.$value.letterSpacing}em (at ${fontSize}px)`);
-    }
-  }
-  return { family, ramp };
-}
-
-// Build the payload lever-manifest from the source block, dropping token-duplicating keys (fonts, icons.stroke, version).
-function buildLeverManifest(manifest, primitives, notes) {
-  const scalar = (k) => manifest.scalars.get(k);
-  const nums = (arr) => arr.map((v) => parseNumberCss(v));
-
-  // fonts duplicates primitive.font-sans/font-mono — the allowlist reads the tokens now.
-  const fonts = parseFlowObject(scalar("fonts").raw);
-  for (const [slot, primKey] of [["sans", "font-sans"], ["mono", "font-mono"]]) {
-    const a = parseFontStackCss(fonts[slot] ?? "");
-    const b = parseFontStackCss(primitives.get(primKey).raw);
-    if (JSON.stringify(a) !== JSON.stringify(b)) {
-      notes.irregularities.push(`manifest fonts.${slot} differs from primitive ${primKey}: ${JSON.stringify(fonts[slot])} vs ${JSON.stringify(primitives.get(primKey).raw)}`);
-    }
-  }
-  notes.drops.push("fonts (duplicates primitive.font-sans / primitive.font-mono)");
-
-  const icons = parseFlowObject(scalar("icons").raw);
-  if (icons.stroke !== undefined) {
-    if (icons.stroke !== primitives.get("icon-stroke").raw) {
-      notes.irregularities.push(`manifest icons.stroke ${icons.stroke} differs from primitive icon-stroke ${primitives.get("icon-stroke").raw}`);
-    }
-    notes.drops.push("icons.stroke (duplicates primitive.icon-stroke)");
-  }
-  if (scalar("version") !== undefined) notes.drops.push("version (superseded by the payload `schema` literal)");
-
-  const motion = parseFlowObject(scalar("motion").raw);
-  return {
-    "spacing-scale": nums(parseFlowArray(scalar("spacing-scale").raw)),
-    "radius-scale": nums(parseFlowArray(scalar("radius-scale").raw)),
-    "shadow-levels": parseFlowArray(scalar("shadow-levels").raw),
-    motion: { durations: nums(motion.durations), easings: motion.easings },
-    icons: { family: icons.family },
-    "accent-count": parseNumberCss(scalar("accent-count").raw),
-  };
-}
-
-// Convert one parsed source entry into its three artifact documents.
-function convertEntry(source, slug) {
-  const notes = { migrated: 0, rootAttached: [], dropped: [], hints: [], ramp: [], drops: [], irregularities: [], darkFile: false };
-  const frontmatter = parseFrontmatter(source);
-  if (!frontmatter) throw new Error("missing frontmatter");
-  if (frontmatter.schema !== "design-md/v1") throw new Error(`unknown source schema: ${frontmatter.schema}`);
-
-  const primText = extractFencedBlock(source, "design-primitives");
-  const maniText = extractFencedBlock(source, "lever-manifest");
-  if (primText === null || maniText === null) throw new Error("missing machine block(s)");
-  const prims = parsePrimitivesBlock(primText);
-  const manifest = parseManifestBlock(maniText);
-
-  // Non-token comments (dials, scales, standalone lines) have no token to land on — they're preserved
-  // on the artifact root $description and reported, never dropped silently.
-  const rootNotes = [];
-  const attachRoot = (where, comment) => { rootNotes.push(`[${where}] ${comment}`); notes.rootAttached.push({ where, comment }); };
-
-  // Primitive tokens.
-  const primitive = {};
-  for (const key of PRIMITIVES) {
-    const entry = prims.entries.get(key);
-    if (!entry) throw new Error(`missing primitive: ${key}`);
-    primitive[key] = buildPrimitiveToken(key, entry.raw, entry.comment, notes);
-  }
-
-  // Dials + traits → payload; their comments are non-token.
-  const dial = (key) => {
-    const entry = prims.entries.get(key);
-    if (!entry) throw new Error(`missing dial: ${key}`);
-    if (entry.comment !== null) attachRoot(key, entry.comment);
-    return entry.raw;
-  };
-  const verbosity = dial("verbosity"), feedback = dial("feedback"), densityTier = dial("density-tier");
-  const traits = parseFlowArray(dial("product-traits"));
-  for (const c of prims.standalone) attachRoot("design-primitives", c);
-  for (const key of prims.entries.keys()) {
-    if (!PRIMITIVES.includes(key) && !["verbosity", "feedback", "density-tier", "product-traits"].includes(key)) {
-      notes.irregularities.push(`unknown design-primitives key: ${key}`);
-    }
-  }
-
-  // Color tokens (light) — every role required.
-  const color = {};
-  for (const role of COLOR_ROLES) {
-    const entry = manifest.light.get(role);
-    if (!entry) throw new Error(`missing color token: ${role}`);
-    color[role] = buildColorToken(entry.raw, entry.comment, notes);
-  }
-  for (const role of manifest.light.keys()) if (!COLOR_ROLES.includes(role)) notes.irregularities.push(`unknown light color token: ${role}`);
-
-  // Manifest scalar comments + standalone comments are non-token.
-  for (const [key, { comment }] of manifest.scalars) if (comment !== null) attachRoot(key, comment);
-  for (const c of manifest.standalone) attachRoot(c.where, c.comment);
-
-  const leverManifest = buildLeverManifest(manifest, prims.entries, notes);
-  const typography = buildTypography(parseRampTable(source), prims.entries, notes);
-
-  // Root $description: the source H1 title, then any root-attached provenance notes.
-  const h1 = /^# (.+)$/m.exec(source);
-  const $description = [h1 ? h1[1].trim() : frontmatter.product, ...rootNotes].join("\n");
-
-  const base = {
-    $description,
-    $extensions: {
-      [EXT]: {
-        schema: "design-tokens/v1",
-        dtcg: "2025.10",
-        product: frontmatter.product,
-        provenance: frontmatter.provenance,
-        sourced: frontmatter.sourced,
-        "product-traits": traits,
-        verbosity, feedback, "density-tier": densityTier,
-        "lever-manifest": leverManifest,
-      },
-    },
-    primitive, color, typography,
-  };
-
-  // Dark set — the color group remapped, nothing else; partial maps inherit light with a marker.
-  let dark = null;
-  if (manifest.dark !== null) {
-    notes.darkFile = true;
-    const darkColor = {};
-    for (const role of COLOR_ROLES) {
-      const entry = manifest.dark.get(role);
-      if (entry) {
-        darkColor[role] = buildColorToken(entry.raw, entry.comment, notes);
-      } else {
-        darkColor[role] = structuredClone(color[role]);
-        darkColor[role].$description = "dark: inherited from light (source map partial)";
-        notes.irregularities.push(`dark map partial: ${role} inherited from light`);
-      }
-    }
-    for (const role of manifest.dark.keys()) if (!COLOR_ROLES.includes(role)) notes.irregularities.push(`unknown dark color token: ${role}`);
-    dark = { color: darkColor };
-  }
-
-  const resolver = {
-    schema: "design-resolver/v1",
-    sets: [{ name: "base", values: ["design.tokens.json"] }],
-    modifiers: [{
-      name: "theme", default: "light",
-      contexts: dark ? { light: [], dark: ["design.tokens.dark.json"] } : { light: [] },
-    }],
-  };
-
-  return { base, dark, resolver, notes };
-}
-
-// ---------------------------------------------------------------------------
-// v1 → v2 upgrade transform (SCHEMA.md migration; idempotent — every step skips when already applied)
-// ---------------------------------------------------------------------------
-
-// The v1 hardcoded slate shadow recipes (the old globals.css @theme block) reified as elevation byte
-// forms — value-preserving: the calc(α × --shadow-intensity) rider keeps the twin's shadow-intensity
-// as the master multiplier, so emitted --shadow-sm/md/lg are byte-identical before/after migration.
-// overlay is the widest-blur member of the same family (new in v2, additive).
-const V1_SHADOW_RECIPES = {
-  sm: "0 1px 3px 0 rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 1px 2px -1px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)))",
-  md: "0 4px 6px -1px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 2px 4px -2px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)))",
-  lg: "0 10px 15px -3px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 4px 6px -4px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)))",
-  overlay: "0 20px 25px -5px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity))), 0 8px 10px -6px rgb(15 23 42 / calc(0.10 * var(--shadow-intensity)))",
-};
-
-// Collect design.md code spans that name real shadow values — a color function (shadow tints ride
-// alpha'd rgba/oklch) or box-shadow geometry (>= 2 consecutive lengths) on a shadow-context line.
-// A bare hex near the word "shadow" (a border color in a "never shadow" sentence) is not one.
-function findShadowProse(designMd) {
-  if (designMd === null) return [];
-  const evidence = [];
-  const lines = designMd.split("\n");
-  for (const [i, line] of lines.entries()) {
-    // The shadow context may sit on the previous line when the prose wraps; a negated mention
-    // ("no shadow", "not shadow", "never ... shadow", "shadowless") is not a shadow context.
-    const window = `${lines[i - 1] ?? ""} ${line}`
-      .replace(/\b(?:no|not|never|without|zero)\b[^.;:]*?shadow\w*/gi, "")
-      .replace(/shadow-?less/gi, "");
-    if (!/shadow/i.test(window)) continue;
-    for (const m of line.matchAll(/`[^`]+`/g)) {
-      const span = m[0];
-      const hasColorFn = /rgba?\(|oklch\(|hsla?\(/.test(span);
-      const hasGeometry = /(?:^|[\s`])(?:-?\d+(?:\.\d+)?px|0)\s+(?:-?\d+(?:\.\d+)?px|0)(?:\s|`|,)/.test(span);
-      if (hasColorFn || hasGeometry) evidence.push(span);
-    }
-  }
-  return evidence;
-}
-
-// True when a design.md declares the dark theme as the product's default.
-function declaresDarkFirst(designMd) {
-  return designMd !== null && /dark by default|default to dark|wear the dark theme by default/i.test(designMd);
-}
-
-// Rebuild an object with `additions` ([key, value] pairs) inserted immediately after `afterKey`.
-function insertAfter(obj, afterKey, additions) {
-  const out = {};
-  for (const [k, v] of Object.entries(obj)) {
-    out[k] = v;
-    if (k === afterKey) for (const [ak, av] of additions) out[ak] = av;
-  }
-  return out;
-}
-
-// Apply the seven-step v1→v2 migration to one artifact's documents in place-order (idempotent:
-// every step is skipped when its key already exists). Returns per-entry stats.
-function upgradeArtifact(base, dark, resolver, designMd, slug) {
-  const stats = { elevationHinted: false, darkFirst: false, displayHinted: false };
-  const payload = base.$extensions?.[EXT];
-  if (!payload) throw new Error("upgrade: no payload on the base root");
-
-  // Step 1 — the schema literal.
-  payload.schema = "design-tokens/v2";
-
-  // Step 6 — theme-default: light everywhere except twins whose design.md declares dark-first
-  // (only a twin shipping a dark set can boot dark); the resolver's theme default mirrors it.
-  if (payload["theme-default"] === undefined) {
-    const darkFirst = dark !== null && declaresDarkFirst(designMd);
-    base.$extensions[EXT] = insertAfter(payload, "sourced", [["theme-default", darkFirst ? "dark" : "light"]]);
-  }
-  stats.darkFirst = base.$extensions[EXT]["theme-default"] === "dark";
-  const themeModifier = (resolver.modifiers ?? []).find((m) => m?.name === "theme");
-  if (themeModifier) themeModifier.default = base.$extensions[EXT]["theme-default"];
-
-  // The Nurix default's stated v2 shadow vocabulary (SCHEMA.md elevation section).
-  if (slug === "nurix") base.$extensions[EXT]["lever-manifest"]["shadow-levels"] = ["none", "sm", "md", "lg", "overlay"];
-
-  // Step 2 — elevation from the v1 slate recipes × the twin's shadow-intensity; hinted when the
-  // design.md names real shadow values (judgment owed: the composites should carry that prose).
-  if (base.elevation === undefined) {
-    const prose = findShadowProse(designMd);
-    stats.elevationHinted = prose.length > 0;
-    const elevation = {};
-    for (const level of ELEVATION_TOKENS) {
-      const css = V1_SHADOW_RECIPES[level];
-      const ext = { css };
-      if (prose.length > 0) {
-        ext.hint = `elevation unset — the design.md names real shadow values (${prose.slice(0, 3).join("; ")}); resolve the composites from that prose at the data build`;
-      }
-      elevation[level] = {
-        $type: "shadow",
-        $value: parseShadowCss(css),
-        $description: "derived: v1 shadow-intensity migration",
-        $extensions: { [EXT]: ext },
-      };
-    }
-    base.elevation = elevation;
-  } else {
-    stats.elevationHinted = ELEVATION_TOKENS.some((l) => base.elevation?.[l]?.$extensions?.[EXT]?.hint !== undefined);
-  }
-
-  // Step 3 — the dark-ladder roles as aliases: zero visual change in light; a dark set gains the
-  // same aliases (they resolve post-overlay to the dark card/popover).
-  if (base.color["surface-raised"] === undefined) {
-    base.color = insertAfter(base.color, "warning", [
-      ["surface-raised", { $type: "color", $value: "{color.card}", $description: "derived: v1→v2 migration — light aliases card; dark looks carry the surface-lightness ladder" }],
-      ["surface-overlay", { $type: "color", $value: "{color.popover}", $description: "derived: v1→v2 migration — light aliases popover; dark looks carry the surface-lightness ladder" }],
-    ]);
-  }
-  if (dark !== null && dark.color["surface-raised"] === undefined) {
-    dark.color = insertAfter(dark.color, "warning", [
-      ["surface-raised", { $type: "color", $value: "{color.card}", $description: "derived: v1→v2 migration — aliased to the dark card; the +4–6 L surface ladder is owed at budget-time" }],
-      ["surface-overlay", { $type: "color", $value: "{color.popover}", $description: "derived: v1→v2 migration — aliased to the dark popover; the +4–6 L surface ladder is owed at budget-time" }],
-    ]);
-  }
-
-  // Step 4 — the display step, hinted (provisional: h1 × 1.75, strong weight). The Nurix default
-  // adopts the provisional derivation as its own look, assigned, so emission stays possible.
-  if (base.typography?.ramp && base.typography.ramp.display === undefined) {
-    const h1 = base.typography.ramp.h1;
-    if (!h1?.$value?.fontSize?.value) throw new Error("upgrade: ramp.h1 carries no fontSize to scale");
-    const display = {
-      $type: "typography",
-      $value: {
-        fontFamily: h1.$value.fontFamily,
-        fontSize: { value: Math.round(h1.$value.fontSize.value * 1.75), unit: "px" },
-        lineHeight: h1.$value.lineHeight,
-        fontWeight: "{primitive.font-weight-strong}",
-        letterSpacing: h1.$value.letterSpacing,
-      },
-    };
-    if (slug === "nurix") {
-      display.$description = "derived: v2 display step — the provisional h1 × 1.75 derivation adopted as the default's own look (KPI numerals, the one focal metric)";
-    } else {
-      display.$description = "derived: v1→v2 migration — provisional display step (h1 × 1.75, strong weight)";
-      display.$extensions = { [EXT]: { hint: "display step unset — resolve from the product's design.md or leave for budget-time" } };
-    }
-    base.typography.ramp.display = display;
-  }
-  stats.displayHinted = base.typography?.ramp?.display?.$extensions?.[EXT]?.hint !== undefined;
-
-  // Step 5 — the stagger base, 30ms default (the prior derived clamp's value).
-  if (base.primitive["stagger-unit"] === undefined) {
-    base.primitive = insertAfter(base.primitive, "ease-default", [
-      ["stagger-unit", { $type: "duration", $value: { value: 30, unit: "ms" }, $description: "derived: v1→v2 migration — the 30ms default stagger base (0–60ms legal)" }],
-    ]);
-  }
-
-  return stats;
-}
-
-// Every artifact directory under data/design-tokens/ (a directory holding design.tokens.json), sorted.
-function listArtifactSlugs() {
-  return readdirSync(tokensDir, { withFileTypes: true })
-    .filter((d) => d.isDirectory() && existsSync(join(tokensDir, d.name, "design.tokens.json")))
-    .map((d) => d.name)
-    .sort();
-}
-
-// The design.md source text for one artifact slug, or null when the twin ships no source.
-function readDesignMd(slug) {
-  const path = slug === "nurix" ? join(designMdDir, "nurix.md") : join(designMdDir, "library", `${slug}.md`);
-  return existsSync(path) ? readFileSync(path, "utf8") : null;
-}
-
-// Run the idempotent v1→v2 migration over the existing artifact directories, then re-validate.
-function runUpgradeV2(only) {
-  const slugs = listArtifactSlugs().filter((s) => !only || s === only);
-  if (slugs.length === 0) fail(`no artifact directory named ${only}`);
-  const totals = { upgraded: 0, elevationHinted: [], darkFirst: [], displayHinted: [] };
-  for (const slug of slugs) {
-    const dir = join(tokensDir, slug);
-    const base = JSON.parse(readFileSync(join(dir, "design.tokens.json"), "utf8"));
-    const resolver = JSON.parse(readFileSync(join(dir, "design.resolver.json"), "utf8"));
-    const darkPath = join(dir, "design.tokens.dark.json");
-    const dark = existsSync(darkPath) ? JSON.parse(readFileSync(darkPath, "utf8")) : null;
-
-    const stats = upgradeArtifact(base, dark, resolver, readDesignMd(slug), slug);
-    writeFileSync(join(dir, "design.tokens.json"), JSON.stringify(base, null, 2) + "\n");
-    writeFileSync(join(dir, "design.resolver.json"), JSON.stringify(resolver, null, 2) + "\n");
-    if (dark !== null) writeFileSync(darkPath, JSON.stringify(dark, null, 2) + "\n");
-
-    totals.upgraded++;
-    if (stats.elevationHinted) totals.elevationHinted.push(slug);
-    if (stats.darkFirst) totals.darkFirst.push(slug);
-    if (stats.displayHinted) totals.displayHinted.push(slug);
-    const marks = [stats.darkFirst ? "dark-first" : null, stats.elevationHinted ? "elevation hinted" : null, stats.displayHinted ? "display hinted" : "display assigned"].filter(Boolean);
-    console.log(`UPGRADE OK   ${slug}  (${marks.join(", ")})`);
-  }
-  console.log(`\nupgraded: ${totals.upgraded}`);
-  console.log(`elevation hinted (design.md names shadow values): ${totals.elevationHinted.length} — ${totals.elevationHinted.join(", ") || "none"}`);
-  console.log(`dark-first (theme-default: dark): ${totals.darkFirst.join(", ") || "none"}`);
-  console.log(`display hinted: ${totals.displayHinted.length} of ${totals.upgraded}`);
-  return totals;
-}
-
-// ---------------------------------------------------------------------------
-// Validation — SCHEMA.md rules 2–10 over an emitted artifact directory
-// ---------------------------------------------------------------------------
-
-// Collect every token in the artifact as path → token for alias resolution and type sweeps.
-function collectTokens(doc) {
-  const tokens = new Map();
-  const walk = (node, path) => {
-    if (node && typeof node === "object" && "$type" in node) { tokens.set(path.join("."), node); return; }
-    if (node && typeof node === "object") {
-      for (const [k, v] of Object.entries(node)) if (!k.startsWith("$")) walk(v, [...path, k]);
-    }
-  };
-  walk(doc, []);
-  return tokens;
-}
-
-// Resolve an alias chain to its target token; records an error string instead on failure.
-function resolveAlias(ref, tokens, errors, context) {
-  const seen = new Set();
-  let cur = ref;
-  while (typeof cur === "string" && /^\{[^}]+\}$/.test(cur)) {
-    const path = cur.slice(1, -1);
-    if (seen.has(path)) { errors.push(`${context}: alias cycle through {${path}}`); return null; }
-    seen.add(path);
-    const target = tokens.get(path);
-    if (!target) { errors.push(`${context}: alias {${path}} does not resolve`); return null; }
-    cur = target.$value;
-    if (typeof cur !== "string" || !/^\{[^}]+\}$/.test(cur)) return target;
-  }
-  return null;
-}
-
-// 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") { errors.push(`${name}: color token missing preserved .css`); return; }
-  let reparsed;
-  try { reparsed = parseColorCss(css); } catch (e) { errors.push(`${name}: ${e.message}`); return; }
-  if (JSON.stringify(reparsed) !== JSON.stringify(token.$value)) {
-    errors.push(`${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(`${name}: srgb components do not round-trip through hex ${token.$value.hex}`);
-    }
-  }
-}
-
-// Validate one artifact directory against SCHEMA.md rules 2–10 (plus the type whitelist); returns error strings.
-function validateArtifact(dir) {
-  const errors = [];
-  const read = (f) => JSON.parse(readFileSync(join(dir, f), "utf8"));
-  let doc, resolver;
-  try { doc = read("design.tokens.json"); } catch (e) { return [`design.tokens.json: ${e.message}`]; }
-  try { resolver = read("design.resolver.json"); } catch (e) { return [`design.resolver.json: ${e.message}`]; }
-
-  // An alias-valued token ("{path.to.token}") defers shape/.css to its target (rule 6 resolves it).
-  const isAliasValue = (t) => typeof t?.$value === "string" && /^\{[^}]+\}$/.test(t.$value);
-
-  // Rule 2 — payload.
-  const payload = doc.$extensions?.[EXT];
-  if (!payload) { errors.push("payload: missing $extensions[com.nurix.design] on the base root"); return errors; }
-  if (payload.schema !== "design-tokens/v2") errors.push(`payload.schema: ${payload.schema}`);
-  if (payload.dtcg !== "2025.10") errors.push(`payload.dtcg: ${payload.dtcg}`);
-  if (!payload.product) errors.push("payload.product: empty");
-  if (!LEGAL_PROVENANCE.includes(payload.provenance)) errors.push(`payload.provenance: ${payload.provenance}`);
-  if (!/^\d{4}-\d{2}-\d{2}$/.test(payload.sourced ?? "")) errors.push(`payload.sourced: ${payload.sourced}`);
-  if (!LEGAL_VERBOSITY.includes(payload.verbosity)) errors.push(`payload.verbosity: ${payload.verbosity}`);
-  if (!LEGAL_FEEDBACK.includes(payload.feedback)) errors.push(`payload.feedback: ${payload.feedback}`);
-  if (!LEGAL_DENSITY.includes(payload["density-tier"])) errors.push(`payload.density-tier: ${payload["density-tier"]}`);
-  if (!Array.isArray(payload["product-traits"]) || payload["product-traits"].length === 0) errors.push("payload.product-traits: empty");
-  if (payload["theme-default"] !== undefined && !["light", "dark"].includes(payload["theme-default"])) errors.push(`payload.theme-default: ${payload["theme-default"]}`);
-  if (payload.anchors !== undefined && (!Array.isArray(payload.anchors) || payload.anchors.length < 2 || payload.anchors.length > 3 || payload.anchors.some((a) => typeof a !== "string" || a.trim() === ""))) {
-    errors.push(`payload.anchors: must be 2–3 non-empty strings (${JSON.stringify(payload.anchors)})`);
-  }
-  const lm = payload["lever-manifest"];
-  for (const key of ["spacing-scale", "radius-scale", "shadow-levels", "motion", "icons", "accent-count"]) {
-    if (lm?.[key] === undefined) errors.push(`lever-manifest.${key}: missing`);
-  }
-  if (errors.length > 0) return errors;
-
-  // Rule 3 — primitive coverage with exact $type.
-  for (const [key, type] of PRIMITIVE_TYPES_V2) {
-    const t = doc.primitive?.[key];
-    if (!t) errors.push(`primitive.${key}: missing`);
-    else if (t.$type !== type) errors.push(`primitive.${key}: $type ${t.$type} (want ${type})`);
-    else if (t.$value === undefined || t.$value === "") errors.push(`primitive.${key}: empty $value`);
-  }
-  const stagger = doc.primitive?.["stagger-unit"]?.$value?.value;
-  if (typeof stagger === "number" && (stagger < 0 || stagger > 60)) errors.push(`primitive.stagger-unit: ${stagger}ms outside 0–60ms`);
-
-  // Rule 4 — color coverage (an aliased role takes its target's shape and .css).
-  for (const role of COLOR_ROLES_V2) {
-    const t = doc.color?.[role];
-    if (!t) { errors.push(`color.${role}: missing`); continue; }
-    if (t.$type !== "color") errors.push(`color.${role}: $type ${t.$type}`);
-    if (isAliasValue(t)) continue;
-    if (!["oklch", "srgb"].includes(t.$value?.colorSpace)) errors.push(`color.${role}: colorSpace ${t.$value?.colorSpace}`);
-    if (typeof t.$extensions?.[EXT]?.css !== "string") errors.push(`color.${role}: missing .css`);
-  }
-
-  // Rule 5 — typography coverage (the seven-step ramp; family.display optional).
-  for (const fam of ["heading", "body", "mono"]) {
-    const t = doc.typography?.family?.[fam];
-    if (!t || t.$type !== "fontFamily") errors.push(`typography.family.${fam}: missing or mistyped`);
-  }
-  if (doc.typography?.family?.display !== undefined && doc.typography.family.display.$type !== "fontFamily") {
-    errors.push("typography.family.display: mistyped (optional slot, fontFamily shape)");
-  }
-  for (const step of RAMP_STEPS_V2) {
-    const t = doc.typography?.ramp?.[step];
-    if (!t || t.$type !== "typography") { errors.push(`typography.ramp.${step}: missing or mistyped`); continue; }
-    for (const sub of ["fontFamily", "fontSize", "fontWeight", "letterSpacing", "lineHeight"]) {
-      if (t.$value?.[sub] === undefined) errors.push(`typography.ramp.${step}.${sub}: missing sub-value`);
-    }
-  }
-
-  // Elevation coverage (rule 13) — four shadow composites, byte form preserved and parse-backed.
-  for (const level of ELEVATION_TOKENS) {
-    const t = doc.elevation?.[level];
-    if (!t || t.$type !== "shadow") { errors.push(`elevation.${level}: missing or not $type shadow`); continue; }
-    if (!Array.isArray(t.$value) || t.$value.length === 0) { errors.push(`elevation.${level}: $value must be a non-empty layer array`); continue; }
-    const css = t.$extensions?.[EXT]?.css;
-    if (typeof css !== "string") { errors.push(`elevation.${level}: missing .css`); continue; }
-    try {
-      if (JSON.stringify(parseShadowCss(css)) !== JSON.stringify(t.$value)) errors.push(`elevation.${level}: css does not parse back to $value`);
-    } catch (e) {
-      errors.push(`elevation.${level}: ${e.message}`);
-    }
-  }
-
-  // Wash shape (rule 14) — optional group, ≤ 2 gradient tokens.
-  if (doc.wash !== undefined) {
-    const washKeys = Object.keys(doc.wash).filter((k) => !k.startsWith("$"));
-    if (washKeys.length > 2) errors.push(`wash: at most 2 tokens (found ${washKeys.length})`);
-    for (const key of washKeys) {
-      if (!["surface", "emphasis"].includes(key)) errors.push(`wash.${key}: not a legal slot`);
-      else if (doc.wash[key].$type !== "gradient") errors.push(`wash.${key}: not $type gradient`);
-    }
-  }
-  if (errors.length > 0) return errors;
-
-  // Rule 6 — alias integrity (token values and composite sub-values), with type expectations.
-  const tokens = collectTokens(doc);
-  const expectType = (ref, want, context) => {
-    const target = resolveAlias(ref, tokens, errors, context);
-    if (target && want && target.$type !== want) errors.push(`${context}: alias ${ref} resolves to $type ${target.$type} (want ${want})`);
-  };
-  for (const [path, token] of tokens) {
-    if (typeof token.$value === "string" && token.$value.startsWith("{")) expectType(token.$value, token.$type, path);
-    if (token.$type === "typography") {
-      const subTypes = { fontFamily: "fontFamily", fontWeight: "fontWeight", letterSpacing: "number", fontSize: "dimension" };
-      for (const [sub, want] of Object.entries(subTypes)) {
-        const v = token.$value[sub];
-        if (typeof v === "string" && v.startsWith("{")) expectType(v, want, `${path}.${sub}`);
-      }
-    }
-  }
-
-  // Rule 7 — manifest scales.
-  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(`lever-manifest.${key}: not non-empty ascending`);
-  }
-  if (!Array.isArray(lm.motion.durations) || lm.motion.durations.length === 0 || !ascending(lm.motion.durations)) errors.push("lever-manifest.motion.durations: not non-empty ascending");
-  if (!Array.isArray(lm.motion.easings) || lm.motion.easings.length === 0) errors.push("lever-manifest.motion.easings: empty");
-  const ranks = (lm["shadow-levels"] ?? []).map((s) => SHADOW_RANK[s]);
-  if (ranks.length === 0 || ranks.some((r) => r === undefined) || !ascending(ranks)) errors.push(`lever-manifest.shadow-levels: ${JSON.stringify(lm["shadow-levels"])}`);
-  if (!lm.icons?.family) errors.push("lever-manifest.icons.family: empty");
-  if (!(lm["accent-count"] >= 1)) errors.push(`lever-manifest.accent-count: ${lm["accent-count"]}`);
-
-  // Rule 8 — the look's own base values sit on its own allowlist; an off-manifest value is legal
-  // only as a recorded deviation (a deviation: $description — rule 15's vocabulary).
-  const deviationTagged = (t) => typeof t?.$description === "string" && t.$description.startsWith("deviation:");
-  if (!lm["radius-scale"].includes(doc.primitive.radius.$value.value) && !deviationTagged(doc.primitive.radius)) errors.push(`radius ${doc.primitive.radius.$value.value} not on radius-scale`);
-  for (const key of ["duration-fast", "duration-normal", "duration-slow"]) {
-    if (!lm.motion.durations.includes(doc.primitive[key].$value.value) && !deviationTagged(doc.primitive[key])) errors.push(`${key} ${doc.primitive[key].$value.value} not in motion.durations`);
-  }
-  const easeCss = doc.primitive["ease-default"].$extensions?.[EXT]?.css;
-  if (!lm.motion.easings.includes(easeCss) && !deviationTagged(doc.primitive["ease-default"])) errors.push(`ease-default ${easeCss} not in motion.easings`);
-
-  // Rule 9 — parse-back for every preserved .css (aliased roles carry none).
-  for (const role of COLOR_ROLES_V2) {
-    if (!isAliasValue(doc.color[role])) verifyColorParseBack(`color.${role}`, doc.color[role], errors);
-  }
-  const ht = doc.primitive["heading-tracking"];
-  const htCss = ht.$extensions?.[EXT]?.css;
-  if (typeof htCss !== "string") errors.push("primitive.heading-tracking: missing .css");
-  else if (parseTrackingCss(htCss) !== ht.$value) errors.push(`primitive.heading-tracking: css ${htCss} != $value ${ht.$value}`);
-  if (easeCss === undefined) errors.push("primitive.ease-default: missing .css");
-  else if (JSON.stringify(parseCubicBezierCss(easeCss)) !== JSON.stringify(doc.primitive["ease-default"].$value)) errors.push("primitive.ease-default: css/$value mismatch");
-  for (const key of ["font-sans", "font-mono"]) {
-    const t = doc.primitive[key];
-    const css = t.$extensions?.[EXT]?.css;
-    if (typeof css !== "string") { errors.push(`primitive.${key}: missing .css`); continue; }
-    if (JSON.stringify(parseFontStackCss(css)) !== JSON.stringify(t.$value)) errors.push(`primitive.${key}: css/$value mismatch`);
-  }
-  for (const step of RAMP_STEPS_V2) {
-    const t = doc.typography.ramp[step];
-    const css = t.$extensions?.[EXT]?.css;
-    if (css?.letterSpacing !== undefined) {
-      const reparsed = parseLetterSpacingCss(css.letterSpacing, t.$value.fontSize.value);
-      if (reparsed !== t.$value.letterSpacing) errors.push(`typography.ramp.${step}: letterSpacing css ${css.letterSpacing} → ${reparsed} != ${t.$value.letterSpacing}`);
-    }
-  }
-
-  // Rule 10 + resolver coherence — the dark file carries exactly the 36-role color group; the
-  // resolver's theme default mirrors the payload's theme-default.
-  const darkNamed = resolver.modifiers?.[0]?.contexts?.dark !== undefined;
-  const darkExists = existsSync(join(dir, "design.tokens.dark.json"));
-  if (darkNamed !== darkExists) errors.push(`dark file/resolver mismatch: named=${darkNamed} exists=${darkExists}`);
-  if (resolver.schema !== "design-resolver/v1") errors.push(`resolver.schema: ${resolver.schema}`);
-  const expectedDefault = payload["theme-default"] ?? "light";
-  if (resolver.modifiers?.[0]?.default !== expectedDefault) errors.push(`resolver: theme default ${resolver.modifiers?.[0]?.default} does not mirror payload theme-default ${expectedDefault}`);
-  if (darkExists) {
-    const dark = read("design.tokens.dark.json");
-    const rootKeys = Object.keys(dark);
-    if (rootKeys.length !== 1 || rootKeys[0] !== "color") errors.push(`dark file: root keys ${rootKeys.join(",")} (want exactly color)`);
-    for (const role of COLOR_ROLES_V2) {
-      const t = dark.color?.[role];
-      if (!t || t.$type !== "color") { errors.push(`dark color.${role}: missing or mistyped`); continue; }
-      if (!isAliasValue(t)) verifyColorParseBack(`dark color.${role}`, t, errors);
-    }
-    for (const role of Object.keys(dark.color ?? {})) if (!COLOR_ROLES_V2.includes(role)) errors.push(`dark color.${role}: not a legal role`);
-  }
-
-  // Rule 11 (type whitelist sweep) — only the ten legal $type values appear.
-  for (const [path, token] of tokens) {
-    if (!LEGAL_TYPES.includes(token.$type)) errors.push(`${path}: illegal $type ${token.$type}`);
-  }
-  return errors;
-}
-
-// ---------------------------------------------------------------------------
-// Strip mode — remove the machine blocks and their orphaned prose references
-// ---------------------------------------------------------------------------
-
-// A sentence or parenthetical that references the (removed) machine blocks.
-const ORPHAN_PATTERN = /machine blocks?|machine-carried|lever[- ]manifest|design-primitives|`hint:`|manifest carries|manifest ships|manifest holds|the manifest|manifest's|both blocks/i;
-// A reference to the in-block `# rationale:` / `# derived:` comment convention — also orphaned by the strip.
-const ANNOTATION_PATTERN = /`# ?(rationale|derived|corpus|note)/i;
-
-// Re-wrap a paragraph's text at ~100 columns, preserving a leading indent/bullet prefix.
-function rewrap(text, prefix = "", width = 100) {
-  const words = text.split(/\s+/).filter((w) => w !== "");
-  const lines = [];
-  let cur = prefix;
-  let bare = prefix.replace(/\S/g, " ");
-  for (const w of words) {
-    if (cur.trim() === "" || (cur + " " + w).length <= width) cur = cur.trim() === "" && cur === prefix ? prefix + w : cur + " " + w;
-    else { lines.push(cur); cur = bare + w; }
-  }
-  if (cur.trim() !== "") lines.push(cur);
-  return lines;
-}
-
-// Lossless sentence split: cut after . ! ? only when a new sentence plausibly starts (whitespace + capital/opener).
-function splitSentences(text) {
-  const out = [];
-  let start = 0;
-  for (let i = 0; i < text.length; i++) {
-    if (".!?".includes(text[i]) && /^\s+["'*(\[`—A-Z0-9]/.test(text.slice(i + 1))) {
-      const end = i + 1 + /^\s+/.exec(text.slice(i + 1))[0].length;
-      out.push(text.slice(start, end));
-      start = end;
-    }
-  }
-  if (start < text.length) out.push(text.slice(start));
-  return out;
-}
-
-// Remove orphaned block-referencing parentheticals and sentences from one prose paragraph; null = unchanged.
-function stripParagraph(lines) {
-  const joined = lines.map((l) => l.trim()).join(" ");
-  // 1. surgical: drop "(…)" parentheticals whose content references the blocks.
-  let text = joined.replace(/\s*\(([^()]*)\)/g, (m, inner) => (ORPHAN_PATTERN.test(inner) ? "" : m));
-  // 2. clause-level: drop a "; …" clause that only cites the annotation convention, keeping its sentence.
-  text = text.replace(/;\s*[^.!?;]*`# ?(rationale|derived|corpus|note)[^.!?]*?(?=[.!?])/gi, "");
-  // 3. sentence-level: drop whole sentences that still reference the blocks or their annotations.
-  const sentences = splitSentences(text);
-  if (sentences.join("") !== text) throw new Error(`lossy sentence split in: ${text.slice(0, 80)}…`);
-  text = sentences.filter((s) => !ORPHAN_PATTERN.test(s) && !ANNOTATION_PATTERN.test(s)).join("").trim();
-  if (text === joined) return null;
-  if (text === "") return [];
-  const m = /^(\s*(?:[-*]\s+|\d+\.\s+)?)/.exec(lines[0]);
-  return rewrap(text, m[1] ?? "");
-}
-
-// Strip both machine blocks (and orphaned prose) from one source text; returns { text, summary }.
-function stripSource(source) {
-  const summary = { blocksRemoved: 0, paragraphsEdited: 0 };
-  let text = source;
-  for (const label of ["design-primitives", "lever-manifest"]) {
-    const re = new RegExp("\\n*^`{3,}\\s*yaml\\s+" + label + "\\s*$\\n[\\s\\S]*?^`{3,}\\s*$\\n?", "m");
-    if (re.test(text)) { text = text.replace(re, "\n"); summary.blocksRemoved++; }
-  }
-
-  // Paragraph pass: skip frontmatter, headings, tables, and fenced code — only plain prose is edited.
-  const lines = text.split("\n");
-  const out = [];
-  let i = 0;
-  let inFence = false;
-  if (lines[0] === "---") {
-    out.push(lines[0]);
-    for (i = 1; i < lines.length; i++) { out.push(lines[i]); if (lines[i] === "---") { i++; break; } }
-  }
-  while (i < lines.length) {
-    const line = lines[i];
-    if (/^`{3,}/.test(line.trim())) inFence = !inFence;
-    const isProse = !inFence && line.trim() !== "" && !/^(#|\||`{3,}|>)/.test(line.trim());
-    if (!isProse) { out.push(line); i++; continue; }
-    const para = [];
-    while (i < lines.length && lines[i].trim() !== "" && !/^(#|\||`{3,}|>)/.test(lines[i].trim())) {
-      // a new bullet starts a new paragraph unit
-      if (para.length > 0 && /^\s*[-*]\s+/.test(lines[i])) break;
-      para.push(lines[i]); i++;
-    }
-    const replaced = stripParagraph(para);
-    if (replaced === null) out.push(...para);
-    else { summary.paragraphsEdited++; out.push(...replaced); }
-  }
-  let result = out.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\n*$/, "\n");
-  return { text: result, summary };
-}
-
-// ---------------------------------------------------------------------------
-// Drivers
-// ---------------------------------------------------------------------------
-
-// Enumerate the source entries: nurix.md + every library/*.md, slug = filename minus .md.
-function listSources() {
-  const entries = [{ slug: "nurix", path: join(designMdDir, "nurix.md") }];
-  for (const f of readdirSync(join(designMdDir, "library")).filter((f) => f.endsWith(".md")).sort()) {
-    entries.push({ slug: basename(f, ".md"), path: join(designMdDir, "library", f) });
-  }
-  return entries;
-}
-
-function runConvert(only, reportPath) {
-  const sources = listSources().filter((s) => !only || s.slug === only);
-  if (sources.length === 0) fail(`no source entry named ${only}`);
-  const report = { converted: [], failed: [], totals: { migrated: 0, rootAttached: 0, dropped: 0, hints: 0, darkFiles: [], fontDrops: 0 } };
-
-  for (const { slug, path } of sources) {
-    let result;
-    try {
-      const sourceText = readFileSync(path, "utf8");
-      result = convertEntry(sourceText, slug);
-      // The converter emits the v2 schema: the same idempotent upgrade transform the migration
-      // mode runs, applied to the freshly converted (v1-shaped) documents.
-      upgradeArtifact(result.base, result.dark, result.resolver, sourceText, slug);
-    } catch (e) {
-      report.failed.push({ slug, error: e.message });
-      console.log(`CONVERT FAIL ${slug}: ${e.message}`);
-      continue;
-    }
-    const dir = join(tokensDir, slug);
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, "design.tokens.json"), JSON.stringify(result.base, null, 2) + "\n");
-    writeFileSync(join(dir, "design.resolver.json"), JSON.stringify(result.resolver, null, 2) + "\n");
-    if (result.dark) writeFileSync(join(dir, "design.tokens.dark.json"), JSON.stringify(result.dark, null, 2) + "\n");
-
-    const n = result.notes;
-    report.converted.push({ slug, migrated: n.migrated, rootAttached: n.rootAttached, dropped: n.dropped, hints: n.hints, ramp: n.ramp, drops: n.drops, irregularities: n.irregularities, darkFile: n.darkFile });
-    report.totals.migrated += n.migrated;
-    report.totals.rootAttached += n.rootAttached.length;
-    report.totals.dropped += n.dropped.length;
-    report.totals.hints += n.hints.length;
-    if (n.darkFile) report.totals.darkFiles.push(slug);
-    if (n.drops.some((d) => d.startsWith("fonts"))) report.totals.fontDrops++;
-    console.log(`CONVERT OK   ${slug}  (annotations: ${n.migrated}${n.darkFile ? ", dark" : ""}${n.hints.length ? `, hints: ${n.hints.length}` : ""})`);
-  }
-
-  // _dropped: comments that landed nowhere. Non-token comments are preserved on the root $description
-  // and listed per entry as rootAttached — reported here so nothing disappears silently.
-  const droppedReport = report.converted.flatMap((e) => e.dropped.map((d) => ({ slug: e.slug, ...d })));
-  console.log(`\n_dropped (unattachable comments): ${droppedReport.length}`);
-  for (const d of droppedReport) console.log(`  ${d.slug}: ${JSON.stringify(d)}`);
-  const rootAttached = report.converted.flatMap((e) => e.rootAttached.map((r) => ({ slug: e.slug, ...r })));
-  console.log(`non-token comments preserved on root $description: ${rootAttached.length}`);
-  for (const r of rootAttached) console.log(`  ${r.slug} [${r.where}] ${r.comment}`);
-
-  if (reportPath) writeFileSync(reportPath, JSON.stringify(report, null, 2) + "\n");
-  return report;
-}
-
-function runValidate(only) {
-  const sources = listSources().filter((s) => !only || s.slug === only);
-  let pass = 0, failCount = 0;
-  for (const { slug } of sources) {
-    const dir = join(tokensDir, slug);
-    if (!existsSync(join(dir, "design.tokens.json"))) { console.log(`VALIDATE FAIL ${slug}: no artifact`); failCount++; continue; }
-    let errors;
-    try { errors = validateArtifact(dir); } catch (e) { errors = [`validator crash: ${e.message}`]; }
-    if (errors.length === 0) { console.log(`VALIDATE OK   ${slug}`); pass++; }
-    else {
-      failCount++;
-      console.log(`VALIDATE FAIL ${slug}`);
-      for (const err of errors) console.log(`    ${err}`);
-    }
-  }
-  console.log(`\nvalidation: ${pass} passed, ${failCount} failed of ${sources.length}`);
-  return failCount === 0;
-}
-
-function runStrip(paths) {
-  if (paths.length === 0) fail("--strip requires explicit file paths (it rewrites sources in place; never run it implicitly)");
-  for (const p of paths) {
-    const abs = resolve(p);
-    const { text, summary } = stripSource(readFileSync(abs, "utf8"));
-    writeFileSync(abs, text);
-    console.log(`STRIP ${abs}: ${summary.blocksRemoved} machine block(s) removed, ${summary.paragraphsEdited} paragraph(s) edited`);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// CLI
-// ---------------------------------------------------------------------------
-
-const args = process.argv.slice(2);
-const flag = (name) => args.includes(name);
-const opt = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : null; };
-
-if (flag("--strip")) {
-  runStrip(args.slice(args.indexOf("--strip") + 1).filter((a) => !a.startsWith("--")));
-} else if (flag("--upgrade-v2")) {
-  runUpgradeV2(opt("--only"));
-  process.exit(runValidate(opt("--only")) ? 0 : 1);
-} else if (flag("--validate")) {
-  process.exit(runValidate(opt("--only")) ? 0 : 1);
-} else {
-  const report = runConvert(opt("--only"), opt("--report"));
-  const ok = runValidate(opt("--only"));
-  console.log(`\nconverted: ${report.converted.length}, failed: ${report.failed.length}`);
-  console.log(`annotations migrated to token $description: ${report.totals.migrated}`);
-  console.log(`dark files: ${report.totals.darkFiles.join(", ") || "none"}`);
-  console.log(`source hints found: ${report.totals.hints}`);
-  console.log(`manifest fonts duplication dropped: ${report.totals.fontDrops} entries`);
-  process.exit(ok && report.failed.length === 0 ? 0 : 1);
-}