@nurix/etna 0.19.3 → 0.19.4

package/data/harnesses/code/skills/design/references/structure.md

@@ -49,6 +49,22 @@ Membership is closed. New archetypes enter only as pack data, ledger-recorded
 
 **Navigation derives from the object model, never decorated on.** Top-level nav entries are the primary entities and their home surfaces; secondary entities are reached through their parent's detail surface, not promoted. The unit of work is the home. Cap top-level entries at what stays countable on one hand — nav categories the model does not carry are a structural defect, not a convenience.
 
+## The delight budget — permission is structural
+
+The object pass classifies **every** surface with a mandatory `budget` — `baseline` or `brand-forward`. Permission is a structural fact decided here, not a look value: the budget grants which token *vocabulary* a surface may consume, never a value. `scaffold.mjs` stamps the budget into each route file's header comment (`// Surface: baseline` / `// Surface: brand-forward (delight-allowing)`); `phase-gate.mjs surfaces` reads the stamp back.
+
+**Defaults by archetype** — assign the default, override only against a recorded reason:
+
+| Archetype | Default | Note |
+| --- | --- | --- |
+| `list-detail`, `log-stream`, `command-center` | `baseline` | throughput surfaces; decoration is noise here |
+| `dashboard`, `entity-detail` (header region), `create-edit` (empty / success moments) | `brand-forward` **candidate** | granted when the look's `delight` is `expressive` or the brief asks for presence; else `baseline` |
+
+- **Overridable, against a recorded reason.** A budget that contradicts the archetype default — a `brand-forward` stamp on a `baseline`-default archetype — carries a `budget-reason` on that surface entry, or the surfaces gate fails. Candidacy is not a grant: a candidate archetype still defaults `baseline` and only rises to `brand-forward` when the look or brief earns it.
+- **`baseline` blocks decoration, never signal.** A `baseline` stamp never suppresses status or feedback color — error red, warning amber, the success tick all render at every budget. It withholds *ornament*: the display ramp step, elevation lifts, washes, arrival motion.
+- **What `brand-forward` unlocks** — all still tokens, all still on-scale: the `display` ramp step (one per surface), `elevation.lg`, the `wash.*` tokens, the motion moments in `motion.csv`, and the generous spacing tier.
+- **What no budget ever unlocks:** literal colors, off-manifest values, slop-gradient vocabulary, serif in dashboards. The floor is budget-independent — a brand-forward surface clears the same rules a baseline one does. Expressiveness is granted *inside* the floor, never as an exception to it.
+
 ## The map: `docs/design/structure.md`
 
 The derivation's whole output. Human prose above the block; the fenced `yaml structure` block is the machine contract — `scaffold.mjs` reads it, so the field names are law. Scaffold generates routes, navigation wiring, and per-surface state-shell stubs from `surfaces[]`, and keys fixture wiring off `entities[]`.
@@ -73,6 +89,8 @@ surfaces:
     route: /<path>
     entity: <Entity>
     density-modifier: <integer step; positive = denser; mirrors the catalog's per-archetype modifier>
+    budget: baseline | brand-forward           # mandatory; the surface's delight budget
+    budget-reason: <one line>                  # required only when budget overrides the archetype default
     states: [loading, empty, error, partial]   # applicable subset; data surfaces carry all four
 ```
 
@@ -120,19 +138,22 @@ surfaces:
     route: /tickets
     entity: Ticket
     density-modifier: 1
+    budget: baseline
     states: [loading, empty, error, partial]
   - name: Ticket Detail
     archetype: entity-detail
     route: /tickets/:id
     entity: Ticket
     density-modifier: 0
+    budget: baseline
     states: [loading, empty, error, partial]
   - name: New Ticket
     archetype: create-edit
     route: /tickets/new
     entity: Ticket
     density-modifier: -1
+    budget: baseline
     states: [loading, error]
 ```
 
