@nurix/etna 0.18.20 → 0.18.21

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

@@ -0,0 +1,1032 @@
+#!/usr/bin/env node
+// skills/design/scripts/convert-design-md.mjs — mechanical design.md → design-tokens converter (schema design-tokens/v1, 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, self-validates (schema rules 2–10), and offers --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 --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 visual primitives in emission order, with their DTCG $type.
+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 34 color roles in emission order (17 semantic + 17 substrate).
+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",
+];
+
+const RAMP_STEPS = ["h1", "h2", "h3", "body", "small", "caption"];
+// 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"];
+const SHADOW_RANK = { none: 0, "2xs": 1, xs: 2, sm: 3, md: 4, lg: 5, xl: 6, "2xl": 7 };
+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) {
+    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 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 };
+}
+
+// ---------------------------------------------------------------------------
+// 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}`]; }
+
+  // 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/v1") 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");
+  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) {
+    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`);
+  }
+
+  // Rule 4 — color coverage.
+  for (const role of COLOR_ROLES) {
+    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 (!["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.
+  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`);
+  }
+  for (const step of RAMP_STEPS) {
+    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`);
+    }
+  }
+  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.
+  if (!lm["radius-scale"].includes(doc.primitive.radius.$value.value)) 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)) 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)) errors.push(`ease-default ${easeCss} not in motion.easings`);
+
+  // Rule 9 — parse-back for every preserved .css.
+  for (const role of COLOR_ROLES) 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) {
+    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 34-role color group.
+  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}`);
+  if (resolver.modifiers?.[0]?.default !== "light") errors.push("resolver: theme default must be light");
+  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) {
+      const t = dark.color?.[role];
+      if (!t || t.$type !== "color") { errors.push(`dark color.${role}: missing or mistyped`); continue; }
+      verifyColorParseBack(`dark color.${role}`, t, errors);
+    }
+    for (const role of Object.keys(dark.color ?? {})) if (!COLOR_ROLES.includes(role)) errors.push(`dark color.${role}: not a legal role`);
+  }
+
+  // Rule 11 (type whitelist sweep) — only the eight 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 {
+      result = convertEntry(readFileSync(path, "utf8"), 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("--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);
+}