-Navigation: top-level is **Tickets** — the unit of work's home. Customer and Agent are reached through Ticket Detail, not promoted to top-level nav (derived, not decorated). History — the audit of status changes and replies — surfaces as a timeline on the detail, not a fifth temporal key. OOUX pass: the status pill renders identically on queue and detail (no Shapeshifter), and Customer links out to its own detail rather than living only as a string (no Masked).
+Navigation: top-level is **Tickets** — the unit of work's home. Customer and Agent are reached through Ticket Detail, not promoted to top-level nav (derived, not decorated). History — the audit of status changes and replies — surfaces as a timeline on the detail, not a fifth temporal key. OOUX pass: the status pill renders identically on queue and detail (no Shapeshifter), and Customer links out to its own detail rather than living only as a string (no Masked). Budgets: every surface stamps `baseline` — the brief states no expressive delight, so the two candidate archetypes (Ticket Detail's header, New Ticket's success moment) stay at their default; a queue is `baseline` outright. No `budget-reason` is needed because no stamp overrides an archetype default.

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

@@ -1,10 +1,11 @@
 #!/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.
+// 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)
@@ -22,7 +23,8 @@ 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.
+// 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"],
@@ -40,7 +42,12 @@ const PRIMITIVE_TYPES = new Map([
 ]);
 const PRIMITIVES = [...PRIMITIVE_TYPES.keys()];
 
-// The 34 color roles in emission order (17 semantic + 17 substrate).
+// 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",
@@ -51,7 +58,12 @@ const COLOR_ROLES = [
   "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"];
 
@@ -59,8 +71,8 @@ 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 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).
@@ -151,16 +163,38 @@ function parseColorCss(css) {
     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 = parseFloat(m[4]);
+    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());
@@ -637,6 +671,202 @@ function convertEntry(source, slug) {
   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
 // ---------------------------------------------------------------------------
@@ -696,10 +926,13 @@ function validateArtifact(dir) {
   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/v1") errors.push(`payload.schema: ${payload.schema}`);
+  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}`);
@@ -708,6 +941,10 @@ function validateArtifact(dir) {
   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`);
@@ -715,34 +952,64 @@ function validateArtifact(dir) {
   if (errors.length > 0) return errors;
 
   // Rule 3 — primitive coverage with exact $type.
-  for (const [key, type] of PRIMITIVE_TYPES) {
+  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.
-  for (const role of COLOR_ROLES) {
+  // 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.
+  // 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`);
   }
-  for (const step of RAMP_STEPS) {
+  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.
@@ -774,16 +1041,20 @@ function validateArtifact(dir) {
   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`);
+  // 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)) errors.push(`${key} ${doc.primitive[key].$value.value} not in motion.durations`);
+    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)) errors.push(`ease-default ${easeCss} not in motion.easings`);
+  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.
-  for (const role of COLOR_ROLES) verifyColorParseBack(`color.${role}`, doc.color[role], errors);
+  // 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");
@@ -796,7 +1067,7 @@ function validateArtifact(dir) {
     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) {
+  for (const step of RAMP_STEPS_V2) {
     const t = doc.typography.ramp[step];
     const css = t.$extensions?.[EXT]?.css;
     if (css?.letterSpacing !== undefined) {
@@ -805,25 +1076,27 @@ function validateArtifact(dir) {
     }
   }
 
-  // Rule 10 + resolver coherence — the dark file carries exactly the 34-role color group.
+  // 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}`);
-  if (resolver.modifiers?.[0]?.default !== "light") errors.push("resolver: theme default must be light");
+  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) {
+    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; }
-      verifyColorParseBack(`dark color.${role}`, t, errors);
+      if (!isAliasValue(t)) 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`);
+    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 eight legal $type values appear.
+  // 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}`);
   }
@@ -943,7 +1216,11 @@ function runConvert(only, reportPath) {
   for (const { slug, path } of sources) {
     let result;
     try {
-      result = convertEntry(readFileSync(path, "utf8"), slug);
+      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}`);
@@ -1018,6 +1295,9 @@ const opt = (name) => { const i = args.indexOf(name); return i >= 0 ? args[i + 1
 
 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 {