spec-layer 0.9.0 → 0.10.0

package/dist/cli.js

@@ -262,7 +262,7 @@ var require_sha256 = __commonJS({
           }
           notString = true;
         }
-        var code2, index = 0, i, length = message.length, blocks2 = this.blocks;
+        var code3, index = 0, i, length = message.length, blocks2 = this.blocks;
         while (index < length) {
           if (this.hashed) {
             this.hashed = false;
@@ -275,22 +275,22 @@ var require_sha256 = __commonJS({
             }
           } else {
             for (i = this.start; index < length && i < 64; ++index) {
-              code2 = message.charCodeAt(index);
-              if (code2 < 128) {
-                blocks2[i >>> 2] |= code2 << SHIFT[i++ & 3];
-              } else if (code2 < 2048) {
-                blocks2[i >>> 2] |= (192 | code2 >>> 6) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code2 & 63) << SHIFT[i++ & 3];
-              } else if (code2 < 55296 || code2 >= 57344) {
-                blocks2[i >>> 2] |= (224 | code2 >>> 12) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code2 >>> 6 & 63) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code2 & 63) << SHIFT[i++ & 3];
+              code3 = message.charCodeAt(index);
+              if (code3 < 128) {
+                blocks2[i >>> 2] |= code3 << SHIFT[i++ & 3];
+              } else if (code3 < 2048) {
+                blocks2[i >>> 2] |= (192 | code3 >>> 6) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code3 & 63) << SHIFT[i++ & 3];
+              } else if (code3 < 55296 || code3 >= 57344) {
+                blocks2[i >>> 2] |= (224 | code3 >>> 12) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code3 >>> 6 & 63) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code3 & 63) << SHIFT[i++ & 3];
               } else {
-                code2 = 65536 + ((code2 & 1023) << 10 | message.charCodeAt(++index) & 1023);
-                blocks2[i >>> 2] |= (240 | code2 >>> 18) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code2 >>> 12 & 63) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code2 >>> 6 & 63) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code2 & 63) << SHIFT[i++ & 3];
+                code3 = 65536 + ((code3 & 1023) << 10 | message.charCodeAt(++index) & 1023);
+                blocks2[i >>> 2] |= (240 | code3 >>> 18) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code3 >>> 12 & 63) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code3 >>> 6 & 63) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code3 & 63) << SHIFT[i++ & 3];
               }
             }
           }
@@ -472,24 +472,24 @@ var require_sha256 = __commonJS({
       function HmacSha256(key, is224, sharedMemory) {
         var i, type = typeof key;
         if (type === "string") {
-          var bytes = [], length = key.length, index = 0, code2;
+          var bytes = [], length = key.length, index = 0, code3;
           for (i = 0; i < length; ++i) {
-            code2 = key.charCodeAt(i);
-            if (code2 < 128) {
-              bytes[index++] = code2;
-            } else if (code2 < 2048) {
-              bytes[index++] = 192 | code2 >>> 6;
-              bytes[index++] = 128 | code2 & 63;
-            } else if (code2 < 55296 || code2 >= 57344) {
-              bytes[index++] = 224 | code2 >>> 12;
-              bytes[index++] = 128 | code2 >>> 6 & 63;
-              bytes[index++] = 128 | code2 & 63;
+            code3 = key.charCodeAt(i);
+            if (code3 < 128) {
+              bytes[index++] = code3;
+            } else if (code3 < 2048) {
+              bytes[index++] = 192 | code3 >>> 6;
+              bytes[index++] = 128 | code3 & 63;
+            } else if (code3 < 55296 || code3 >= 57344) {
+              bytes[index++] = 224 | code3 >>> 12;
+              bytes[index++] = 128 | code3 >>> 6 & 63;
+              bytes[index++] = 128 | code3 & 63;
             } else {
-              code2 = 65536 + ((code2 & 1023) << 10 | key.charCodeAt(++i) & 1023);
-              bytes[index++] = 240 | code2 >>> 18;
-              bytes[index++] = 128 | code2 >>> 12 & 63;
-              bytes[index++] = 128 | code2 >>> 6 & 63;
-              bytes[index++] = 128 | code2 & 63;
+              code3 = 65536 + ((code3 & 1023) << 10 | key.charCodeAt(++i) & 1023);
+              bytes[index++] = 240 | code3 >>> 18;
+              bytes[index++] = 128 | code3 >>> 12 & 63;
+              bytes[index++] = 128 | code3 >>> 6 & 63;
+              bytes[index++] = 128 | code3 & 63;
             }
           }
           key = bytes;
@@ -562,6 +562,609 @@ import { parseArgs } from "node:util";
 import { existsSync as existsSync8, readFileSync as readFileSync9 } from "node:fs";
 import { join as join8, resolve as resolve5 } from "node:path";
 
+// ../extractor/src/naming.ts
+function parseVariantName(name) {
+  const out = {};
+  for (const segment of name.split(",")) {
+    const [axis, ...rest] = segment.split("=");
+    if (!rest.length) return null;
+    out[axis.trim()] = rest.join("=").trim();
+  }
+  return out;
+}
+var WHITESPACE = /\s/;
+function cleanPartName(name) {
+  let end = name.length;
+  while (end > 0 && WHITESPACE.test(name[end - 1])) end--;
+  const afterHashes = end;
+  while (end > 0 && name[end - 1] === "#") end--;
+  return afterHashes === end ? name.trim() : name.slice(0, end).trim();
+}
+var cleanPropName = (raw) => raw.split("#")[0];
+function siblingPartNames(children) {
+  const counts = /* @__PURE__ */ new Map();
+  const out = /* @__PURE__ */ new Map();
+  for (const child of children) {
+    const base = cleanPartName(child.name);
+    const n = (counts.get(base) ?? 0) + 1;
+    counts.set(base, n);
+    out.set(child, n === 1 ? base : `${base} (${n})`);
+  }
+  return out;
+}
+function joinPath(parentPath, part) {
+  const escaped = part.replace(/\//g, "\\/");
+  return parentPath ? `${parentPath}/${escaped}` : escaped;
+}
+function walkParts(root, rootName, visit, skipInvisible = false, parentPath = "") {
+  if (typeof skipInvisible === "function" ? skipInvisible(root) : skipInvisible && root.visible === false) return;
+  const path = joinPath(parentPath, rootName);
+  visit(root, rootName, path);
+  const kids = root.children ?? [];
+  const names = siblingPartNames(kids);
+  for (const child of kids) {
+    walkParts(child, names.get(child), visit, skipInvisible, path);
+  }
+}
+
+// ../extractor/src/anatomy.ts
+var MAX_DEPTH = 3;
+function defaultVariant(root) {
+  if (root.type !== "COMPONENT_SET" || !root.children?.length) return root;
+  const variants = root.children.filter((c) => c.type === "COMPONENT");
+  if (!variants.length) return root.children[0];
+  const declared = Object.entries(root.propertyDefinitions ?? {}).filter(([, d]) => d.type === "VARIANT" && typeof d.defaultValue === "string").map(([axis, d]) => [axis, d.defaultValue]);
+  if (declared.length) {
+    const match = variants.find((v) => {
+      const combo = parseVariantName(v.name);
+      return combo != null && declared.every(([axis, value]) => combo[axis] === value);
+    });
+    if (match) return match;
+  }
+  return variants[0];
+}
+function booleanPropertyKeys(root) {
+  return new Set(
+    Object.entries(root.propertyDefinitions ?? {}).filter(([, def]) => def.type === "BOOLEAN").map(([key]) => key)
+  );
+}
+function hiddenBoundTo(node, booleans) {
+  if (node.visible) return void 0;
+  if (node.visibleProperty === void 0 || !booleans.has(node.visibleProperty)) return void 0;
+  return cleanPropName(node.visibleProperty);
+}
+function isDocumentable(node, booleans) {
+  return node.visible || hiddenBoundTo(node, booleans) !== void 0;
+}
+function hiddenPartRules(root) {
+  const booleans = booleanPropertyKeys(root);
+  return {
+    prune: (node) => !isDocumentable(node, booleans),
+    shownBy: (node) => hiddenBoundTo(node, booleans)
+  };
+}
+function extractAnatomy(root) {
+  const parts = [];
+  const related = /* @__PURE__ */ new Set();
+  const isInSet = root.type === "COMPONENT_SET";
+  const def = defaultVariant(root);
+  const rootPath = isInSet ? "Container" : cleanPartName(def.name);
+  const booleans = booleanPropertyKeys(root);
+  let siblingSet = def.children ?? [];
+  let children = siblingSet.filter((c) => c.visible);
+  let parentPath = rootPath;
+  const skippedHidden = [];
+  while (children.length === 1 && (children[0].type === "FRAME" || children[0].type === "GROUP") && (children[0].children ?? []).filter((c) => c.visible).length > 0) {
+    for (const node of siblingSet) {
+      if (node !== children[0] && hiddenBoundTo(node, booleans) !== void 0) {
+        skippedHidden.push({ node, parentPath });
+      }
+    }
+    const names = siblingPartNames(siblingSet);
+    parentPath = joinPath(parentPath, names.get(children[0]));
+    siblingSet = children[0].children ?? [];
+    children = siblingSet.filter((c) => c.visible);
+  }
+  const namingOrder = [
+    ...children,
+    ...siblingSet.filter((c) => hiddenBoundTo(c, booleans) !== void 0),
+    ...skippedHidden.map((e) => e.node)
+  ];
+  const topNames = siblingPartNames(namingOrder);
+  const topLevel = [
+    ...siblingSet.filter((c) => isDocumentable(c, booleans)).map((node) => ({ node, parentPath })),
+    ...skippedHidden
+  ];
+  function pushPart(child, depth, childParentPath, name, inheritedShownBy) {
+    const shownBy = hiddenBoundTo(child, booleans) ?? inheritedShownBy;
+    const nested = child.type === "INSTANCE";
+    if (nested && child.mainComponent && shownBy === void 0) related.add(child.mainComponent.name);
+    const path = joinPath(childParentPath, name);
+    parts.push({
+      id: child.id,
+      name,
+      type: child.type,
+      nested,
+      depth,
+      path,
+      ...nested && child.mainComponent ? { component: child.mainComponent.name } : {},
+      ...child.text ? { text: child.text } : {},
+      ...shownBy !== void 0 ? { hiddenByDefault: true, shownBy } : {}
+    });
+    if (!nested && depth + 1 < MAX_DEPTH && child.children?.length) {
+      addParts(child.children, depth + 1, path, shownBy);
+    }
+  }
+  function addParts(nodes, depth, nodesParentPath, inheritedShownBy) {
+    const names = siblingPartNames(nodes);
+    for (const child of nodes) {
+      if (!isDocumentable(child, booleans)) continue;
+      pushPart(child, depth, nodesParentPath, names.get(child), inheritedShownBy);
+    }
+  }
+  for (const entry2 of topLevel) {
+    pushPart(entry2.node, 0, entry2.parentPath, topNames.get(entry2.node), void 0);
+  }
+  return { parts, related: [...related], componentId: def.id };
+}
+
+// ../extractor/src/effects.ts
+function extractNodeEffects(root) {
+  const out = [];
+  const def = defaultVariant(root);
+  walkParts(
+    def,
+    root.type === "COMPONENT_SET" ? "Container" : cleanPartName(def.name),
+    (n, part, path) => {
+      if (n.effects && n.effects.length > 0) out.push({ part, path, effects: n.effects });
+    }
+  );
+  return out;
+}
+
+// ../extractor/src/tokens.ts
+function variantAxisModel(root) {
+  const isInSet = root.type === "COMPONENT_SET";
+  const variants = isInSet ? (root.children ?? []).filter((c) => c.type === "COMPONENT") : [root];
+  if (!isInSet) return { variants, combos: variants.map(() => ({})) };
+  const parsed = variants.map((v) => parseVariantName(v.name));
+  const first = parsed[0];
+  const consistent = first != null && parsed.every(
+    (p) => p !== null && Object.keys(p).length === Object.keys(first).length && Object.keys(first).every((k) => k in p)
+  );
+  return {
+    variants,
+    combos: consistent ? parsed : variants.map((v) => ({ Variant: v.name }))
+  };
+}
+function formatConditions(conditions) {
+  const entries = Object.entries(conditions);
+  if (!entries.length) return "\u2014";
+  return entries.map(([axis, values]) => `${axis}=${values.join(" \xB7 ")}`).join(", ");
+}
+var SIMPLE_PROPERTY_MAP = {
+  fills: "fill",
+  strokes: "border",
+  cornerRadius: "border-radius",
+  itemSpacing: "gap",
+  fontSize: "font-size",
+  fontFamily: "font-family",
+  fontWeight: "font-weight",
+  fontStyle: "font-style",
+  lineHeight: "line-height",
+  letterSpacing: "letter-spacing",
+  strokeWeight: "border-width",
+  strokeTopWeight: "border-top-width",
+  strokeRightWeight: "border-right-width",
+  strokeBottomWeight: "border-bottom-width",
+  strokeLeftWeight: "border-left-width",
+  maxWidth: "max-width",
+  minWidth: "min-width",
+  maxHeight: "max-height",
+  minHeight: "min-height"
+};
+var RADIUS_PROPS = ["topLeftRadius", "topRightRadius", "bottomLeftRadius", "bottomRightRadius"];
+var RADIUS_INDIVIDUAL_MAP = {
+  topLeftRadius: "border-top-left-radius",
+  topRightRadius: "border-top-right-radius",
+  bottomLeftRadius: "border-bottom-left-radius",
+  bottomRightRadius: "border-bottom-right-radius"
+};
+var RADIUS_BINDINGS = /* @__PURE__ */ new Set([
+  "cornerRadius",
+  "topLeftRadius",
+  "topRightRadius",
+  "bottomLeftRadius",
+  "bottomRightRadius"
+]);
+var PADDING_RAW_PROPS = /* @__PURE__ */ new Set([
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+  "verticalPadding",
+  "horizontalPadding"
+]);
+var TYPOGRAPHY_SUBPROPS = /* @__PURE__ */ new Set(["fontSize", "fontFamily", "fontWeight", "fontStyle", "lineHeight", "letterSpacing"]);
+var simpleProperty = (raw) => SIMPLE_PROPERTY_MAP[raw] ?? raw;
+function paddingSides(top, right, bottom, left, key = String) {
+  const single = (xs) => xs.length === 1 ? xs[0] : null;
+  const sameKey = (a, b) => {
+    const x = single(a), y = single(b);
+    return x !== null && y !== null && key(x) === key(y);
+  };
+  const sides = [top, right, bottom, left];
+  const out = [];
+  if (sides.every((s) => single(s) !== null) && new Set(sides.map((s) => key(single(s)))).size === 1) {
+    out.push({ property: "padding", value: single(top) });
+    return out;
+  }
+  if (left.length && sameKey(left, right)) {
+    out.push({ property: "padding-x", value: single(left) });
+  } else {
+    for (const t of left) out.push({ property: "padding-left", value: t });
+    for (const t of right) out.push({ property: "padding-right", value: t });
+  }
+  if (top.length && sameKey(top, bottom)) {
+    out.push({ property: "padding-y", value: single(top) });
+  } else {
+    for (const t of top) out.push({ property: "padding-top", value: t });
+    for (const t of bottom) out.push({ property: "padding-bottom", value: t });
+  }
+  return out;
+}
+function normalizeBindings(raw) {
+  const byProp = /* @__PURE__ */ new Map();
+  for (const b of raw) {
+    const refs = byProp.get(b.property) ?? [];
+    if (!refs.some((r) => r.kind === b.kind && r.id === b.id)) refs.push(b);
+    byProp.set(b.property, refs);
+  }
+  const out = [];
+  const emit = (property, ref) => {
+    if (out.some((o) => o.property === property && o.kind === ref.kind && o.id === ref.id)) return;
+    out.push({ ...ref, property });
+  };
+  const radii = RADIUS_PROPS.filter((p) => byProp.has(p));
+  const radiusRefs = radii.flatMap((p) => byProp.get(p));
+  const distinctRadius = new Set(radiusRefs.map((r) => `${r.kind}|${r.id}`));
+  if (radii.length === RADIUS_PROPS.length && distinctRadius.size === 1) {
+    emit("border-radius", radiusRefs[0]);
+  } else {
+    for (const p of radii) for (const r of byProp.get(p)) emit(RADIUS_INDIVIDUAL_MAP[p], r);
+  }
+  const sideRefs = (...props) => props.flatMap((p) => byProp.get(p) ?? []);
+  for (const { property, value } of paddingSides(
+    sideRefs("paddingTop", "verticalPadding"),
+    sideRefs("paddingRight", "horizontalPadding"),
+    sideRefs("paddingBottom", "verticalPadding"),
+    sideRefs("paddingLeft", "horizontalPadding"),
+    (r) => `${r.kind}|${r.id}`
+  )) {
+    emit(property, value);
+  }
+  const hasTypography = byProp.has("typography");
+  for (const [prop, refs] of byProp) {
+    if (RADIUS_PROPS.includes(prop) || PADDING_RAW_PROPS.has(prop)) continue;
+    if (hasTypography && TYPOGRAPHY_SUBPROPS.has(prop)) continue;
+    const mapped = simpleProperty(prop);
+    for (const r of refs) emit(mapped, r);
+  }
+  return out;
+}
+var refKey = (r) => `${r.kind}|${r.id}`;
+var ABSENT_KEY = "absent";
+function extractTokens(root, model) {
+  const isInSet = root.type === "COMPONENT_SET";
+  const { variants, combos } = model ?? variantAxisModel(root);
+  if (!variants.length) return [];
+  const axisOrder = [];
+  const observedValues = /* @__PURE__ */ new Map();
+  for (const combo of combos) {
+    for (const [axis, value] of Object.entries(combo)) {
+      let vals = observedValues.get(axis);
+      if (!vals) {
+        axisOrder.push(axis);
+        observedValues.set(axis, vals = []);
+      }
+      if (!vals.includes(value)) vals.push(value);
+    }
+  }
+  const axisValues = /* @__PURE__ */ new Map();
+  for (const axis of axisOrder) {
+    const obs = observedValues.get(axis);
+    const declared = root.propertyDefinitions?.[axis]?.variantOptions;
+    axisValues.set(
+      axis,
+      declared ? [...declared.filter((v) => obs.includes(v)), ...obs.filter((v) => !declared.includes(v))] : obs
+    );
+  }
+  const gridKey = (path, property) => JSON.stringify([path, property]);
+  const cellsByPathProp = /* @__PURE__ */ new Map();
+  const pathOrder = [];
+  const propOrder = /* @__PURE__ */ new Map();
+  const partByPath = /* @__PURE__ */ new Map();
+  const shownByPath = /* @__PURE__ */ new Map();
+  const hidden = hiddenPartRules(root);
+  const refsByKey = /* @__PURE__ */ new Map();
+  variants.forEach((variant, idx) => {
+    const combo = combos[idx];
+    const variantRefs = /* @__PURE__ */ new Map();
+    const shownByNode = /* @__PURE__ */ new Map();
+    const markHidden = (n, inherited) => {
+      const own = hidden.shownBy(n) ?? inherited;
+      if (own !== void 0) shownByNode.set(n, own);
+      for (const child of n.children ?? []) markHidden(child, own);
+    };
+    for (const child of variant.children ?? []) markHidden(child, void 0);
+    walkParts(variant, isInSet ? "Container" : cleanPartName(variant.name), (n, part, path) => {
+      const shownBy = shownByNode.get(n);
+      if (shownBy !== void 0 && !shownByPath.has(path)) shownByPath.set(path, shownBy);
+      for (const ref of normalizeBindings(n.bindings ?? [])) {
+        const key = gridKey(path, ref.property);
+        partByPath.set(path, part);
+        const { property: _property, ...identity } = ref;
+        let inner = variantRefs.get(key);
+        if (!inner) variantRefs.set(key, inner = /* @__PURE__ */ new Map());
+        const rk = refKey(ref);
+        inner.set(rk, identity);
+        refsByKey.set(rk, identity);
+      }
+    }, hidden.prune);
+    for (const [key, inner] of variantRefs) {
+      let cells = cellsByPathProp.get(key);
+      if (!cells) {
+        cellsByPathProp.set(key, cells = []);
+        const [path, prop] = JSON.parse(key);
+        if (!propOrder.has(path)) {
+          pathOrder.push(path);
+          propOrder.set(path, []);
+        }
+        propOrder.get(path).push(prop);
+      }
+      cells.push({ combo, keys: [...inner.keys()].sort() });
+    }
+  });
+  for (const cells of cellsByPathProp.values()) {
+    const present = new Set(cells.map((c) => c.combo));
+    for (const combo of combos) {
+      if (!present.has(combo)) cells.push({ combo, keys: [ABSENT_KEY] });
+    }
+  }
+  const cellKey = (c) => JSON.stringify(c.keys);
+  const projKey = (combo, axes) => JSON.stringify(axes.map((a) => combo[a]));
+  const relevantAxes = (cells) => {
+    const relevant = [];
+    for (const axis of axisOrder) {
+      const present = new Set(cells.map((c) => c.combo[axis]));
+      if (present.size < axisValues.get(axis).length) {
+        relevant.push(axis);
+        continue;
+      }
+      const others = axisOrder.filter((a) => a !== axis);
+      const groups = /* @__PURE__ */ new Map();
+      for (const c of cells) {
+        const gk = projKey(c.combo, others);
+        const tk = cellKey(c);
+        const prev = groups.get(gk);
+        if (prev === void 0) groups.set(gk, tk);
+        else if (prev !== tk) {
+          relevant.push(axis);
+          break;
+        }
+      }
+    }
+    return relevant;
+  };
+  const hasConflict = (cells, axes) => {
+    const m = /* @__PURE__ */ new Map();
+    for (const c of cells) {
+      const k = projKey(c.combo, axes);
+      const tk = cellKey(c);
+      const prev = m.get(k);
+      if (prev === void 0) m.set(k, tk);
+      else if (prev !== tk) return true;
+    }
+    return false;
+  };
+  const buildRules = (cellsIn) => {
+    let cells = cellsIn;
+    let relevant = relevantAxes(cells);
+    for (const axis of axisOrder) {
+      if (!hasConflict(cells, relevant)) break;
+      if (!relevant.includes(axis)) relevant = axisOrder.filter((a) => relevant.includes(a) || a === axis);
+    }
+    if (hasConflict(cells, relevant)) {
+      relevant = [...axisOrder];
+      const byCombo = /* @__PURE__ */ new Map();
+      for (const c of cells) {
+        const k = projKey(c.combo, axisOrder);
+        if (!byCombo.has(k)) byCombo.set(k, c);
+      }
+      cells = [...byCombo.values()];
+    }
+    const groups = /* @__PURE__ */ new Map();
+    for (const c of cells) {
+      const k = projKey(c.combo, relevant);
+      let g = groups.get(k);
+      if (!g) groups.set(k, g = { combo: c.combo, keys: /* @__PURE__ */ new Set() });
+      c.keys.forEach((t) => g.keys.add(t));
+    }
+    let rules = [];
+    for (const g of groups.values()) {
+      for (const key of [...g.keys].sort()) {
+        rules.push({ key, values: new Map(relevant.map((a) => [a, /* @__PURE__ */ new Set([g.combo[a]])])) });
+      }
+    }
+    const conditionKey = (r, excludeAxis) => JSON.stringify(axisOrder.filter((a) => a !== excludeAxis).map((a) => r.values.has(a) ? [...r.values.get(a)].sort() : null));
+    for (const axis of relevant) {
+      const merged = /* @__PURE__ */ new Map();
+      for (const r of rules) {
+        const k = JSON.stringify([r.key, conditionKey(r, axis)]);
+        const prev = merged.get(k);
+        if (prev && prev.values.has(axis) && r.values.has(axis)) {
+          r.values.get(axis).forEach((v) => prev.values.get(axis).add(v));
+        } else if (!merged.has(k)) {
+          merged.set(k, r);
+        }
+      }
+      rules = [...merged.values()];
+    }
+    for (const r of rules) {
+      for (const axis of [...r.values.keys()]) {
+        const vals = r.values.get(axis);
+        const observed = /* @__PURE__ */ new Set();
+        for (const combo of combos) {
+          const matchesOthers = [...r.values.entries()].every(
+            ([a, vs]) => a === axis || vs.has(combo[a])
+          );
+          if (matchesOthers) observed.add(combo[axis]);
+        }
+        if ([...observed].every((v) => vals.has(v))) r.values.delete(axis);
+      }
+    }
+    const seen = /* @__PURE__ */ new Map();
+    for (const r of rules) {
+      const k = JSON.stringify([r.key, conditionKey(r, null)]);
+      if (!seen.has(k)) seen.set(k, r);
+    }
+    rules = [...seen.values()];
+    rules = rules.filter(
+      (r) => !rules.some(
+        (other) => other !== r && other.key === r.key && other.values.size < r.values.size && [...other.values.entries()].every(
+          ([a, vs]) => r.values.has(a) && [...r.values.get(a)].every((v) => vs.has(v))
+        )
+      )
+    );
+    return rules;
+  };
+  const defaultCombo = combos[0];
+  const toTokenRule = (path, property, r) => {
+    const conditions = {};
+    for (const axis of axisOrder) {
+      const vs = r.values.get(axis);
+      if (!vs) continue;
+      conditions[axis] = axisValues.get(axis).filter((v) => vs.has(v));
+    }
+    const shownBy = shownByPath.get(path);
+    return {
+      part: partByPath.get(path),
+      path,
+      property,
+      conditions,
+      ...refsByKey.get(r.key),
+      // Absent, never undefined, on a rule that applies unconditionally: the
+      // same contract AnatomyPart.shownBy keeps, so `'shownBy' in rule` is a
+      // reliable test and the key never appears in output it does not apply to.
+      ...shownBy !== void 0 ? { shownBy } : {}
+    };
+  };
+  const ruleSortKey = (r) => {
+    const matchesDefault = [...r.values.entries()].every(([a, vs]) => vs.has(defaultCombo[a]));
+    const axisBits = axisOrder.map((a, i) => {
+      const vs = r.values.get(a);
+      if (!vs) return "";
+      const indices = axisValues.get(a).map((v, vi) => vs.has(v) ? String(vi).padStart(3, "0") : "").filter(Boolean).join(".");
+      return `${i}:${indices}`;
+    }).filter(Boolean).join("|");
+    return [
+      matchesDefault ? "0" : "1",
+      String(r.values.size).padStart(3, "0"),
+      axisBits,
+      // An absent rule has no reference and sorts first, exactly as the old
+      // control-character sentinel did. It is dropped below either way.
+      refsByKey.get(r.key)?.name ?? "",
+      r.key
+    ];
+  };
+  const compareKeys = (a, b) => {
+    for (let i = 0; i < a.length; i++) {
+      if (a[i] < b[i]) return -1;
+      if (a[i] > b[i]) return 1;
+    }
+    return 0;
+  };
+  const out = [];
+  for (const path of pathOrder) {
+    for (const prop of propOrder.get(path)) {
+      const cells = cellsByPathProp.get(gridKey(path, prop));
+      const rules = buildRules(cells);
+      rules.sort((a, b) => compareKeys(ruleSortKey(a), ruleSortKey(b)));
+      for (const r of rules) {
+        if (r.key === ABSENT_KEY) continue;
+        out.push(toTokenRule(path, prop, r));
+      }
+    }
+  }
+  return out;
+}
+var TYPOGRAPHY_PROPS = ["typography", "fontSize", "fontFamily", "fontStyle", "fontWeight", "lineHeight", "letterSpacing"];
+var PADDING_PROPS = ["paddingTop", "paddingRight", "paddingBottom", "paddingLeft", "verticalPadding", "horizontalPadding"];
+function extractGaps(root) {
+  const out = [];
+  const seenGaps = /* @__PURE__ */ new Set();
+  const pushGap = (part, path, property, issue, value) => {
+    const key = `${path} ${property} ${issue}`;
+    if (seenGaps.has(key)) return;
+    seenGaps.add(key);
+    out.push({ part, path, property, issue, ...value !== void 0 ? { value } : {} });
+  };
+  const isInSet = root.type === "COMPONENT_SET";
+  const def = defaultVariant(root);
+  walkParts(def, isInSet ? "Container" : cleanPartName(def.name), (n, part, path) => {
+    const bound = new Set((n.bindings ?? []).map((b) => b.property));
+    if (n.hasUnboundPaint) {
+      pushGap(part, path, simpleProperty("fills"), "hardcoded-color", n.unboundFill);
+    }
+    if (n.hasUnboundStroke) {
+      pushGap(part, path, simpleProperty("strokes"), "hardcoded-color", n.unboundStroke);
+    }
+    if (n.hasUnboundGradient) {
+      pushGap(part, path, simpleProperty("fills"), "missing-token-binding");
+    }
+    if (n.hasUnboundEffect) {
+      pushGap(part, path, simpleProperty("effects"), "missing-token-binding");
+    }
+    if (n.opacity !== void 0 && n.opacity !== 1 && !bound.has("opacity")) {
+      pushGap(part, path, simpleProperty("opacity"), "hardcoded-value", Math.round(n.opacity * 1e4) / 1e4);
+    }
+    if (n.type === "TEXT" && !TYPOGRAPHY_PROPS.some((p) => bound.has(p))) {
+      pushGap(part, path, simpleProperty("typography"), "missing-token-binding");
+    }
+    const l = n.layout;
+    if (!l) return;
+    if (l.itemSpacing !== void 0 && !bound.has("itemSpacing")) {
+      pushGap(part, path, simpleProperty("itemSpacing"), "hardcoded-value", l.itemSpacing);
+    }
+    if (l.cornerRadius !== void 0 && ![...RADIUS_BINDINGS].some((p) => bound.has(p))) {
+      pushGap(part, path, simpleProperty("cornerRadius"), "hardcoded-value", l.cornerRadius);
+    }
+    if (!PADDING_PROPS.some((p) => bound.has(p))) {
+      const side = (v) => v !== void 0 ? [v] : [];
+      for (const { property, value } of paddingSides(
+        side(l.paddingTop),
+        side(l.paddingRight),
+        side(l.paddingBottom),
+        side(l.paddingLeft)
+      )) {
+        pushGap(part, path, property, "hardcoded-value", value);
+      }
+    }
+  });
+  return out;
+}
+
+// ../extractor/src/pivot.ts
+function isModifierAxis(axis) {
+  if (axis.values.length !== 2) return false;
+  const lower = axis.values.map((v) => v.toLowerCase());
+  return lower.includes("true") && lower.includes("false");
+}
+function isStateAxisName(prop) {
+  const n = prop.trim().toLowerCase();
+  return n === "state" || n === "states";
+}
+
 // ../extractor/src/statesMatrix.ts
 var STATE_ORDER = [
   "default",
@@ -588,6 +1191,200 @@ var STATE_ORDER = [
   "visited"
 ];
 var STATE_VOCAB = new Set(STATE_ORDER);
+var WHITESPACE2 = /\s/;
+function stateBaseName(v) {
+  const lowered = v.trim().toLowerCase();
+  let end = lowered.length;
+  while (end > 0 && WHITESPACE2.test(lowered[end - 1])) end--;
+  if (end === 0 || lowered[end - 1] !== ")") return lowered.trim();
+  let open = -1;
+  for (let i = end - 2; i >= 0; i--) {
+    const ch = lowered[i];
+    if (ch === ")") break;
+    if (ch === "(") open = i;
+  }
+  if (open === -1) return lowered.trim();
+  let cut = open;
+  while (cut > 0 && WHITESPACE2.test(lowered[cut - 1])) cut--;
+  return lowered.slice(0, cut).trim();
+}
+function stateRank(v) {
+  const i = STATE_ORDER.indexOf(stateBaseName(v));
+  return i === -1 ? STATE_ORDER.length : i;
+}
+function orderStates(values) {
+  return values.map((v, i) => ({ v, i })).sort((a, b) => stateRank(a.v) - stateRank(b.v) || a.i - b.i).map((x) => x.v);
+}
+function isStateLike(axis) {
+  const n = axis.prop.trim().toLowerCase();
+  if (isStateAxisName(axis.prop) || n === "status") return true;
+  const hits = axis.values.filter((v) => STATE_VOCAB.has(v.trim().toLowerCase())).length;
+  return hits >= 2;
+}
+function isStateVocabName(prop) {
+  const n = prop.trim().toLowerCase();
+  return isStateAxisName(prop) || n === "status" || STATE_VOCAB.has(stateBaseName(prop));
+}
+function trueValueOf(axis) {
+  return axis.values.find((v) => v.toLowerCase() === "true") ?? axis.values[axis.values.length - 1];
+}
+function detectStateMatrix(variants) {
+  const stateAxis = variants.find(isStateLike) ?? null;
+  if (stateAxis) {
+    const rowAxis2 = variants.find((v) => v.prop !== stateAxis.prop && !isModifierAxis(v) && !isStateLike(v)) ?? null;
+    const columns2 = orderStates(stateAxis.values).map((v) => ({
+      label: v,
+      override: { [stateAxis.prop]: v }
+    }));
+    return { encoding: "enum", columns: columns2, rowAxis: rowAxis2?.prop ?? null, axis: stateAxis.prop };
+  }
+  const flags = variants.filter((v) => isModifierAxis(v) && isStateVocabName(v.prop));
+  if (flags.length === 0) return null;
+  const orderedFlagProps = orderStates(flags.map((f) => f.prop));
+  const orderedFlags = orderedFlagProps.map((p) => flags.find((f) => f.prop === p));
+  const columns = [
+    { label: "Default", override: {} },
+    ...orderedFlags.map((f) => ({ label: f.prop, override: { [f.prop]: trueValueOf(f) } }))
+  ];
+  const rowAxis = variants.find((v) => !isModifierAxis(v) && !isStateLike(v)) ?? null;
+  return { encoding: "flags", columns, rowAxis: rowAxis?.prop ?? null, axis: null };
+}
+
+// ../extractor/src/props.ts
+var KIND_MAP = {
+  VARIANT: "variant",
+  BOOLEAN: "boolean",
+  TEXT: "text",
+  INSTANCE_SWAP: "instanceSwap"
+};
+function extractProps(root) {
+  return Object.entries(root.propertyDefinitions ?? {}).map(([raw, def]) => ({
+    name: cleanPropName(raw),
+    kind: KIND_MAP[def.type],
+    ...def.variantOptions !== void 0 ? { options: def.variantOptions } : {},
+    default: def.defaultValue
+  }));
+}
+function extractVariants(root) {
+  return extractProps(root).filter((p) => p.kind === "variant").map((p) => ({ prop: p.name, values: p.options ?? [] }));
+}
+function extractStates(root) {
+  const info = detectStateMatrix(extractVariants(root));
+  if (!info) return ["Default"];
+  const labels = info.columns.map((c) => c.label);
+  return labels.length ? labels : ["Default"];
+}
+
+// ../extractor/src/layout.ts
+function valuesOf(l) {
+  return {
+    ...l.cornerRadius !== void 0 ? { radius: l.cornerRadius } : {},
+    ...l.itemSpacing !== void 0 ? { gap: l.itemSpacing } : {}
+  };
+}
+function fmt(l) {
+  const bits = [];
+  if (l.mode) bits.push(l.mode.toLowerCase());
+  const pads = [l.paddingTop ?? 0, l.paddingRight ?? 0, l.paddingBottom ?? 0, l.paddingLeft ?? 0];
+  if (pads.some((p) => p > 0)) bits.push(`padding ${pads.join("/")}`);
+  if (l.itemSpacing !== void 0) bits.push(`gap ${l.itemSpacing}`);
+  if (l.cornerRadius !== void 0) bits.push(`radius ${l.cornerRadius}`);
+  return bits.join(", ");
+}
+function extractLayout(root) {
+  const out = [];
+  const isInSet = root.type === "COMPONENT_SET";
+  walkParts(defaultVariant(root), isInSet ? "Container" : cleanPartName(root.name), (n, _part, path) => {
+    if (!n.layout) return;
+    const summary = fmt(n.layout);
+    if (summary) out.push({ part: n.name, path, summary, values: valuesOf(n.layout) });
+  }, false);
+  return out;
+}
+
+// ../extractor/src/rawValues.ts
+var PADDING_BINDINGS = /* @__PURE__ */ new Set([
+  "paddingTop",
+  "paddingRight",
+  "paddingBottom",
+  "paddingLeft",
+  "verticalPadding",
+  "horizontalPadding"
+]);
+function extractRawValues(root) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (part, property, value) => {
+    const k = JSON.stringify([part, property]);
+    if (seen.has(k)) return;
+    seen.add(k);
+    out.push({ part, property, value });
+  };
+  const def = defaultVariant(root);
+  walkParts(def, root.type === "COMPONENT_SET" ? "Container" : cleanPartName(def.name), (n, part) => {
+    const bound = new Set((n.bindings ?? []).map((b) => b.property));
+    if (n.unboundFill) push(part, "fill", n.unboundFill);
+    const l = n.layout;
+    if (l) {
+      const t = l.paddingTop ?? 0, r = l.paddingRight ?? 0, b = l.paddingBottom ?? 0, lf = l.paddingLeft ?? 0;
+      const hasPad = t > 0 || r > 0 || b > 0 || lf > 0;
+      if (hasPad && ![...PADDING_BINDINGS].some((p) => bound.has(p))) {
+        if (t === r && r === b && b === lf) push(part, "padding", String(t));
+        else {
+          if (lf === r && lf > 0) push(part, "padding-x", String(lf));
+          else {
+            if (lf > 0) push(part, "padding-left", String(lf));
+            if (r > 0) push(part, "padding-right", String(r));
+          }
+          if (t === b && t > 0) push(part, "padding-y", String(t));
+          else {
+            if (t > 0) push(part, "padding-top", String(t));
+            if (b > 0) push(part, "padding-bottom", String(b));
+          }
+        }
+      }
+      if (l.itemSpacing !== void 0 && l.itemSpacing > 0 && !bound.has("itemSpacing")) {
+        push(part, "gap", String(l.itemSpacing));
+      }
+      if (l.cornerRadius !== void 0 && l.cornerRadius > 0 && ![...RADIUS_BINDINGS].some((p) => bound.has(p))) {
+        push(part, "border-radius", String(l.cornerRadius));
+      }
+    }
+  }, true);
+  return out;
+}
+
+// ../extractor/src/extract.ts
+function toVariantInstances(model) {
+  return model.variants.map((v, i) => ({ nodeId: v.id, name: v.name, values: model.combos[i] }));
+}
+function extract(root, meta) {
+  const { parts, related, componentId } = extractAnatomy(root);
+  const model = variantAxisModel(root);
+  return {
+    name: root.name,
+    figmaKey: root.key ?? "",
+    figmaFile: meta.figmaFile,
+    // Spread in only when a name was actually supplied, so an absent name is
+    // an absent key rather than a key holding undefined.
+    ...meta.figmaFileName ? { figmaFileName: meta.figmaFileName } : {},
+    figmaNode: root.id,
+    description: root.description ?? "",
+    documentationLinks: root.documentationLinks ?? [],
+    anatomy: parts,
+    anatomyComponentId: componentId,
+    props: extractProps(root),
+    variants: extractVariants(root),
+    variantInstances: toVariantInstances(model),
+    states: extractStates(root),
+    tokens: extractTokens(root, model),
+    related,
+    gaps: extractGaps(root),
+    layout: extractLayout(root),
+    rawValues: extractRawValues(root),
+    nodeEffects: extractNodeEffects(root)
+  };
+}
 
 // ../extractor/src/v5/precision.ts
 var SIGNIFICANT_DIGITS = 7;
@@ -643,10 +1440,10 @@ var DEFAULT_SEVERITY = {
   EXPORT_SCOPED: "info"
 };
 var compareCodeUnits = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-function diagnostic(code2, fields) {
+function diagnostic(code3, fields) {
   return {
-    code: code2,
-    severity: DEFAULT_SEVERITY[code2],
+    code: code3,
+    severity: DEFAULT_SEVERITY[code3],
     entity_id: fields.entity_id,
     ...fields.mode_id !== void 0 ? { mode_id: fields.mode_id } : {},
     message: fields.message,
@@ -657,8 +1454,16 @@ function diagnostic(code2, fields) {
 // ../extractor/src/hash.ts
 var import_js_sha256 = __toESM(require_sha256(), 1);
 
+// ../extractor/src/displayNames.ts
+function displayComponentName(raw) {
+  const name = raw.replace(/^[._]+/, "").trim();
+  if (!name) return "";
+  if (/[A-Z]/.test(name)) return name;
+  return name.charAt(0).toUpperCase() + name.slice(1);
+}
+
 // ../extractor/src/prose/prompt.ts
-var PROSE_SYSTEM_PROMPT = [
+var LEGACY_PROSE_SYSTEM_PROMPT = [
   "You write component guideline prose for a design-system specification tool.",
   "Your output fills three spec sections: Definition, Accessibility, and Do's & Don'ts,",
   "in the voice of best-in-class design systems (Atlassian, Material, Polaris, Carbon).",
@@ -707,7 +1512,7 @@ var PROSE_SYSTEM_PROMPT = [
   "Return only the JSON object requested in the user message. No preamble and no prose outside the",
   "JSON."
 ].join("\n");
-var FEW_SHOT_PROMPT = [
+var LEGACY_FEW_SHOT_PROMPT = [
   "Component: Button",
   "",
   "Anatomy: Container, Label, Leading icon (component)",
@@ -719,7 +1524,7 @@ var FEW_SHOT_PROMPT = [
   "",
   `Return ONLY a JSON object with keys: definition (one sentence defining what it is, then a short benefit-led overview: where it is used, the value it gives people, its role, and a guiding principle; no style names and no when-to-use guide), variantsSummary (1-2 sentences on what varies across the options, then a bulleted "when to use which type" guide with bold type names when it has several types), anatomySummary (1-2 sentences orienting the reader to the component structure and the role of its key parts), anatomyParts (array of { name, description } where each name EXACTLY matches one of the Anatomy part names above and description is one concise sentence naming that part's role), accessibility (a bulleted list; give each bullet a short bold lead-in then the guidance; include one bullet flagging what cannot be known from the design file), interactions (Markdown under "### Mouse", "### Keyboard", "### Other" subheadings, 2-3 bullets each, anchored to the States above), designConsiderations (3-4 designer-facing bullets on contrast, state distinguishability, and missing-state flags), contentConsiderations (3-4 bullets on label writing, truncation, and internationalization), dos (string[], 3 to 5 items, each starting with a bold rule summary then the reason), donts (string[], 3 to 5 items, same shape). Use Markdown (bold lead-ins, lists, at most "###" subheadings); never "#" or "##" headings. Do not use em dashes. Do not include any prose outside the JSON.`
 ].join("\n");
-var FEW_SHOT_RESPONSE = {
+var LEGACY_FEW_SHOT_RESPONSE = {
   definition: "A Button triggers an action when activated. Used across products to perform common actions, it gives people a familiar, accessible way to engage with the interface and keeps frequent tasks fast and predictable. It is essential for guiding people through workflows and performing the key actions on a screen. Create buttons that are clear, easy to identify, and accessible.",
   variantsSummary: [
     "Style sets the visual weight and states cover the interactive feedback; all styles share the same anatomy.",
@@ -773,6 +1578,315 @@ var FEW_SHOT_RESPONSE = {
     "**Don't disable a button without explaining why.** A disabled control gives no reason and drops out of the tab order, so use inline validation instead."
   ]
 };
+var LEGACY_FOUNDATION_SYSTEM_PROMPT = [
+  "You write short descriptions of design-token groups for a design-system reference.",
+  "Each description sits under a group heading in a generated documentation frame.",
+  "",
+  "You are given the token names in the group and their resolved values. That is ALL you know.",
+  "Describe what the group is for, as its names and values actually show.",
+  "",
+  "Never invent: no component names the tokens do not mention, no counts, no accessibility",
+  "claims, no history, no rules the names do not support. If the names are too generic to",
+  "support a purpose, describe the shape of the set plainly instead and stop. A vague but true",
+  "sentence is correct; a specific but invented one is a defect.",
+  "",
+  "Voice:",
+  "- One or two sentences. Under 220 characters. No heading, no list, no markdown.",
+  "- Plain and factual, the tone of a peer explaining their own file.",
+  '- Say what the group is for and when to reach for it. Lead with the purpose, not "This group".',
+  '- Write for people, not "the user".',
+  "- Never use em dashes or en dashes. Use a period, comma, colon, or parentheses.",
+  '- Do not restate the heading as a sentence ("Surface colours are colours for surfaces").',
+  "",
+  "Return ONLY a JSON object mapping each group key to its description string.",
+  "No prose outside the JSON, no code fence."
+].join("\n");
+
+// ../extractor/src/prose/v2.ts
+var PROSE_V2_KEYS = [
+  "overview",
+  "whenToUse",
+  "whenNotToUse",
+  "variantsIntro",
+  "variantsGuide",
+  "anatomySummary",
+  "anatomyParts",
+  "properties",
+  "states",
+  "keyboard",
+  "pointer",
+  "semantics",
+  "content",
+  "guidelines"
+];
+var KEYBOARD_KEYS = [
+  "Tab",
+  "Shift+Tab",
+  "Enter",
+  "Space",
+  "Escape",
+  "Arrow Up",
+  "Arrow Down",
+  "Arrow Left",
+  "Arrow Right",
+  "Home",
+  "End",
+  "Page Up",
+  "Page Down",
+  "Delete",
+  "Backspace"
+];
+
+// ../extractor/src/prose/promptV2.ts
+var PROMPT_RETURN_ANCHOR = "\nReturn ONLY a JSON object with these keys: ";
+function partKind(part) {
+  if (part.nested) return `nested component ${part.component ?? "component"}`;
+  switch (part.type) {
+    case "TEXT":
+      return "text";
+    case "VECTOR":
+    case "BOOLEAN_OPERATION":
+    case "STAR":
+    case "POLYGON":
+    case "LINE":
+      return "vector";
+    case "RECTANGLE":
+    case "ELLIPSE":
+      return "shape";
+    case "FRAME":
+    case "GROUP":
+    case "SECTION":
+    case "COMPONENT":
+    case "INSTANCE":
+      return "container";
+    default:
+      return part.type.toLowerCase();
+  }
+}
+var PROSE_KEY_INSTRUCTIONS = {
+  overview: "overview ({ lede, body }: lede is one sentence saying what the component is and what a person does with it; body is at most one short paragraph, one or two sentences, on where it appears and what it holds; describe, never explain or justify; no option names)",
+  whenToUse: "whenToUse (string[], 2 to 4 concrete situations where this component is the right choice; each names a task or context, never a rule about how to use it)",
+  whenNotToUse: 'whenNotToUse (string[], 2 to 3 situations where another control fits better, each phrased "For <situation>, use <alternative> instead" with the reason after a semicolon; never start with "Do not"; name another component only if it is listed under Related above)',
+  variantsIntro: "variantsIntro (one or two sentences on what the option axes change; never mention states)",
+  variantsGuide: "variantsGuide ({ name, guidance }[] with one entry per option value listed under Options above, name spelled exactly as listed, guidance one sentence on when to choose it; omit state values)",
+  anatomySummary: "anatomySummary (one or two sentences on how the parts fit together)",
+  anatomyParts: "anatomyParts ({ name, role }[] with name exactly as listed under Anatomy above and role one sentence on what the part does, not how it looks; skip a part you cannot describe without guessing)",
+  properties: "properties ({ name, description }[] with name exactly as listed under Options, State axis or Properties above and description one sentence on what the property controls and when to change it)",
+  states: "states ({ name, whenItApplies }[] with name exactly as listed under States above and whenItApplies one sentence on when the state applies)",
+  // The vocabulary is read from KEYBOARD_KEYS rather than written out again:
+  // `validateProseV2` drops a row whose key is not in that list, so a literal
+  // here could ask for a key the validator then throws away, or leave out one
+  // it would have accepted.
+  keyboard: `keyboard ({ keys: string[], action }[] with each key one of ${KEYBOARD_KEYS.join(", ")}, and action one sentence; include only bindings this component really has, and leave the key out for a non-interactive component)`,
+  pointer: "pointer (string[], 2 to 3 sentences on mouse and touch behaviour, including target size)",
+  semantics: "semantics (string[], 3 to 4 sentences on roles, accessible names, and announcements, plus one on what the design file cannot encode)",
+  content: "content (string[], 3 to 4 sentences on writing the text parts listed under Anatomy, on truncation, and on translation)",
+  guidelines: "guidelines ({ do: { rule, reason }, dont: { rule, reason } }[], 3 pairs about using this component once chosen; each pair covers one topic drawn from its options, states or text parts, the dont mirrors the do, and no pair repeats a When to use or When not to use bullet; each rule one sentence, each reason one sentence)"
+};
+function axisDefault(spec, axis) {
+  const prop = spec.props.find((p) => p.name === axis && p.kind === "variant");
+  return typeof prop?.default === "string" ? prop.default : void 0;
+}
+var WHITESPACE3 = /\s/;
+function collapseLineBreaks(text) {
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    if (!WHITESPACE3.test(text[i])) {
+      out += text[i];
+      i += 1;
+      continue;
+    }
+    let j = i;
+    let hasBreak = false;
+    while (j < text.length && WHITESPACE3.test(text[j])) {
+      if (text[j] === "\n") hasBreak = true;
+      j += 1;
+    }
+    out += hasBreak ? " " : text.slice(i, j);
+    i = j;
+  }
+  return out;
+}
+function buildProsePrompt(spec, requested) {
+  const lines = [];
+  const display = displayComponentName(spec.name);
+  lines.push(display === spec.name ? `Component: ${spec.name}` : `Component: ${display} (layer name: ${spec.name})`);
+  const description = spec.description.trim();
+  if (description) {
+    lines.push("");
+    lines.push("Designer's description (authoritative; build on it, never contradict or restate it):");
+    lines.push(`  ${collapseLineBreaks(description)}`);
+  }
+  if (spec.anatomy.length) {
+    lines.push("");
+    lines.push("Anatomy (depth-first; indent marks nesting):");
+    for (const part of spec.anatomy) {
+      const indent = "  ".repeat(part.depth + 1);
+      const shown = part.shownBy ? `; shown by ${part.shownBy}` : "";
+      lines.push(`${indent}${part.name}: ${partKind(part)}${shown}`);
+    }
+  }
+  const matrix = detectStateMatrix(spec.variants);
+  const stateAxis = matrix?.axis ?? null;
+  const optionAxes = spec.variants.filter((v) => v.prop !== stateAxis);
+  if (optionAxes.length) {
+    lines.push("");
+    lines.push("Options:");
+    for (const v of optionAxes) {
+      const def = axisDefault(spec, v.prop);
+      lines.push(`  ${v.prop}: ${v.values.join(" \xB7 ")}${def ? ` (default ${def})` : ""}`);
+    }
+  }
+  if (stateAxis) {
+    const axis = spec.variants.find((v) => v.prop === stateAxis);
+    if (axis) {
+      lines.push("");
+      lines.push("State axis:");
+      lines.push(`  ${axis.prop}: ${axis.values.join(" \xB7 ")}`);
+    }
+  }
+  const otherProps = spec.props.filter((p) => p.kind !== "variant");
+  if (otherProps.length) {
+    lines.push("");
+    lines.push("Properties:");
+    for (const p of otherProps) {
+      const def = p.default !== void 0 ? ` (default: ${p.default})` : "";
+      lines.push(`  ${p.name} [${p.kind}]${def}`);
+    }
+  }
+  if (spec.states.length) {
+    lines.push("");
+    lines.push(`States: ${spec.states.join(", ")}`);
+  }
+  if (spec.tokens.length) {
+    lines.push("");
+    lines.push("Design tokens:");
+    for (const t of spec.tokens) {
+      const condition = formatConditions(t.conditions);
+      const qualifier = condition === "\u2014" ? "" : ` [${condition}]`;
+      lines.push(`  ${t.part}.${t.property}${qualifier} \u2192 ${t.name}`);
+    }
+    if (spec.tokens.some((t) => Object.keys(t.conditions).length)) {
+      lines.push("  Note: a bracketed condition like [State=Hover] means the token applies only to variants matching those axis values; unbracketed lines apply to all variants.");
+    }
+  }
+  if (spec.layout.length) {
+    lines.push("");
+    lines.push("Layout (default variant):");
+    for (const l of spec.layout) lines.push(`  ${l.part}: ${l.summary}`);
+  }
+  if (spec.related.length) {
+    lines.push("");
+    lines.push(`Related: ${spec.related.join(", ")}`);
+  }
+  const keys = requested ? PROSE_V2_KEYS.filter((k) => requested.has(k)) : [...PROSE_V2_KEYS];
+  lines.push("");
+  lines.push(
+    PROMPT_RETURN_ANCHOR.trimStart() + keys.map((k) => PROSE_KEY_INSTRUCTIONS[k]).join("; ") + ". Leave out any key you cannot fill honestly. Markdown only as **bold** or `code` inside a sentence; no headings. No em dashes; keep sentences short. Return only the JSON object."
+  );
+  return lines.join("\n");
+}
+var BANNED_PHRASES = [
+  "familiar",
+  "essential",
+  "intuitive",
+  "seamless",
+  "engage with the interface",
+  "clear, easy to identify",
+  "gives people a way to",
+  "plays a key role"
+];
+var PROSE_SYSTEM_PROMPT = [
+  "You write component documentation for a design system, in the voice of a senior designer explaining their own component to a colleague.",
+  "",
+  "Voice:",
+  "- Second person, verb first, one idea per sentence. Every rule carries its reason.",
+  "- Anchor guidance in concrete situations: forms, dialogs, toolbars, lists, filters.",
+  '- Write for people, not "the user".',
+  '- Describe, do not argue. No sentence explains why the component reads or feels a certain way, and nothing is "rather than" something else.',
+  "",
+  "Facts:",
+  "- Name only what the prompt lists: this component's parts, properties, option values, states, and related components. Never invent an option, a part, a state, or a component.",
+  "- The designer's description, when given, is authoritative. Build on it. Never contradict it and never restate it.",
+  "- States are not variants. The variants guide covers option axes only; states go in the states list.",
+  "- Say each fact once. When to use and When not to use are about choosing this component over another; the guidelines are about using it well once chosen.",
+  `- Keyboard rows use only these keys: ${KEYBOARD_KEYS.join(", ")}.`,
+  "",
+  "Words to avoid:",
+  `- Do not write ${BANNED_PHRASES.map((p) => `"${p}"`).join(", ")}.`,
+  "- Do not restate a heading as a sentence.",
+  "",
+  "Format:",
+  "- No em dashes and no spaced en dashes. Use a comma, a colon, or a full stop.",
+  "- No headings inside strings. Markdown only as **bold** or `code` inside a sentence.",
+  "- Return only the JSON object the message asks for, with only the keys it lists. Leave out a key you cannot fill honestly."
+].join("\n");
+function exemplarVariant(state) {
+  const bind = (property, name) => ({
+    property,
+    id: `VariableID:${name}`,
+    name,
+    kind: "variable",
+    remote: false,
+    collectionId: "VariableCollectionId:exemplar"
+  });
+  const border = state === "Focused" ? "color/border/focus" : state === "Error" ? "color/border/error" : "color/field/border";
+  return {
+    id: `x:${state}`,
+    name: `Size=Medium, Style=Filled, State=${state}`,
+    type: "COMPONENT",
+    visible: true,
+    layout: { mode: "VERTICAL", itemSpacing: 4 },
+    children: [
+      { id: `x:${state}:label`, name: "Label", type: "TEXT", visible: true, bindings: [bind("fills", "color/text/secondary")] },
+      {
+        id: `x:${state}:input`,
+        name: "Input",
+        type: "FRAME",
+        visible: true,
+        layout: { mode: "HORIZONTAL", paddingLeft: 12, paddingRight: 12, itemSpacing: 8 },
+        bindings: [bind("fills", "color/field/bg"), bind("strokes", border)],
+        children: [
+          {
+            id: `x:${state}:icon`,
+            name: "Leading icon",
+            type: "INSTANCE",
+            visible: false,
+            visibleProperty: "Show leading icon",
+            mainComponent: { name: "Icon", key: "exemplar-icon" }
+          },
+          { id: `x:${state}:placeholder`, name: "Placeholder", type: "TEXT", visible: true, bindings: [bind("fills", "color/text/placeholder")] }
+        ]
+      },
+      { id: `x:${state}:helper`, name: "Helper text", type: "TEXT", visible: true, bindings: [bind("fills", "color/text/secondary")] }
+    ]
+  };
+}
+function exemplarNode() {
+  return {
+    id: "x:0",
+    name: "Text field",
+    type: "COMPONENT_SET",
+    visible: true,
+    key: "exemplar-text-field",
+    description: "A single-line field where people type short, free-form text.",
+    propertyDefinitions: {
+      Size: { type: "VARIANT", defaultValue: "Medium", variantOptions: ["Small", "Medium"] },
+      Style: { type: "VARIANT", defaultValue: "Filled", variantOptions: ["Filled", "Outlined"] },
+      State: { type: "VARIANT", defaultValue: "Enabled", variantOptions: ["Enabled", "Hover", "Focused", "Error", "Disabled"] },
+      "Show leading icon": { type: "BOOLEAN", defaultValue: false },
+      "Show helper text": { type: "BOOLEAN", defaultValue: true },
+      Label: { type: "TEXT", defaultValue: "Label" },
+      Placeholder: { type: "TEXT", defaultValue: "Placeholder" }
+    },
+    children: ["Enabled", "Hover", "Focused", "Error", "Disabled"].map(exemplarVariant)
+  };
+}
+function exemplarSpec() {
+  return extract(exemplarNode(), { figmaFile: "exemplar" });
+}
+var EXEMPLAR_PROMPT = buildProsePrompt(exemplarSpec());
 
 // ../extractor/src/prose/foundationPrompt.ts
 var FOUNDATION_SYSTEM_PROMPT = [
@@ -795,10 +1909,160 @@ var FOUNDATION_SYSTEM_PROMPT = [
   "- Never use em dashes or en dashes. Use a period, comma, colon, or parentheses.",
   '- Do not restate the heading as a sentence ("Surface colours are colours for surfaces").',
   "",
-  "Return ONLY a JSON object mapping each group key to its description string.",
+  'Each "<collection key>|overview" entry describes that collection in one paragraph: what it holds,',
+  "how its modes differ, and which collections it draws from, exactly as the names, modes and alias",
+  "counts show. Under 400 characters, no markdown, no invented usage. Leave it out if the names",
+  "support nothing.",
+  "",
+  "Return ONLY a JSON object: each group key mapped to its description, and each",
+  "collection overview key mapped to its overview.",
   "No prose outside the JSON, no code fence."
 ].join("\n");
 
+// ../extractor/src/yaml.ts
+var RESERVED_WORD = /^(y|n|yes|no|true|false|on|off|null|~)$/i;
+var NUMERIC = /^[-+]?(\d[\d_]*(\.\d*)?([eE][-+]?\d+)?|\.\d+|0[xob][0-9a-fA-F_]+)$/;
+var SPECIAL_FLOAT = /^[-+]?\.(inf|nan)$/i;
+var LEADING_INDICATOR = /^[-?:,[\]{}#&*!|>'"%@`]/;
+var CONTROL_CHAR = /[\x00-\x1f]/;
+function needsQuote(s) {
+  if (s === "") return true;
+  if (LEADING_INDICATOR.test(s)) return true;
+  if (/^\s|\s$/.test(s)) return true;
+  if (s.includes(": ") || s.endsWith(":")) return true;
+  if (s.includes(" #")) return true;
+  if (RESERVED_WORD.test(s)) return true;
+  if (SPECIAL_FLOAT.test(s)) return true;
+  if (NUMERIC.test(s)) return true;
+  if (CONTROL_CHAR.test(s)) return true;
+  return false;
+}
+function unicodeEscape(ch) {
+  return "\\u" + ch.charCodeAt(0).toString(16).padStart(4, "0");
+}
+function doubleQuote(s) {
+  const body = s.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t").replace(/[\x00-\x1f]/g, (ch) => unicodeEscape(ch));
+  return `"${body}"`;
+}
+function inlineScalar(s) {
+  return needsQuote(s) ? doubleQuote(s) : s;
+}
+function isInline(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "number") return true;
+  if (typeof value === "string") return value.includes("\r") || !value.includes("\n");
+  if (Array.isArray(value)) return value.length === 0;
+  return Object.values(value).filter((v) => v !== void 0).length === 0;
+}
+function inlineText(value) {
+  if (value === null) return "null";
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new Error(`yaml: cannot emit ${String(value)}`);
+    return String(value);
+  }
+  if (typeof value === "string") return inlineScalar(value);
+  if (Array.isArray(value)) return "[]";
+  return "{}";
+}
+var FLOW_MAX = 72;
+function flowEligible(value, depth = 0) {
+  if (isInline(value)) return true;
+  if (typeof value === "string") return false;
+  if (depth >= 2) return false;
+  if (Array.isArray(value)) return value.every((m) => flowEligible(m, depth + 1));
+  if (value === null || typeof value !== "object") {
+    throw new Error(`yaml: flowEligible() called on a non-collection value: ${JSON.stringify(value)}`);
+  }
+  const members = Object.values(value).filter((v) => v !== void 0);
+  if (members.length === 0) return true;
+  return members.every((m) => flowEligible(m, depth + 1));
+}
+var FLOW_UNSAFE = /[,{}[\]]/;
+function flowScalar(value) {
+  if (typeof value !== "string") return inlineText(value);
+  return needsQuote(value) || FLOW_UNSAFE.test(value) ? doubleQuote(value) : value;
+}
+function flowText(value) {
+  if (isInline(value)) return flowScalar(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((v) => flowText(v)).join(", ")}]`;
+  }
+  if (value === null || typeof value !== "object") {
+    throw new Error(`yaml: flowText() called on a non-collection value: ${JSON.stringify(value)}`);
+  }
+  const entries = Object.entries(value).filter(([, v]) => v !== void 0);
+  return `{ ${entries.map(([k, v]) => `${flowScalar(k)}: ${flowText(v)}`).join(", ")} }`;
+}
+function asFlow(value) {
+  if (isInline(value)) return null;
+  if (!flowEligible(value)) return null;
+  const text = flowText(value);
+  return text.length <= FLOW_MAX ? text : null;
+}
+function blockScalarLines(s, indent) {
+  const pad = " ".repeat(indent);
+  let trailingNewlines = 0;
+  while (trailingNewlines < s.length && s[s.length - 1 - trailingNewlines] === "\n") {
+    trailingNewlines++;
+  }
+  const core = trailingNewlines === 0 ? s : s.slice(0, s.length - trailingNewlines);
+  const indicator = trailingNewlines === 0 ? "|-" : "|+";
+  const extraBlankLines = trailingNewlines >= 1 ? trailingNewlines - 1 : 0;
+  const contentLines = core.split("\n").concat(Array(extraBlankLines).fill(""));
+  return [indicator, ...contentLines.map((l) => l === "" ? "" : pad + l)];
+}
+function emitMapEntry(key, value, indent) {
+  const pad = " ".repeat(indent);
+  const k = inlineScalar(key);
+  if (isInline(value)) {
+    return [`${pad}${k}: ${inlineText(value)}`];
+  }
+  const flow = asFlow(value);
+  if (flow !== null) {
+    return [`${pad}${k}: ${flow}`];
+  }
+  if (typeof value === "string") {
+    const [indicator, ...lines] = blockScalarLines(value, indent + 2);
+    return [`${pad}${k}: ${indicator}`, ...lines];
+  }
+  return [`${pad}${k}:`, ...blockLines(value, indent + 2)];
+}
+function emitListItem(value, indent) {
+  const pad = " ".repeat(indent);
+  if (isInline(value)) {
+    return [`${pad}- ${inlineText(value)}`];
+  }
+  const flow = asFlow(value);
+  if (flow !== null) {
+    return [`${pad}- ${flow}`];
+  }
+  if (typeof value === "string") {
+    const [indicator, ...lines2] = blockScalarLines(value, indent + 2);
+    return [`${pad}- ${indicator}`, ...lines2];
+  }
+  const lines = blockLines(value, indent + 2);
+  const first = lines[0].slice(indent + 2);
+  return [`${pad}- ${first}`, ...lines.slice(1)];
+}
+function blockLines(value, indent) {
+  if (Array.isArray(value)) {
+    return value.flatMap((item) => emitListItem(item, indent));
+  }
+  if (value === null || typeof value !== "object") {
+    throw new Error(`yaml: blockLines() called on a non-collection value: ${JSON.stringify(value)}`);
+  }
+  const entries = Object.entries(value).filter((e) => e[1] !== void 0);
+  return entries.flatMap(([k, v]) => emitMapEntry(k, v, indent));
+}
+function toYaml(value) {
+  if (isInline(value)) return inlineText(value) + "\n";
+  if (typeof value === "string") {
+    const [indicator, ...lines] = blockScalarLines(value, 2);
+    return [indicator, ...lines].join("\n") + "\n";
+  }
+  return blockLines(value, 0).join("\n") + "\n";
+}
+
 // ../extractor/src/v5/value.ts
 var SUPPORTED_UNITS = ["px", "rem", "em", "%", "deg", "ms", "s"];
 var SUPPORTED_TOKEN_TYPES = [
@@ -845,6 +2109,14 @@ function canonicalJson(value) {
   }
   return JSON.stringify(value);
 }
+function semanticContentHash(payload) {
+  return `sha256:${(0, import_js_sha2562.sha256)(canonicalJson({
+    completeness: payload.completeness,
+    collections: payload.collections,
+    tokens: payload.tokens,
+    styles: payload.styles
+  }))}`;
+}
 
 // ../extractor/src/v5/validate.ts
 var ROOT = "<artifact>";
@@ -1322,46 +2594,392 @@ function validateRootSections(artifact, out) {
     }
   }
 }
-function validateLevel1(artifact) {
-  try {
-    const out = [];
-    if (!isRecord(artifact)) {
-      out.push(shape(ROOT, "The artifact root must be an object."));
-      return out;
+function validateLevel1(artifact) {
+  try {
+    const out = [];
+    if (!isRecord(artifact)) {
+      out.push(shape(ROOT, "The artifact root must be an object."));
+      return out;
+    }
+    validateRootSections(artifact, out);
+    if (!Array.isArray(artifact.tokens)) {
+      out.push(shape(ROOT, "`tokens` must be an array."));
+    } else {
+      artifact.tokens.forEach((token, index) => validateToken(token, index, out));
+    }
+    return out;
+  } catch (err) {
+    const message = err instanceof Error && err.message ? `The artifact could not be read; accessing its properties threw: ${err.message}` : "The artifact could not be read; accessing its properties threw.";
+    return [diagnostic("INCONSISTENT_VALUE_SHAPE", {
+      entity_id: "artifact",
+      message
+    })];
+  }
+}
+
+// ../extractor/src/v5/fonts.ts
+function fontRequirements(artifact) {
+  const byFamily = /* @__PURE__ */ new Map();
+  for (const style of artifact.styles.typography) {
+    const family = style.properties.font_family.resolved;
+    if (family === null || family.type !== "font_family") continue;
+    const bucket = byFamily.get(family.value) ?? { weights: /* @__PURE__ */ new Set(), used: /* @__PURE__ */ new Set() };
+    const weight = style.properties.font_weight.resolved;
+    if (weight !== null && weight.type === "number") bucket.weights.add(weight.value);
+    bucket.used.add(style.name);
+    byFamily.set(family.value, bucket);
+  }
+  return [...byFamily.entries()].sort((a, b) => compareCodeUnits(a[0], b[0])).map(([family, bucket]) => ({
+    family,
+    weights: [...bucket.weights].sort((a, b) => a - b),
+    used_by: [...bucket.used].sort(compareCodeUnits)
+  }));
+}
+
+// ../extractor/src/v5/aiContext.ts
+function readableLabels(items, idOf, nameOf) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const name = nameOf(item);
+    counts.set(name, (counts.get(name) ?? 0) + 1);
+  }
+  const preferred = items.map((item) => {
+    const id = idOf(item);
+    const name = nameOf(item);
+    return [id, counts.get(name) === 1 ? name : `${name} [${id}]`];
+  });
+  if (new Set(preferred.map(([, label]) => label)).size === preferred.length) {
+    return new Map(preferred);
+  }
+  return new Map(items.map((item) => [
+    idOf(item),
+    `[${idOf(item)}] ${nameOf(item)}`
+  ]));
+}
+function buildIndex(artifact) {
+  const collectionById = new Map(artifact.collections.map((collection) => [collection.id, collection]));
+  const tokenById = new Map(artifact.tokens.map((token) => [token.id, token]));
+  const collectionLabelById = readableLabels(
+    artifact.collections,
+    ({ id }) => id,
+    ({ name }) => name
+  );
+  const ambiguousEntityIds = /* @__PURE__ */ new Set();
+  for (const collection of artifact.collections) {
+    if (collectionLabelById.get(collection.id) !== collection.name) {
+      ambiguousEntityIds.add(collection.id);
+    }
+  }
+  const tokenLabelById = /* @__PURE__ */ new Map();
+  for (const collection of artifact.collections) {
+    const tokens = artifact.tokens.filter((token) => token.collection_id === collection.id);
+    const localLabels = readableLabels(tokens, ({ id }) => id, ({ name }) => name);
+    const collectionLabel = collectionLabelById.get(collection.id) ?? collection.name;
+    for (const token of tokens) {
+      const tokenLabel = localLabels.get(token.id) ?? token.name;
+      if (tokenLabel !== token.name) ambiguousEntityIds.add(token.id);
+      tokenLabelById.set(token.id, `${collectionLabel}/${tokenLabel}`);
+    }
+  }
+  const entityLabelById = new Map(tokenLabelById);
+  const addStyleLabels = (kind, styles) => {
+    const labels = readableLabels(styles, ({ id }) => id, ({ name }) => name);
+    for (const style of styles) {
+      const label = labels.get(style.id) ?? style.name;
+      if (label !== style.name) ambiguousEntityIds.add(style.id);
+      entityLabelById.set(style.id, `${kind}/${label}`);
+    }
+  };
+  addStyleLabels("Typography", artifact.styles.typography);
+  addStyleLabels("Effects", artifact.styles.effects);
+  const modeLabelByCollectionAndId = /* @__PURE__ */ new Map();
+  for (const collection of artifact.collections) {
+    modeLabelByCollectionAndId.set(collection.id, readableLabels(
+      collection.modes,
+      ({ id }) => id,
+      ({ name }) => name
+    ));
+  }
+  return {
+    collectionById,
+    tokenById,
+    collectionLabelById,
+    tokenLabelById,
+    entityLabelById,
+    modeLabelByCollectionAndId,
+    ambiguousEntityIds
+  };
+}
+function compactTypedValue(value, expectedType) {
+  let compact;
+  switch (value.type) {
+    case "color":
+      compact = value.alpha === 1 && value.channels === void 0 ? value.hex : {
+        hex: value.hex,
+        ...value.alpha !== 1 ? { alpha: value.alpha } : {},
+        ...value.channels ? { channels: [...value.channels] } : {}
+      };
+      break;
+    case "dimension":
+    case "duration":
+      compact = { number: value.number, unit: value.unit };
+      break;
+    case "cubic_bezier":
+      compact = [...value.value];
+      break;
+    case "number":
+    case "string":
+    case "boolean":
+    case "font_family":
+      compact = value.value;
+      break;
+    default: {
+      const exhaustive = value;
+      return exhaustive;
+    }
+  }
+  return expectedType !== void 0 && value.type !== expectedType ? { type: value.type, value: compact } : compact;
+}
+function referenceLabel(reference, index) {
+  if (reference.target_id !== null) {
+    const local = index.tokenLabelById.get(reference.target_id);
+    if (local !== void 0) return local;
+  }
+  const path = reference.target_path.length > 0 ? reference.target_path.join("/") : reference.target_id ?? "<unknown target>";
+  return reference.source_library_name ? `${reference.source_library_name}/${path}` : path;
+}
+function stepLabel(step, index) {
+  const token = index.tokenById.get(step.token_id);
+  if (token === void 0) return `${step.token_id} @ ${step.mode_id}`;
+  const tokenLabel = index.tokenLabelById.get(token.id) ?? token.name;
+  const modeLabel = index.modeLabelByCollectionAndId.get(token.collection_id)?.get(step.mode_id) ?? step.mode_id;
+  return `${tokenLabel} @ ${modeLabel}`;
+}
+function compactCanonicalValue(value, expectedType, index) {
+  if (value.kind === "literal") return compactTypedValue(value.value, expectedType);
+  if (value.kind === "missing") return { missing: value.reason };
+  const chain = value.resolved.chain.map((step) => stepLabel(step, index));
+  const firstStep = value.resolved.chain[0];
+  const alias = firstStep !== void 0 && firstStep.token_id === value.reference.target_id ? stepLabel(firstStep, index) : referenceLabel(value.reference, index);
+  return {
+    alias,
+    ...value.resolved.status === "resolved" ? { resolved: compactTypedValue(value.resolved.value, expectedType) } : { unresolved: value.resolved.reason },
+    ...chain.length > 1 || value.resolved.status === "unresolved" && chain.length > 0 ? { chain } : {}
+  };
+}
+function compactLifecycle(lifecycle, index) {
+  if (lifecycle === void 0) return void 0;
+  const replacement = lifecycle.replacement_id === null ? void 0 : index.entityLabelById.get(lifecycle.replacement_id) ?? lifecycle.replacement_id;
+  return { status: lifecycle.status, ...replacement ? { replacement } : {} };
+}
+function compactToken(token, collection, index, includeSourceIds) {
+  const modeLabels2 = index.modeLabelByCollectionAndId.get(collection.id) ?? /* @__PURE__ */ new Map();
+  const values = {};
+  for (const [modeId, value] of Object.entries(token.values)) {
+    values[modeLabels2.get(modeId) ?? modeId] = compactCanonicalValue(value, token.type, index);
+  }
+  const lifecycle = compactLifecycle(token.lifecycle, index);
+  return {
+    name: token.name,
+    ...includeSourceIds || index.ambiguousEntityIds.has(token.id) ? { source_id: token.id } : {},
+    ...token.suggested_code_name ? { suggested_code_name: token.suggested_code_name } : {},
+    type: token.type,
+    ...token.description.length > 0 ? { description: token.description } : {},
+    ...token.scopes.length > 0 ? { scopes: token.scopes } : {},
+    ...token.code_syntax ? { code_syntax: token.code_syntax } : {},
+    ...token.publication ? { publication: token.publication } : {},
+    ...lifecycle ? { lifecycle } : {},
+    values
+  };
+}
+function compactStyleProperty(property, index) {
+  if (property.source.kind === "literal") {
+    return property.resolved === null ? { missing: "source_unavailable" } : { type: property.resolved.type, value: compactTypedValue(property.resolved) };
+  }
+  const path = property.source.target_path.join("/");
+  const target = property.source.target_id === null ? path || "<unknown target>" : (index.tokenLabelById.get(property.source.target_id) ?? path) || property.source.target_id;
+  return {
+    alias: target,
+    ...property.resolved === null ? { unresolved: "target_not_found" } : { resolved: { type: property.resolved.type, value: compactTypedValue(property.resolved) } }
+  };
+}
+function styleIdentity(style, index, includeSourceIds) {
+  const lifecycle = compactLifecycle(style.lifecycle, index);
+  return {
+    name: style.name,
+    ...includeSourceIds || index.ambiguousEntityIds.has(style.id) ? { source_id: style.id } : {},
+    ...style.suggested_code_name ? { suggested_code_name: style.suggested_code_name } : {},
+    ...style.publication ? { publication: {
+      published: style.publication.published,
+      hidden_from_publishing: style.publication.hidden_from_publishing
+    } } : {},
+    ...style.source ? { source: {
+      remote: style.source.remote,
+      ...style.source.library_name === null ? {} : { library_name: style.source.library_name }
+    } } : {},
+    ...lifecycle ? { lifecycle } : {}
+  };
+}
+function compactTypography(style, index, includeSourceIds) {
+  return {
+    ...styleIdentity(style, index, includeSourceIds),
+    ...style.description.length > 0 ? { description: style.description } : {},
+    properties: {
+      font_family: compactStyleProperty(style.properties.font_family, index),
+      font_weight: compactStyleProperty(style.properties.font_weight, index),
+      font_size: compactStyleProperty(style.properties.font_size, index),
+      line_height: compactStyleProperty(style.properties.line_height, index),
+      letter_spacing: compactStyleProperty(style.properties.letter_spacing, index),
+      paragraph_spacing: compactStyleProperty(style.properties.paragraph_spacing, index),
+      paragraph_indent: compactStyleProperty(style.properties.paragraph_indent, index),
+      text_case: style.properties.text_case,
+      text_decoration: style.properties.text_decoration
     }
-    validateRootSections(artifact, out);
-    if (!Array.isArray(artifact.tokens)) {
-      out.push(shape(ROOT, "`tokens` must be an array."));
-    } else {
-      artifact.tokens.forEach((token, index) => validateToken(token, index, out));
+  };
+}
+function compactEffect(style, index, includeSourceIds) {
+  const modeMatches = [...index.collectionById.values()].flatMap((collection) => {
+    const label = index.modeLabelByCollectionAndId.get(collection.id)?.get(style.mode_id ?? "");
+    return label === void 0 ? [] : [label];
+  });
+  const mode = style.mode_id === null ? null : modeMatches.length === 1 ? modeMatches[0] : style.mode_id;
+  return {
+    ...styleIdentity(style, index, includeSourceIds),
+    mode,
+    effects: style.effects.map((effect) => ({
+      type: effect.type,
+      visible: effect.visible,
+      ...effect.blend_mode !== void 0 ? { blend_mode: effect.blend_mode } : {},
+      ...effect.color ? { color: compactTypedValue(effect.color, "color") } : {},
+      ...effect.offset_x ? { offset_x: compactTypedValue(effect.offset_x, "dimension") } : {},
+      ...effect.offset_y ? { offset_y: compactTypedValue(effect.offset_y, "dimension") } : {},
+      ...effect.blur ? { blur: compactTypedValue(effect.blur, "dimension") } : {},
+      ...effect.spread ? { spread: compactTypedValue(effect.spread, "dimension") } : {},
+      ...effect.show_behind_node !== void 0 ? { show_behind_node: effect.show_behind_node } : {}
+    })),
+    ...style.bindings && style.bindings.length > 0 ? { bindings: Object.fromEntries(style.bindings.map((binding) => [
+      binding.property,
+      index.tokenLabelById.get(binding.token_id) ?? binding.token_id
+    ])) } : {}
+  };
+}
+function kebab(code3) {
+  return code3.toLowerCase().replace(/_/g, "-");
+}
+function valueText(value) {
+  if (value === null || value === void 0) return "unknown";
+  if (typeof value === "object") {
+    const record = value;
+    if ("value" in record) return String(record.value);
+    if ("number" in record) {
+      const unit = typeof record.unit === "string" ? record.unit : "";
+      return `${String(record.number)}${unit}`;
+    }
+    if (typeof record.hex === "string") {
+      const alpha = typeof record.alpha === "number" ? ` alpha ${record.alpha}` : "";
+      const channels = Array.isArray(record.channels) ? ` channels ${JSON.stringify(record.channels)}` : "";
+      return `${record.hex}${alpha}${channels}`;
     }
-    return out;
-  } catch (err) {
-    const message = err instanceof Error && err.message ? `The artifact could not be read; accessing its properties threw: ${err.message}` : "The artifact could not be read; accessing its properties threw.";
-    return [diagnostic("INCONSISTENT_VALUE_SHAPE", {
-      entity_id: "artifact",
-      message
-    })];
   }
+  return String(value);
 }
-
-// ../extractor/src/v5/fonts.ts
-function fontRequirements(artifact) {
-  const byFamily = /* @__PURE__ */ new Map();
-  for (const style of artifact.styles.typography) {
-    const family = style.properties.font_family.resolved;
-    if (family === null || family.type !== "font_family") continue;
-    const bucket = byFamily.get(family.value) ?? { weights: /* @__PURE__ */ new Set(), used: /* @__PURE__ */ new Set() };
-    const weight = style.properties.font_weight.resolved;
-    if (weight !== null && weight.type === "number") bucket.weights.add(weight.value);
-    bucket.used.add(style.name);
-    byFamily.set(family.value, bucket);
+var DIAGNOSTIC_MESSAGE = {
+  STYLE_BINDING_DRIFT: (d) => `${String(d.details?.property)} is ${valueText(d.details?.style_value)} in the style but ${valueText(d.details?.token_value)} in the token it is bound to; the two disagree.`,
+  UNIT_METADATA_UNAVAILABLE: (d) => `The numeric value is kept, but scopes ${JSON.stringify(d.details?.scopes ?? [])} state no unit, so a consumer cannot use it as a length.`,
+  UNRESOLVED_REFERENCE: (d) => d.message
+};
+function diagnosticRows(diagnostics, index) {
+  const rows = diagnostics.flatMap((d) => {
+    const render = DIAGNOSTIC_MESSAGE[d.code];
+    if (!render) return [];
+    const property = d.details?.property;
+    const path = index.entityLabelById.get(d.entity_id) ?? d.entity_id;
+    return [{
+      id: kebab(d.code),
+      severity: d.severity,
+      path,
+      ...typeof property === "string" ? { property } : {},
+      message: render(d)
+    }];
+  });
+  return rows.sort((a, b) => compareCodeUnits(a.id, b.id) || compareCodeUnits(a.path ?? "", b.path ?? "") || compareCodeUnits(a.property ?? "", b.property ?? "") || compareCodeUnits(a.message, b.message));
+}
+function issueCounts(artifact) {
+  const bySeverity = /* @__PURE__ */ new Map();
+  for (const finding of artifact.diagnostics) {
+    const byCode = bySeverity.get(finding.severity) ?? /* @__PURE__ */ new Map();
+    byCode.set(finding.code, (byCode.get(finding.code) ?? 0) + 1);
+    bySeverity.set(finding.severity, byCode);
+  }
+  if (bySeverity.size === 0) return void 0;
+  return Object.fromEntries([...bySeverity].sort(([a], [b]) => compareCodeUnits(a, b)).map(
+    ([severity, byCode]) => [severity, Object.fromEntries(
+      [...byCode].sort(([a], [b]) => compareCodeUnits(a, b))
+    )]
+  ));
+}
+function foundationAiContext(artifact, options = {}) {
+  const includeSourceIds = options.includeSourceIds === true;
+  const index = buildIndex(artifact);
+  const tokensByCollection = /* @__PURE__ */ new Map();
+  for (const token of artifact.tokens) {
+    const tokens = tokensByCollection.get(token.collection_id) ?? [];
+    tokens.push(token);
+    tokensByCollection.set(token.collection_id, tokens);
   }
-  return [...byFamily.entries()].sort((a, b) => compareCodeUnits(a[0], b[0])).map(([family, bucket]) => ({
-    family,
-    weights: [...bucket.weights].sort((a, b) => a - b),
-    used_by: [...bucket.used].sort(compareCodeUnits)
-  }));
+  const collections = artifact.collections.map((collection) => {
+    const tokens = tokensByCollection.get(collection.id) ?? [];
+    const modeLabels2 = index.modeLabelByCollectionAndId.get(collection.id) ?? /* @__PURE__ */ new Map();
+    return {
+      name: collection.name,
+      ...includeSourceIds || index.ambiguousEntityIds.has(collection.id) ? { source_id: collection.id } : {},
+      ...collection.suggested_code_name ? { suggested_code_name: collection.suggested_code_name } : {},
+      ...collection.publication ? { publication: collection.publication } : {},
+      ...collection.source ? { source: {
+        remote: collection.source.remote,
+        ...collection.source.library_name === null ? {} : { library_name: collection.source.library_name }
+      } } : {},
+      default_mode: modeLabels2.get(collection.default_mode_id) ?? collection.default_mode_id,
+      modes: collection.modes.map((mode) => modeLabels2.get(mode.id) ?? mode.name),
+      tokens: tokens.map((token) => compactToken(
+        token,
+        collection,
+        index,
+        includeSourceIds
+      ))
+    };
+  });
+  const counts = issueCounts(artifact);
+  const validation = diagnosticRows(artifact.diagnostics, index);
+  return {
+    spec_layer: {
+      kind: "foundation",
+      version: 5,
+      profile: "ai",
+      content_hash: artifact.spec_layer.export.content_hash,
+      source: {
+        provider: "figma",
+        ...artifact.spec_layer.source.file_name === null ? {} : { file_name: artifact.spec_layer.source.file_name }
+      }
+    },
+    completeness: artifact.completeness,
+    collections,
+    styles: {
+      typography: artifact.styles.typography.map((style) => compactTypography(
+        style,
+        index,
+        includeSourceIds
+      )),
+      effects: artifact.styles.effects.map((style) => compactEffect(
+        style,
+        index,
+        includeSourceIds
+      ))
+    },
+    ...validation.length > 0 ? { validation } : {},
+    ...counts ? { issue_counts: counts } : {},
+    ...artifact.guidelines ? { guidelines: artifact.guidelines.group_descriptions } : {}
+  };
 }
 
 // ../extractor/src/v5/dtcg.ts
@@ -2318,6 +3936,598 @@ function dtcgExportFiles(out) {
   return files;
 }
 
+// ../extractor/src/v5/componentContext.ts
+var import_js_sha2564 = __toESM(require_sha256(), 1);
+function componentFoundationAiSlice(artifact) {
+  const payload = artifact.references.foundation;
+  if (!payload) return null;
+  const dependencyArtifact = {
+    ...payload,
+    spec_layer: {
+      kind: "foundation",
+      // The Foundation schema's own version, since this slice is a Foundation
+      // artifact: the two happen to agree today and need not tomorrow.
+      schema_version: SCHEMA_VERSION,
+      schema_uri: "https://spec-layer.com/schemas/foundation-context/v5.json",
+      extractor: artifact.spec_layer.extractor,
+      export: {
+        id: `${artifact.spec_layer.export.id}:foundation-dependencies`,
+        generated_at: artifact.spec_layer.export.generated_at,
+        deterministic: true,
+        content_hash: artifact.foundation_dependency_hash ?? semanticContentHash(payload)
+      },
+      source: {
+        provider: "figma",
+        file_id: null,
+        file_name: artifact.spec_layer.source.file_name,
+        file_version: null,
+        library_enabled: null
+      }
+    },
+    diagnostics: artifact.foundation_diagnostics ?? [],
+    statistics: {}
+  };
+  return {
+    dependency_hash: dependencyArtifact.spec_layer.export.content_hash,
+    compact: foundationAiContext(dependencyArtifact, { includeSourceIds: true })
+  };
+}
+function componentEnvelope(artifact, profile) {
+  return {
+    spec_layer: {
+      kind: "component",
+      version: 5,
+      profile,
+      content_hash: artifact.spec_layer.export.content_hash,
+      ...artifact.foundation_content_hash ? { foundation_hash: artifact.foundation_content_hash } : {},
+      source: {
+        provider: "figma",
+        ...artifact.spec_layer.source.file_name ? { file_name: artifact.spec_layer.source.file_name } : {}
+      }
+    },
+    source: {
+      node_id: artifact.spec_layer.source.node_id,
+      node_name: artifact.spec_layer.source.node_name,
+      ...artifact.spec_layer.source.component_key ? { component_key: artifact.spec_layer.source.component_key } : {}
+    }
+  };
+}
+
+// ../extractor/src/v5/markdown.ts
+var COMPONENT_YAML_MARKER = "spec_layer:\n  kind: component";
+var COMPONENT_MARKDOWN_MARKER = "---\nspec_layer:\n  kind: component";
+function escapeInline(text) {
+  return text.replace(/\r?\n/g, " ").replace(/([\\*_<>[\]])/g, "\\$1").trim();
+}
+function escapeCell(text) {
+  return text.replace(/\r?\n/g, " ").replace(/([\\*_<>[\]|])/g, "\\$1").trim();
+}
+function escapeHeading(text) {
+  return escapeCell(text).replace(/^#/, "\\#");
+}
+function escapeBlock(text) {
+  return escapeInline(text).replace(/^(`{3,}|~{3,}|[#=+-])/, "\\$1").replace(/^(\d{1,9})([.)])/, "$1\\$2");
+}
+function code(text) {
+  const flat = text.replace(/\r?\n/g, " ");
+  const longest = (flat.match(/`+/g) ?? []).reduce((n, run) => Math.max(n, run.length), 0);
+  const fence = "`".repeat(longest + 1);
+  return longest === 0 ? `${fence}${flat}${fence}` : `${fence} ${flat} ${fence}`;
+}
+function codeCell(text) {
+  if (text.includes("\\")) return escapeCell(text);
+  return code(text).replace(/\|/g, "\\|");
+}
+function table(headers, rows) {
+  const line = (cells) => `| ${cells.join(" | ")} |
+`;
+  return line(headers) + `|${headers.map(() => "---").join("|")}|
+` + rows.map(line).join("");
+}
+var asRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+var str = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
+var SCOPE_SENTENCE = {
+  default_variant: "Default variant."
+};
+function bindingsSection(references) {
+  const bindings = Array.isArray(references.bindings) ? references.bindings : [];
+  if (bindings.length === 0) return void 0;
+  const byId = new Map(
+    (Array.isArray(references.used) ? references.used : []).map((r) => [
+      asRecord(r).source_id,
+      r
+    ])
+  );
+  const rows = bindings.map((raw) => {
+    const binding = asRecord(raw);
+    const source_id = str(binding.source_id);
+    const reference = source_id ? byId.get(source_id) : void 0;
+    const ref = asRecord(reference);
+    const name = str(ref.name) ?? source_id;
+    const status = ref.status && ref.status !== "resolved" ? ` (${ref.status})` : "";
+    const when = asRecord(binding.when);
+    const whenStr = Object.entries(when).map(([axis, raw_values]) => {
+      const values = Array.isArray(raw_values) ? raw_values : [];
+      return `${escapeCell(axis)}: ${values.map((v) => escapeCell(String(v))).join(", ")}`;
+    }).join("; ");
+    const path = str(binding.path);
+    const property = str(binding.property);
+    return [
+      path ? codeCell(path) : "",
+      property ? escapeCell(property) : "",
+      `${escapeCell(name ?? "")}${status}`,
+      whenStr
+    ];
+  });
+  return `## Token bindings
+
+${table(["Part", "Property", "Token", "When"], rows).trimEnd()}`;
+}
+function layoutSection(layout) {
+  const items = Array.isArray(layout.items) ? layout.items : [];
+  if (items.length === 0) return void 0;
+  const rows = items.map((raw) => {
+    const item = asRecord(raw);
+    const path = str(item.path);
+    return [path ? codeCell(path) : "", escapeCell(str(item.summary) ?? "")];
+  });
+  const scope = str(layout.scope);
+  const sentence = scope ? SCOPE_SENTENCE[scope] : void 0;
+  const parts = ["## Layout"];
+  if (sentence) parts.push(sentence);
+  parts.push(table(["Part", "Layout"], rows).trimEnd());
+  return parts.join("\n\n");
+}
+function propertiesSection(api) {
+  const rows = [];
+  for (const [name, raw] of Object.entries(asRecord(api.variants))) {
+    const axis = asRecord(raw);
+    const options = Array.isArray(axis.options) ? axis.options.map((o) => escapeCell(String(o))).join(", ") : "";
+    rows.push([escapeCell(name), "Variant", options, escapeCell(String(axis.default ?? ""))]);
+  }
+  for (const [name, raw] of Object.entries(asRecord(api.booleans))) {
+    const b = asRecord(raw);
+    rows.push([
+      escapeCell(name),
+      "Boolean",
+      "",
+      b.default === void 0 ? "" : escapeCell(String(b.default))
+    ]);
+  }
+  for (const [name, raw] of Object.entries(asRecord(api.slots))) {
+    const slot = asRecord(raw);
+    const type = str(slot.type);
+    const label = type ? type.charAt(0).toUpperCase() + type.slice(1) : "Slot";
+    rows.push([
+      escapeCell(name),
+      label,
+      "",
+      slot.default === void 0 ? "" : escapeCell(String(slot.default))
+    ]);
+  }
+  const states = Array.isArray(api.states) ? api.states.map((s) => escapeInline(String(s))) : [];
+  if (rows.length === 0 && states.length === 0) return void 0;
+  const parts = ["## Properties"];
+  if (rows.length > 0) {
+    parts.push(table(["Property", "Type", "Options", "Default"], rows).trimEnd());
+  }
+  if (states.length > 0) parts.push(`States: ${states.join(", ")}`);
+  return parts.join("\n\n");
+}
+function anatomyBullets(nodes, depth) {
+  const lines = [];
+  for (const raw of nodes) {
+    const node = asRecord(raw);
+    const part = escapeInline(str(node.part) ?? "");
+    const path = str(node.path);
+    const type = str(node.type);
+    const parts = [];
+    if (path) parts.push(code(path));
+    const component = str(node.component);
+    if (component) parts.push(`instance of ${escapeInline(component)}`);
+    else if (type) parts.push(escapeInline(type.toLowerCase()));
+    const shownBy = str(node.shown_by);
+    if (shownBy) parts.push(`shown when ${code(shownBy)} is true`);
+    lines.push(`${"  ".repeat(depth)}- ${part}: ${parts.join(", ")}`);
+    if (Array.isArray(node.children)) {
+      lines.push(...anatomyBullets(node.children, depth + 1));
+    }
+  }
+  return lines;
+}
+var NOT_READ_SENTENCE = "Token values are not included: the foundations had not been read when this was exported.";
+function styleValueText(value) {
+  if (value !== null && typeof value === "object") {
+    const record = value;
+    if (typeof record.missing === "string") return `missing: ${record.missing}`;
+    if (typeof record.alias === "string") {
+      if (record.resolved !== void 0) {
+        const resolved2 = record.resolved;
+        return `${record.alias} (resolved: ${valueText(resolved2.value)})`;
+      }
+      if (typeof record.unresolved === "string") {
+        return `${record.alias} (unresolved: ${record.unresolved})`;
+      }
+    }
+    if ("value" in record) return valueText(record.value);
+  }
+  return valueText(value);
+}
+function typographySection(items) {
+  if (items.length === 0) return void 0;
+  const rows = items.map((raw) => {
+    const style = asRecord(raw);
+    const properties = asRecord(style.properties);
+    return [
+      escapeCell(str(style.name) ?? ""),
+      escapeCell(styleValueText(properties.font_family)),
+      escapeCell(styleValueText(properties.font_weight)),
+      escapeCell(styleValueText(properties.font_size)),
+      escapeCell(styleValueText(properties.line_height)),
+      escapeCell(styleValueText(properties.letter_spacing)),
+      escapeCell(styleValueText(properties.paragraph_indent))
+    ];
+  });
+  return [
+    "### Typography styles",
+    table(
+      ["Style", "Font family", "Weight", "Size", "Line height", "Letter spacing", "Paragraph indent"],
+      rows
+    ).trimEnd()
+  ].join("\n\n");
+}
+function effectSummary(effect) {
+  const parts = [];
+  const type = str(effect.type);
+  if (type) parts.push(type);
+  if (effect.offset_x !== void 0 || effect.offset_y !== void 0) {
+    parts.push(`offset ${valueText(effect.offset_x)}/${valueText(effect.offset_y)}`);
+  }
+  if (effect.blur !== void 0) parts.push(`blur ${valueText(effect.blur)}`);
+  if (effect.spread !== void 0) parts.push(`spread ${valueText(effect.spread)}`);
+  if (effect.color !== void 0) parts.push(valueText(effect.color));
+  const summary = parts.join(", ");
+  return effect.visible === false ? `${summary} (hidden)` : summary;
+}
+function effectsSection(items) {
+  if (items.length === 0) return void 0;
+  const rows = items.map((raw) => {
+    const style = asRecord(raw);
+    const mode = str(style.mode);
+    const effects = Array.isArray(style.effects) ? style.effects : [];
+    const summary = effects.map((effect) => effectSummary(asRecord(effect))).join("; ");
+    return [escapeCell(str(style.name) ?? ""), mode ? escapeCell(mode) : "", escapeCell(summary)];
+  });
+  return [
+    "### Effect styles",
+    table(["Style", "Mode", "Effects"], rows).trimEnd()
+  ].join("\n\n");
+}
+function inlineEffectLayerText(raw) {
+  const layer = asRecord(raw);
+  const type = str(layer.type) ?? "unknown";
+  const num = (value) => typeof value === "number" ? String(value) : "";
+  let summary;
+  switch (type) {
+    case "drop-shadow":
+    case "inner-shadow": {
+      const offset = asRecord(layer.offset);
+      const color = asRecord(layer.color);
+      const parts = [type, `offset ${num(offset.x)}/${num(offset.y)}`, `radius ${num(layer.radius)}`];
+      if (layer.spread !== void 0) parts.push(`spread ${num(layer.spread)}`);
+      if (str(color.hex)) parts.push(`${str(color.hex)} alpha ${num(color.alpha)}`);
+      summary = parts.join(", ");
+      break;
+    }
+    case "layer-blur":
+    case "background-blur": {
+      const progressive = layer.blurType === "progressive";
+      const parts = [progressive ? `${type} (progressive)` : type, `radius ${num(layer.radius)}`];
+      if (progressive) {
+        const startOffset = asRecord(layer.startOffset);
+        const endOffset = asRecord(layer.endOffset);
+        parts.push(`start radius ${num(layer.startRadius)}`);
+        parts.push(`start offset ${num(startOffset.x)}/${num(startOffset.y)}`);
+        parts.push(`end offset ${num(endOffset.x)}/${num(endOffset.y)}`);
+      }
+      summary = parts.join(", ");
+      break;
+    }
+    case "noise": {
+      const color = asRecord(layer.color);
+      const noiseType = str(layer.noiseType);
+      const parts = [noiseType ? `noise (${noiseType})` : "noise"];
+      if (str(color.hex)) parts.push(`${str(color.hex)} alpha ${num(color.alpha)}`);
+      parts.push(`size ${num(layer.noiseSize)}`);
+      parts.push(`density ${num(layer.density)}`);
+      const secondary = asRecord(layer.secondaryColor);
+      if (str(secondary.hex)) parts.push(`secondary ${str(secondary.hex)} alpha ${num(secondary.alpha)}`);
+      if (layer.opacity !== void 0) parts.push(`opacity ${num(layer.opacity)}`);
+      summary = parts.join(", ");
+      break;
+    }
+    case "texture": {
+      const parts = [
+        "texture",
+        `size ${num(layer.noiseSize)}`,
+        `radius ${num(layer.radius)}`,
+        `clip ${layer.clipToShape === true ? "true" : "false"}`
+      ];
+      const vector = asRecord(layer.noiseSizeVector);
+      if (vector.x !== void 0) parts.push(`vector ${num(vector.x)}/${num(vector.y)}`);
+      summary = parts.join(", ");
+      break;
+    }
+    case "glass": {
+      summary = [
+        "glass",
+        `radius ${num(layer.radius)}`,
+        `light intensity ${num(layer.lightIntensity)}`,
+        `light angle ${num(layer.lightAngle)}`,
+        `refraction ${num(layer.refraction)}`,
+        `depth ${num(layer.depth)}`,
+        `dispersion ${num(layer.dispersion)}`
+      ].join(", ");
+      break;
+    }
+    default: {
+      const figmaType = str(layer.figma_type);
+      summary = figmaType ? `unknown (${figmaType})` : "unknown";
+    }
+  }
+  const bindings = layer.bindings !== void 0 ? asRecord(layer.bindings) : void 0;
+  const boundText = bindings ? Object.entries(bindings).map(([field, reference]) => `${field} bound to ${str(asRecord(reference).name) ?? ""}`).join(", ") : "";
+  const hidden = layer.visible === false ? " (hidden)" : "";
+  return `${summary}${boundText ? `, ${boundText}` : ""}${hidden}`;
+}
+function effectsInlineSection(items) {
+  if (items.length === 0) return void 0;
+  const rows = items.map((raw) => {
+    const item = asRecord(raw);
+    const path = str(item.path);
+    const layers = Array.isArray(item.layers) ? item.layers : [];
+    const summary = layers.map((layer) => inlineEffectLayerText(layer)).join("; ");
+    return [path ? codeCell(path) : "", escapeCell(summary)];
+  });
+  return `## Effects
+
+${table(["Part", "Effects"], rows).trimEnd()}`;
+}
+function unboundSection(unbound) {
+  const entries = Array.isArray(unbound) ? unbound : [];
+  if (entries.length === 0) return void 0;
+  const rows = entries.map((raw) => {
+    const entry2 = asRecord(raw);
+    return [
+      str(entry2.path) ? codeCell(str(entry2.path)) : "",
+      escapeCell(str(entry2.property) ?? ""),
+      escapeCell(str(entry2.issue) ?? ""),
+      entry2.value === void 0 ? "" : escapeCell(String(entry2.value))
+    ];
+  });
+  return `## Unbound values
+
+${table(["Part", "Property", "Issue", "Value"], rows).trimEnd()}`;
+}
+function issuesSection(artifact) {
+  const validation = Array.isArray(artifact.validation) ? artifact.validation : [];
+  const lines = [];
+  for (const raw of validation) {
+    const row = asRecord(raw);
+    if (str(row.id) === "unbound-value") continue;
+    lines.push(issueLine(row));
+  }
+  return lines.length === 0 ? void 0 : `## Issues
+
+${lines.join("\n")}`;
+}
+function issueLine(row) {
+  const severity = escapeInline(str(row.severity) ?? "info");
+  const message = escapeInline(str(row.message) ?? "");
+  const where = [
+    str(row.path) ? code(str(row.path)) : void 0,
+    str(row.property) ? escapeInline(str(row.property)) : void 0
+  ].filter((v) => v !== void 0);
+  return `- ${severity}: ${message}${where.length > 0 ? ` (${where.join(", ")})` : ""}`;
+}
+function foundationIssuesSection(rows) {
+  if (!rows || rows.length === 0) return void 0;
+  return `### Foundation issues
+
+${rows.map((row) => issueLine(asRecord(row))).join("\n")}`;
+}
+function tokenValueText(value) {
+  if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+    const record = value;
+    if (typeof record.missing === "string") return `missing: ${record.missing}`;
+    if (typeof record.alias === "string") {
+      const chain = Array.isArray(record.chain) ? record.chain.filter((step) => typeof step === "string") : [];
+      const steps = chain.length === 0 ? [record.alias] : chain[0] === record.alias ? chain : [record.alias, ...chain];
+      const target = steps.join(" \u2192 ");
+      if (record.resolved !== void 0) return `${target} (resolved: ${valueText(record.resolved)})`;
+      if (typeof record.unresolved === "string") return `${target} (unresolved: ${record.unresolved})`;
+      return target;
+    }
+  }
+  return valueText(value);
+}
+function tokensUsedSection(artifact) {
+  const slice = componentFoundationAiSlice(artifact);
+  if (!slice) return `## Tokens used
+
+${NOT_READ_SENTENCE}`;
+  const { compact } = slice;
+  const parts = ["## Tokens used"];
+  parts.push(
+    `Foundation: collections ${compact.completeness.collections}, styles ${compact.completeness.styles}.`
+  );
+  if (compact.completeness.unavailable_sources.length > 0) {
+    parts.push(`Unavailable sources: ${compact.completeness.unavailable_sources.map((source) => escapeInline(source)).join(", ")}.`);
+  }
+  for (const collection of compact.collections) {
+    parts.push(`### ${escapeInline(collection.name)}`);
+    const modes = collection.modes.map((mode) => mode === collection.default_mode ? `${escapeInline(mode)} (default)` : escapeInline(mode));
+    parts.push(`Modes: ${modes.join(", ")}.`);
+    const rows = collection.tokens.map((token) => [
+      escapeCell(token.name),
+      escapeCell(token.type),
+      ...collection.modes.map((mode) => escapeCell(tokenValueText(token.values[mode]))),
+      token.code_syntax ? Object.entries(token.code_syntax).map(([platform, id]) => id ? `${escapeCell(platform)} ${codeCell(id)}` : escapeCell(platform)).join(", ") : ""
+    ]);
+    parts.push(table(
+      ["Token", "Type", ...collection.modes.map((mode) => escapeCell(mode)), "Code syntax"],
+      rows
+    ).trimEnd());
+  }
+  const typography = typographySection(compact.styles.typography);
+  if (typography) parts.push(typography);
+  const effects = effectsSection(compact.styles.effects);
+  if (effects) parts.push(effects);
+  const issues = foundationIssuesSection(compact.validation);
+  if (issues) parts.push(issues);
+  return parts.join("\n\n");
+}
+var AI_MARKER = "*Written by AI from the extracted facts, not read from Figma.*";
+var ATX_H1_H2 = /^ {0,3}(#{1,2})(?= |$)/;
+var FENCE_MARKER = /^(`{3,}|~{3,})/;
+var SETEXT_UNDERLINE = /^(?:=+|-+)$/;
+function demote(blob) {
+  const lines = blob.split("\n");
+  const out = [];
+  let inFence = false;
+  const isHeadingOrFence = (line) => {
+    if (line === void 0) return false;
+    const trimmed = line.trim();
+    return /^#{1,6}(?= |$)/.test(trimmed) || FENCE_MARKER.test(trimmed);
+  };
+  for (const rawLine of lines) {
+    const trimmed = rawLine.trim();
+    if (FENCE_MARKER.test(trimmed)) {
+      inFence = !inFence;
+      out.push(rawLine);
+      continue;
+    }
+    if (inFence) {
+      out.push(rawLine);
+      continue;
+    }
+    if (SETEXT_UNDERLINE.test(trimmed)) {
+      const previous = out[out.length - 1];
+      const previousIsBlank = previous === void 0 || previous.trim() === "";
+      if (!previousIsBlank && !isHeadingOrFence(previous)) {
+        out[out.length - 1] = `### ${previous.trim()}`;
+        continue;
+      }
+      out.push(rawLine);
+      continue;
+    }
+    out.push(rawLine.replace(ATX_H1_H2, "###"));
+  }
+  return out.join("\n").trimEnd();
+}
+function proseSection(heading, blob) {
+  return `## ${heading}
+
+${AI_MARKER}
+
+${demote(blob)}`;
+}
+function overviewBlock(guidelines) {
+  const blob = str(guidelines.definition);
+  return blob ? proseSection("Overview", blob) : void 0;
+}
+function anatomyProseParagraph(guidelines) {
+  const blob = str(guidelines.anatomy_summary);
+  return blob ? `${AI_MARKER}
+
+${demote(blob)}` : void 0;
+}
+function ruleList(items) {
+  const indent = (blob) => blob.split("\n").map((line, index) => index === 0 || line === "" ? line : `  ${line}`).join("\n");
+  return items.map((item) => `- ${indent(demote(String(item)))}`).join("\n");
+}
+function restProseBlocks(guidelines) {
+  const blocks = [];
+  const add = (heading, key) => {
+    const blob = str(guidelines[key]);
+    if (blob) blocks.push(proseSection(heading, blob));
+  };
+  add("Variants", "variants_summary");
+  const dos = Array.isArray(guidelines.dos) ? guidelines.dos : [];
+  const donts = Array.isArray(guidelines.donts) ? guidelines.donts : [];
+  if (dos.length > 0 || donts.length > 0) {
+    const parts = [`## Do and don't`, AI_MARKER];
+    if (dos.length > 0) parts.push("### Do", ruleList(dos));
+    if (donts.length > 0) parts.push(`### Don't`, ruleList(donts));
+    blocks.push(parts.join("\n\n"));
+  }
+  add("Accessibility", "accessibility");
+  add("Interactions", "interactions");
+  add("Content considerations", "content_considerations");
+  add("Design considerations", "design_considerations");
+  return blocks;
+}
+function frontMatter(artifact) {
+  const envelope = componentEnvelope(artifact, "markdown");
+  return `---
+${toYaml(envelope)}---
+`;
+}
+function componentMarkdown(artifact) {
+  const component = asRecord(artifact.component);
+  const guidelines = asRecord(artifact.guidelines);
+  const blocks = [];
+  const name = str(component.name);
+  if (name === void 0) throw new Error("componentMarkdown needs component.name; the artifact has none.");
+  if (!Array.isArray(artifact.anatomy)) {
+    throw new Error("componentMarkdown needs anatomy as an array; the artifact has none.");
+  }
+  blocks.push(`# ${escapeHeading(name)}`);
+  const description = str(component.description);
+  if (description) blocks.push(escapeBlock(description));
+  const related = Array.isArray(component.related) ? component.related.filter((r) => typeof r === "string") : [];
+  if (related.length > 0) {
+    blocks.push(`Related: ${related.map((r) => escapeInline(r)).join(", ")}`);
+  }
+  const overview = overviewBlock(guidelines);
+  if (overview) blocks.push(overview);
+  if (artifact.api !== void 0) {
+    const section = propertiesSection(asRecord(artifact.api));
+    if (section) blocks.push(section);
+  }
+  if (artifact.anatomy.length > 0) {
+    const anatomyProse = anatomyProseParagraph(guidelines);
+    const bullets = anatomyBullets(artifact.anatomy, 0).join("\n");
+    const body = anatomyProse ? `${anatomyProse}
+
+${bullets}` : bullets;
+    blocks.push(`## Anatomy
+
+${body}`);
+  }
+  if (artifact.layout !== void 0) {
+    const section = layoutSection(asRecord(artifact.layout));
+    if (section) blocks.push(section);
+  }
+  const bindings = bindingsSection(asRecord(artifact.references));
+  if (bindings) blocks.push(bindings);
+  blocks.push(tokensUsedSection(artifact));
+  if (artifact.effects_inline !== void 0) {
+    const section = effectsInlineSection(
+      Array.isArray(artifact.effects_inline) ? artifact.effects_inline : []
+    );
+    if (section) blocks.push(section);
+  }
+  const unbound = unboundSection(artifact.unbound);
+  if (unbound) blocks.push(unbound);
+  const issues = issuesSection(artifact);
+  if (issues) blocks.push(issues);
+  blocks.push(...restProseBlocks(guidelines));
+  return `${frontMatter(artifact)}
+${blocks.join("\n\n")}
+`;
+}
+
 // ../extractor/src/v5/usageUnits.ts
 var LENGTH_SCOPES = ["CORNER_RADIUS", "WIDTH_HEIGHT", "GAP", "FONT_SIZE", "STROKE_FLOAT"];
 var LENGTH_PROPERTIES = [
@@ -2538,12 +4748,12 @@ function acceptCssDeclared(declared) {
   if (BARE_IDENT.test(declared)) return `--${declared}`;
   return null;
 }
-var asRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : null;
+var asRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : null;
 function collectLeaves(tree, prefix, out) {
-  const node = asRecord(tree);
+  const node = asRecord2(tree);
   if (!node) return;
   if ("$value" in node) {
-    const ours = asRecord(asRecord(node.$extensions)?.[EXT]);
+    const ours = asRecord2(asRecord2(node.$extensions)?.[EXT]);
     out.push({
       path: prefix.join("."),
       type: typeof node.$type === "string" ? node.$type : "",
@@ -2559,7 +4769,7 @@ function collectLeaves(tree, prefix, out) {
 }
 var unpointer = (s) => s.replace(/~1/g, "/").replace(/~0/g, "~");
 var refFile = (src) => {
-  const r = asRecord(src);
+  const r = asRecord2(src);
   return r && typeof r.$ref === "string" ? r.$ref : null;
 };
 function sourcesOf(resolver) {
@@ -2634,7 +4844,7 @@ function cssValue(ctx, type, value, property) {
   switch (type) {
     case "color": {
       if (typeof value === "string") return value;
-      const c = asRecord(value);
+      const c = asRecord2(value);
       if (c && typeof c.hex === "string" && typeof c.alpha === "number") {
         if (c.alpha === 1) return c.hex;
         const [r, g, b] = hexChannels(c.hex);
@@ -2645,7 +4855,7 @@ function cssValue(ctx, type, value, property) {
     case "dimension":
     case "duration": {
       if (typeof value === "string") return value;
-      const d = asRecord(value);
+      const d = asRecord2(value);
       if (d && typeof d.value === "number" && typeof d.unit === "string") return `${d.value}${d.unit}`;
       break;
     }
@@ -2707,7 +4917,7 @@ function typographyMemberKeys(value, ext) {
   }
   for (const key of ["lineHeight", "letterSpacing"]) {
     if (key in value) continue;
-    const d = asRecord(ext[key]);
+    const d = asRecord2(ext[key]);
     if (d && typeof d.value === "number" && typeof d.unit === "string") keys.push(key);
   }
   for (const [key, extKey] of TEXT_MEMBERS) {
@@ -2724,7 +4934,7 @@ function converted(ctx, property, from, to) {
   });
 }
 function extensionDimension(ctx, ext, key, name, percentTo) {
-  const d = asRecord(ext[key]);
+  const d = asRecord2(ext[key]);
   if (!d || typeof d.value !== "number" || typeof d.unit !== "string") return null;
   if (d.unit === "%") {
     const to = percentTo(canonicalNumber(d.value / 100));
@@ -2736,7 +4946,7 @@ function extensionDimension(ctx, ext, key, name, percentTo) {
 function typographyDecls(ctx, leaf, names) {
   const decls = [];
   const declaredPaths = [];
-  const value = asRecord(leaf.value) ?? {};
+  const value = asRecord2(leaf.value) ?? {};
   const ext = leaf.ext ?? {};
   const nameFor = (key) => names.get(`${leaf.path}.${key}`);
   for (const [key, type] of TYPOGRAPHY_MEMBERS2) {
@@ -2769,12 +4979,12 @@ function typographyDecls(ctx, leaf, names) {
       }
     }
   }
-  for (const [key, extKey, table] of TEXT_MEMBERS) {
+  for (const [key, extKey, table2] of TEXT_MEMBERS) {
     const raw = ext[extKey];
     if (typeof raw !== "string") continue;
     const name = nameFor(key);
     if (name === void 0) continue;
-    const css = table[raw];
+    const css = table2[raw];
     if (css !== void 0) {
       decls.push(`${name}: ${css};`);
       declaredPaths.push(`${leaf.path}.${key}`);
@@ -2805,7 +5015,7 @@ function shadowDecl(ctx, leaf, name) {
   if (layers.length === 0) return omit("no_visible_shadow", "The style has no visible shadow, so no box-shadow was written.");
   const parts = [];
   for (const layer of layers) {
-    const l = asRecord(layer);
+    const l = asRecord2(layer);
     if (!l) return omit("layer_not_an_object", "A shadow layer is not an object; the style was omitted.");
     const members = [];
     for (const [key, type] of SHADOW_MEMBERS) {
@@ -2930,7 +5140,7 @@ function cssOutput(exp, header, options = {}) {
   for (const leaves of leavesByFile.values()) {
     for (const leaf of leaves) {
       if (leaf.type === "typography") {
-        const value = asRecord(leaf.value) ?? {};
+        const value = asRecord2(leaf.value) ?? {};
         const ext = leaf.ext ?? {};
         for (const key of typographyMemberKeys(value, ext)) candidatePaths.add(`${leaf.path}.${key}`);
       } else {
@@ -3002,16 +5212,13 @@ ${imports.join("\n")}
   return { files, map, report: sortReport(entries) };
 }
 
-// ../extractor/src/v5/componentContext.ts
-var import_js_sha2564 = __toESM(require_sha256(), 1);
-
 // ../extractor/src/libraryBundle.ts
 var LIBRARY_BUNDLE_SCHEMA = "spec-layer-library-bundle";
 var LibraryBundleError = class extends Error {
-  constructor(code2, message) {
+  constructor(code3, message) {
     super(message);
     this.name = "LibraryBundleError";
-    this.code = code2;
+    this.code = code3;
   }
 };
 var isRecord3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -3020,11 +5227,26 @@ function hasContentHash(artifact) {
   const exp = artifact.spec_layer.export;
   return isRecord3(exp) && typeof exp.content_hash === "string";
 }
+function readVariants(value) {
+  if (!Array.isArray(value)) return void 0;
+  const out = [];
+  for (const item of value) {
+    if (!isRecord3(item) || typeof item.name !== "string" || !isRecord3(item.values)) return void 0;
+    const values = {};
+    for (const [axis, v] of Object.entries(item.values)) {
+      if (typeof v !== "string") return void 0;
+      values[axis] = v;
+    }
+    out.push({ name: item.name, values });
+  }
+  return out;
+}
 function entry(v, where) {
   if (!isRecord3(v) || typeof v.name !== "string" || typeof v.ai !== "string" || !hasContentHash(v.artifact)) {
     throw new LibraryBundleError("malformed", `The ${where} entry in this bundle is malformed.`);
   }
-  return { name: v.name, ai: v.ai, artifact: v.artifact };
+  const variants = readVariants(v.variants);
+  return { name: v.name, ai: v.ai, artifact: v.artifact, ...variants ? { variants } : {} };
 }
 function supportedVersion(version) {
   return typeof version === "string" && /^1\.\d+\.\d+$/.test(version);
@@ -3073,6 +5295,39 @@ function parseLibraryBundle(input) {
 // ../extractor/src/libraryBundleHash.ts
 var import_js_sha2565 = __toESM(require_sha256(), 1);
 
+// ../extractor/src/componentSlugs.ts
+var DASH = 45;
+function slugify(name) {
+  const collapsed = name.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+  let start = 0;
+  let end = collapsed.length;
+  while (start < end && collapsed.charCodeAt(start) === DASH) start += 1;
+  while (end > start && collapsed.charCodeAt(end - 1) === DASH) end -= 1;
+  const slug2 = collapsed.slice(start, end);
+  return slug2 || "component";
+}
+function componentSlugs(names) {
+  const usedSlugs = /* @__PURE__ */ new Set();
+  const nextSuffix = /* @__PURE__ */ new Map();
+  return names.map((name) => {
+    const base = slugify(name);
+    let slug2 = base;
+    if (usedSlugs.has(slug2)) {
+      let n = (nextSuffix.get(base) ?? 1) + 1;
+      slug2 = `${base}-${n}`;
+      while (usedSlugs.has(slug2)) {
+        n += 1;
+        slug2 = `${base}-${n}`;
+      }
+      nextSuffix.set(base, n);
+    } else {
+      nextSuffix.set(base, 1);
+    }
+    usedSlugs.add(slug2);
+    return slug2;
+  });
+}
+
 // src/bundle.ts
 function parseBundle(raw) {
   try {
@@ -3393,15 +5648,17 @@ var inside = (parent, child) => {
   return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
 };
 var isDotfile = (name) => name.startsWith(".");
+var markerList = (marker) => typeof marker === "string" ? [marker] : marker;
 function carriesMarker(abs, marker) {
-  const newlines = (marker.match(/\n/g) ?? []).length;
-  const wantBytes = Buffer.byteLength(marker, "utf8") + newlines;
+  const markers = markerList(marker);
+  if (markers.length === 0) return false;
+  const wantBytes = Math.max(...markers.map((m) => Buffer.byteLength(m, "utf8") + (m.match(/\n/g) ?? []).length));
   const fd = openSync(abs, "r");
   try {
     const buf = Buffer.alloc(wantBytes);
     const read = readSync(fd, buf, 0, wantBytes, 0);
     const text = buf.subarray(0, read).toString("utf8").replace(/\r\n/g, "\n");
-    return text.startsWith(marker);
+    return markers.some((m) => text.startsWith(m));
   } finally {
     closeSync(fd);
   }
@@ -3478,18 +5735,18 @@ function parseOutput(value, index) {
   }
   const spec = specOf(r.platform, r.format);
   if (!spec) throw new Error(`${at}: unknown platform/format "${r.platform}/${r.format}". Known: ${knownFormats()}.`);
-  const str = (key) => {
+  const str2 = (key) => {
     if (r[key] !== void 0 && typeof r[key] !== "string") throw new Error(`${at} "${key}" must be a string.`);
     return r[key];
   };
-  const path = str("path") ?? spec.defaultPath;
+  const path = str2("path") ?? spec.defaultPath;
   if (path === null) throw new Error(`${at} needs "path": ${spec.platform} has no default location.`);
-  const nameCase = str("case");
+  const nameCase = str2("case");
   if (nameCase !== void 0 && !NAME_CASES.includes(nameCase)) {
     throw new Error(`${at} "case" takes ${NAME_CASES.join(", ")}.`);
   }
-  const root = str("root");
-  const modeSelector = str("modeSelector");
+  const root = str2("root");
+  const modeSelector = str2("modeSelector");
   let modes;
   if (r.modes !== void 0) {
     const m = r.modes;
@@ -3545,6 +5802,11 @@ var DEFAULT_API = "https://api.spec-layer.com";
 var DEFAULT_OUT_DIR = ".speclayer";
 var DEFAULT_COMPONENT_SPECS_DIR = "component-specs";
 var CONFIG_NAME = "speclayer.json";
+var COMPONENT_FORMATS = ["yaml", "md"];
+var DEFAULT_COMPONENT_FORMAT = "yaml";
+function isComponentFormat(value) {
+  return typeof value === "string" && COMPONENT_FORMATS.includes(value);
+}
 var invalidConfig = () => new Error(`${CONFIG_NAME} is not valid JSON. Fix or delete it, then retry.`);
 function parseInclude(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalidConfig();
@@ -3583,6 +5845,10 @@ function parseComponentSpecsDir(value) {
   if (dir.length === 0) throw new Error('speclayer.json "componentSpecsDir" must be a non-empty string.');
   return dir;
 }
+function parseComponentSpecsFormat(value) {
+  if (!isComponentFormat(value)) throw new Error('speclayer.json "componentSpecsFormat" must be "yaml" or "md".');
+  return value;
+}
 function parsePlatforms(value) {
   if (!Array.isArray(value) || !value.every((p) => typeof p === "string" && isPlatform(p))) {
     throw new Error(`speclayer.json "platforms" must be an array of ${PLATFORMS.join(", ")}.`);
@@ -3617,6 +5883,7 @@ function readConfig(cwd) {
     ...typeof record.libraryId === "string" ? { libraryId: record.libraryId } : {},
     ...typeof record.outDir === "string" ? { outDir: record.outDir } : {},
     ...record.componentSpecsDir !== void 0 ? { componentSpecsDir: parseComponentSpecsDir(record.componentSpecsDir) } : {},
+    ...record.componentSpecsFormat !== void 0 ? { componentSpecsFormat: parseComponentSpecsFormat(record.componentSpecsFormat) } : {},
     ...record.include !== void 0 ? { include: parseInclude(record.include) } : {},
     ...record.dtcg !== void 0 ? { dtcg: parseDtcg(record.dtcg) } : {},
     ...record.platforms !== void 0 ? { platforms: parsePlatforms(record.platforms) } : {},
@@ -3628,6 +5895,7 @@ function writeConfig(cwd, config) {
     libraryId: config.libraryId,
     outDir: config.outDir,
     ...config.componentSpecsDir ? { componentSpecsDir: config.componentSpecsDir } : {},
+    ...config.componentSpecsFormat ? { componentSpecsFormat: config.componentSpecsFormat } : {},
     ...config.include ? { include: config.include } : {},
     ...config.dtcg ? { dtcg: config.dtcg } : {},
     ...config.platforms && config.platforms.length > 0 ? { platforms: config.platforms } : {},
@@ -3657,6 +5925,7 @@ function resolveOptions(cwd, flags, env, manifestLibraryId) {
     // A trailing slash would build "//v1/..." paths the proxy router 404s on.
     api: (flags.api ?? env.SPEC_LAYER_API ?? DEFAULT_API).replace(/\/+$/, ""),
     key: supplied ?? storedKey,
+    ...config?.componentSpecsFormat ? { componentSpecsFormat: config.componentSpecsFormat } : {},
     ...config?.include ? { include: config.include } : {},
     ...config?.dtcg ? { dtcg: config.dtcg } : {},
     ...config?.platforms ? { platforms: config.platforms } : {},
@@ -3680,7 +5949,8 @@ async function fetchBundle(opts) {
   } catch {
     return { kind: "error", message: `Could not reach ${opts.api}.` };
   }
-  if (res.status === 304) return { kind: "not_modified" };
+  const version = res.headers.get("X-Library-Version");
+  if (res.status === 304) return { kind: "not_modified", version };
   if (res.status === 401) {
     return {
       kind: "error",
@@ -3694,7 +5964,8 @@ async function fetchBundle(opts) {
     kind: "ok",
     raw,
     publishedAt: res.headers.get("X-Published-At") ?? "unknown",
-    bundleHash: createHash("sha256").update(raw).digest("hex")
+    bundleHash: createHash("sha256").update(raw).digest("hex"),
+    version
   };
 }
 
@@ -3745,11 +6016,21 @@ function cliVersion() {
 }
 
 // src/files.ts
-function slugify(name) {
-  const slug2 = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return slug2 || "component";
+var COMPONENT_SPEC_MARKER = COMPONENT_YAML_MARKER;
+var COMPONENT_SPEC_MARKERS = [COMPONENT_YAML_MARKER, COMPONENT_MARKDOWN_MARKER];
+function componentMarkdownPage(component) {
+  const failed = () => new Error(
+    `The published component context for ${component.name} could not be rendered as Markdown. Republish from the plugin, then pull again.`
+  );
+  let page;
+  try {
+    page = componentMarkdown(component.artifact);
+  } catch {
+    throw failed();
+  }
+  if (!page.startsWith(COMPONENT_MARKDOWN_MARKER)) throw failed();
+  return page;
 }
-var COMPONENT_SPEC_MARKER = "spec_layer:\n  kind: component";
 function readManifest(outDir) {
   const path = join5(outDir, "manifest.json");
   if (!existsSync5(path)) return null;
@@ -3776,27 +6057,6 @@ function readLocalBundle(outDir) {
     throw new Error(`${path} could not be read as a library bundle. Run spec-layer pull again.`);
   }
 }
-function componentSlugs(bundle) {
-  const usedSlugs = /* @__PURE__ */ new Set();
-  const nextSuffix = /* @__PURE__ */ new Map();
-  return bundle.components.map((component) => {
-    const base = slugify(component.name);
-    let slug2 = base;
-    if (usedSlugs.has(slug2)) {
-      let n = (nextSuffix.get(base) ?? 1) + 1;
-      slug2 = `${base}-${n}`;
-      while (usedSlugs.has(slug2)) {
-        n += 1;
-        slug2 = `${base}-${n}`;
-      }
-      nextSuffix.set(base, n);
-    } else {
-      nextSuffix.set(base, 1);
-    }
-    usedSlugs.add(slug2);
-    return slug2;
-  });
-}
 function assertReplaceable(outDir, cwd) {
   const rel = relative2(resolve3(cwd), resolve3(outDir));
   if (rel === "" || rel.startsWith("..") || isAbsolute2(rel)) {
@@ -3810,12 +6070,13 @@ function writeBundleFiles(opts) {
   assertReplaceable(opts.outDir, opts.cwd);
   const selection = opts.selection ?? DEFAULT_SELECTION;
   const selected = selectComponents(opts.bundle, selection);
-  const slugs = componentSlugs(opts.bundle);
+  const slugs = componentSlugs(opts.bundle.components.map((c) => c.name));
   const outputs = opts.outputs ?? [];
   const componentSpecsDir = opts.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR;
+  const componentSpecsFormat = opts.componentSpecsFormat ?? DEFAULT_COMPONENT_FORMAT;
   const outDirRel = relative2(resolve3(opts.cwd), resolve3(opts.outDir)).split(sep).join("/");
   const outputPaths = outputs.map((o) => o.path);
-  const specsProblem = visibleDirProblem(opts.cwd, outDirRel, componentSpecsDir, COMPONENT_SPEC_MARKER, outputPaths, "componentSpecsDir");
+  const specsProblem = visibleDirProblem(opts.cwd, outDirRel, componentSpecsDir, COMPONENT_SPEC_MARKERS, outputPaths, "componentSpecsDir");
   if (specsProblem) throw new Error(specsProblem);
   for (const o of outputs) {
     const problem = outputPathProblem(opts.cwd, outDirRel, o, [componentSpecsDir, ...outputPaths.filter((p) => p !== o.path)]);
@@ -3824,6 +6085,10 @@ function writeBundleFiles(opts) {
   const briefs = {};
   opts.bundle.components.forEach((component, i) => {
     if (!selected[i]) return;
+    if (componentSpecsFormat === "md") {
+      briefs[`${slugs[i]}.md`] = componentMarkdownPage(component);
+      return;
+    }
     if (!component.ai.startsWith(COMPONENT_SPEC_MARKER)) {
       throw new Error(`The published brief for ${component.name} does not begin with the Spec Layer marker. Republish from the plugin, then pull again.`);
     }
@@ -3879,7 +6144,7 @@ function writeBundleFiles(opts) {
         kind: "component",
         name: component.name,
         contentHash: component.artifact.spec_layer.export.content_hash,
-        path: selected[i] ? `${componentSpecsDir}/${slugs[i]}.yaml` : null
+        path: selected[i] ? `${componentSpecsDir}/${slugs[i]}.${componentSpecsFormat}` : null
       });
     });
     const manifest = {
@@ -3891,7 +6156,9 @@ function writeBundleFiles(opts) {
       cliVersion: cliVersion(),
       selection,
       componentSpecsDir,
+      componentSpecsFormat,
       artifacts,
+      ...opts.version ? { version: opts.version } : {},
       ...opts.dtcg && Object.keys(opts.dtcg).length > 0 ? { dtcg: opts.dtcg } : {},
       ...opts.platforms && opts.platforms.length > 0 ? { platforms: opts.platforms } : {},
       ...opts.outputs ? { outputs: opts.outputs } : {}
@@ -3903,7 +6170,7 @@ function writeBundleFiles(opts) {
   }
   rmSync2(opts.outDir, { recursive: true, force: true });
   renameSync2(staging, opts.outDir);
-  const componentSpecs = { path: componentSpecsDir, files: writeVisibleDir(opts.cwd, componentSpecsDir, COMPONENT_SPEC_MARKER, briefs) };
+  const componentSpecs = { path: componentSpecsDir, files: writeVisibleDir(opts.cwd, componentSpecsDir, COMPONENT_SPEC_MARKERS, briefs) };
   const outputResults = [];
   for (const d of deliverables) {
     outputResults.push({ path: d.output.path, files: writeVisibleDir(opts.cwd, d.output.path, CSS_HEADER_PREFIX, d.files, CSS_INDEX_FILE) });
@@ -3979,7 +6246,7 @@ var PULL_EXITS = {
 var TOOLS = [
   {
     name: "setup",
-    usage: "spec-layer setup --id lib_... --key sl_... [--out DIR] [--platform web|ios|android|flutter]... [--only foundation|components] [--component NAME]...",
+    usage: "spec-layer setup --id lib_... --key sl_... [--out DIR] [--platform web|ios|android|flutter]... [--component-format yaml|md] [--only foundation|components] [--component NAME]...",
     summary: "Records the library id, stores the pull key in a gitignored speclayer.local.json, then pulls.",
     when: "Once, with the command the plugin's Publish screen hands out. Re-run it after the key is rotated.",
     network: true,
@@ -3996,7 +6263,7 @@ var TOOLS = [
   },
   {
     name: "init",
-    usage: "spec-layer init --id lib_... [--out DIR] [--platform web|ios|android|flutter]... [--only foundation|components] [--component NAME]...",
+    usage: "spec-layer init --id lib_... [--out DIR] [--platform web|ios|android|flutter]... [--component-format yaml|md] [--only foundation|components] [--component NAME]...",
     summary: "Writes speclayer.json, with the platforms and default outputs, so later commands need no flags. Stores no key and reaches no server.",
     when: "A repo that supplies the key from SPEC_LAYER_KEY instead of a stored file.",
     network: false,
@@ -4006,9 +6273,9 @@ var TOOLS = [
   },
   {
     name: "pull",
-    usage: "spec-layer pull [--id lib_...] [--key sl_...] [--out DIR] [--platform web|ios|android|flutter]... [--only foundation|components] [--component NAME]... [--strict]",
-    summary: "Fetches the published library and writes the record under the output directory (default .speclayer/), the briefs under componentSpecsDir, and the token files under outputs[].path. Prints a severity summary to stderr, even on a cached pull, when tokens/report.json or an outputs/*.report.json holds an error or warning.",
-    when: "After setup, whenever status says the local copy is behind, or after changing the include, dtcg, outputs, or componentSpecsDir blocks. Add --strict in CI to fail the build on an error-severity report entry.",
+    usage: "spec-layer pull [--id lib_...] [--key sl_...] [--out DIR] [--platform web|ios|android|flutter]... [--component-format yaml|md] [--only foundation|components] [--component NAME]... [--strict]",
+    summary: "Fetches the published library and writes the record under the output directory (default .speclayer/), the briefs under componentSpecsDir (YAML, or Markdown when componentSpecsFormat or --component-format says md), and the token files under outputs[].path. Prints a severity summary to stderr, even on a cached pull, when tokens/report.json or an outputs/*.report.json holds an error or warning.",
+    when: "After setup, whenever status says the local copy is behind, or after changing the include, dtcg, outputs, componentSpecsDir, or componentSpecsFormat settings. Add --strict in CI to fail the build on an error-severity report entry.",
     network: true,
     needsKey: true,
     writes: [
@@ -4040,8 +6307,8 @@ var TOOLS = [
   },
   {
     name: "show",
-    usage: "spec-layer show foundation | component NAME [--canonical] [--out DIR]",
-    summary: "Prints one artifact to stdout: the Foundation DTCG document, or one component's AI YAML; --canonical prints the v5 JSON.",
+    usage: "spec-layer show foundation | component NAME [--component-format yaml|md] [--canonical] [--out DIR]",
+    summary: "Prints one artifact to stdout: the Foundation DTCG document, or one component's AI YAML or Markdown (by --component-format, then componentSpecsFormat, then the last pull); --canonical prints the v5 JSON.",
     when: "To read one component or the token document without opening files; it pipes cleanly.",
     network: false,
     needsKey: false,
@@ -4081,7 +6348,7 @@ function toolsText() {
     lines.push(`  ${tool.summary}`);
     lines.push(`  When: ${tool.when}`);
     lines.push(`  Network: ${tool.network ? "yes" : "no"}. Key: ${tool.needsKey ? "required" : "not needed"}. Writes: ${tool.writes.length ? tool.writes.join(", ") : "nothing"}.`);
-    lines.push(`  Exits: ${Object.entries(tool.exits).map(([code2, meaning]) => `${code2} ${meaning}`).join("; ")}.`);
+    lines.push(`  Exits: ${Object.entries(tool.exits).map(([code3, meaning]) => `${code3} ${meaning}`).join("; ")}.`);
     lines.push("");
   }
   lines.push("Flags every command accepts where they apply:");
@@ -4209,6 +6476,7 @@ function summarizePull(cwd, outDir, manifest) {
     publishedAt: manifest.publishedAt,
     pluginVersion: manifest.pluginVersion,
     componentSpecsDir: manifest.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR,
+    componentSpecsFormat: manifest.componentSpecsFormat ?? DEFAULT_COMPONENT_FORMAT,
     components,
     foundation,
     outputs: (manifest.outputs ?? []).map((o) => {
@@ -4237,7 +6505,7 @@ function summarizePull(cwd, outDir, manifest) {
     })
   };
 }
-var code = (s) => `\`${s}\``;
+var code2 = (s) => `\`${s}\``;
 function stackSection(input) {
   const { profile, platforms, platformSource, pull } = input;
   const lines = ["## This codebase", ""];
@@ -4247,7 +6515,7 @@ function stackSection(input) {
     );
   } else {
     lines.push("Detected from the repository root (the file that carries each signal is named, and nothing deeper was read):", "");
-    for (const e of profile.evidence) lines.push(`- ${e.signal} (${code(e.file)})`);
+    for (const e of profile.evidence) lines.push(`- ${e.signal} (${code2(e.file)})`);
     lines.push("");
     const facts = [];
     if (profile.languages.length) facts.push(`Languages: ${profile.languages.join(", ")}.`);
@@ -4257,7 +6525,7 @@ function stackSection(input) {
   }
   if (platformSource === "none") {
     lines.push(
-      `No target platform was detected, so the token advice below is generic. Re-run ${code("spec-layer skill --platform web|ios|android|flutter")} to write it for a platform, or pass ` + code("--install") + " with the same flag to update the installed copy.",
+      `No target platform was detected, so the token advice below is generic. Re-run ${code2("spec-layer skill --platform web|ios|android|flutter")} to write it for a platform, or pass ` + code2("--install") + " with the same flag to update the installed copy.",
       ""
     );
   } else {
@@ -4269,7 +6537,7 @@ function stackSection(input) {
     const n = pull.foundation.unitlessNumbers;
     const cssReport = pull.outputs.find((o) => o.platform === "web" && o.format === "css" && o.written) ?? null;
     lines.push(
-      `**${n} token${n === 1 ? " has" : "s have"} no unit.** ${n === 1 ? "Its own Figma variable states" : "Their own Figma variables state"} none at all, not even that ${n === 1 ? "it is" : "they are"} a unitless number the way an opacity or a font weight would. Those are already excluded from this count, because Figma states that for them. So ${n === 1 ? "it is" : "they are"} written as ${code('$type: "number"')}: a bare number, not usable as a CSS length. ${code("height: 36")} is invalid CSS and the browser drops the declaration. ${n === 1 ? "Narrow the variable's" : "Narrow each variable's"} scope in Figma to a length (${code("CORNER_RADIUS")}, ${code("GAP")}, ${code("WIDTH_HEIGHT")}, ${code("FONT_SIZE")}, or ${code("STROKE_FLOAT")}), or to ${code("OPACITY")}/${code("FONT_WEIGHT")} if it genuinely carries none, and pull again. Only add ${code('"dtcg": { "units": { "<Collection>/<name glob>": "px" } }')} in ${code("speclayer.json")} once you already know the token is a length: the override applies to anything the glob matches that Figma has not already scoped as unitless, so a glob that is too broad can turn a genuine opacity or font weight into a fake length. Nothing is inferred from a name; ${code(`${tokensDir}spec-layer.meta.json`)} names each token's own Figma scopes` + (cssReport ? `, and ${code(`${input.outDir}/outputs/${cssReport.platform}-${cssReport.format}.report.json`)} names every one under ${code("unitless_number")}. Do not read that file's entry count as this number: it carries one entry per mode a token appears in, and it also names the tokens Figma does scope as a unitless number, which this count leaves out.` : "."),
+      `**${n} token${n === 1 ? " has" : "s have"} no unit.** ${n === 1 ? "Its own Figma variable states" : "Their own Figma variables state"} none at all, not even that ${n === 1 ? "it is" : "they are"} a unitless number the way an opacity or a font weight would. Those are already excluded from this count, because Figma states that for them. So ${n === 1 ? "it is" : "they are"} written as ${code2('$type: "number"')}: a bare number, not usable as a CSS length. ${code2("height: 36")} is invalid CSS and the browser drops the declaration. ${n === 1 ? "Narrow the variable's" : "Narrow each variable's"} scope in Figma to a length (${code2("CORNER_RADIUS")}, ${code2("GAP")}, ${code2("WIDTH_HEIGHT")}, ${code2("FONT_SIZE")}, or ${code2("STROKE_FLOAT")}), or to ${code2("OPACITY")}/${code2("FONT_WEIGHT")} if it genuinely carries none, and pull again. Only add ${code2('"dtcg": { "units": { "<Collection>/<name glob>": "px" } }')} in ${code2("speclayer.json")} once you already know the token is a length: the override applies to anything the glob matches that Figma has not already scoped as unitless, so a glob that is too broad can turn a genuine opacity or font weight into a fake length. Nothing is inferred from a name; ${code2(`${tokensDir}spec-layer.meta.json`)} names each token's own Figma scopes` + (cssReport ? `, and ${code2(`${input.outDir}/outputs/${cssReport.platform}-${cssReport.format}.report.json`)} names every one under ${code2("unitless_number")}. Do not read that file's entry count as this number: it carries one entry per mode a token appears in, and it also names the tokens Figma does scope as a unitless number, which this count leaves out.` : "."),
       ""
     );
   }
@@ -4292,17 +6560,17 @@ function stackSection(input) {
           }
           const fallbackTarget = cssOut ? `${cssOut.path}/` : `${input.outDir}/`;
           lines.push(
-            `The token holds a family name and no fallback stack. Never write ${code("font-family")} from a token without appending a generic fallback, and never keep that fallback inside ${code(fallbackTarget)}: the next pull replaces it.`,
+            `The token holds a family name and no fallback stack. Never write ${code2("font-family")} from a token without appending a generic fallback, and never keep that fallback inside ${code2(fallbackTarget)}: the next pull replaces it.`,
             ""
           );
         } else if (fontsStatus === "ok") {
           lines.push(
-            `${code("fonts.json")} names no font family. Either this library's typography styles reference none, or a reference failed to resolve one; ${code("npx spec-layer show foundation")} prints the styles themselves.`,
+            `${code2("fonts.json")} names no font family. Either this library's typography styles reference none, or a reference failed to resolve one; ${code2("npx spec-layer show foundation")} prints the styles themselves.`,
             ""
           );
         } else {
           lines.push(
-            fontsStatus === "missing" ? `${code("fonts.json")} is missing, so the font requirement for this library is unknown here. Run ${code("npx spec-layer pull")} again: every pull that includes the Foundation writes this file, and a pull that finds it gone re-projects instead of reporting no change.` : `${code("fonts.json")} is not valid JSON, so the font requirement for this library is unknown here. Delete ${code(`${input.outDir}/fonts.json`)} and run ${code("npx spec-layer pull")} again, which rewrites it.`,
+            fontsStatus === "missing" ? `${code2("fonts.json")} is missing, so the font requirement for this library is unknown here. Run ${code2("npx spec-layer pull")} again: every pull that includes the Foundation writes this file, and a pull that finds it gone re-projects instead of reporting no change.` : `${code2("fonts.json")} is not valid JSON, so the font requirement for this library is unknown here. Delete ${code2(`${input.outDir}/fonts.json`)} and run ${code2("npx spec-layer pull")} again, which rewrites it.`,
             ""
           );
         }
@@ -4310,58 +6578,58 @@ function stackSection(input) {
       if (cssOut) {
         const mapPath = `${input.outDir}/outputs/web-css.map.json`;
         lines.push(
-          `The CSS custom property for every token is in ${code(mapPath)}: source "code_syntax" when the designer declared it in Figma, "derived" when the CLI built it from the DTCG path by the stated rule (${cssOut.case} case, collection root included). Each entry names the file that declares the property. Use those names; never invent a third. ${code(`${tokensDir}spec-layer.meta.json`)} still holds the raw ${code("code_syntax.WEB")} the designer declared.`,
+          `The CSS custom property for every token is in ${code2(mapPath)}: source "code_syntax" when the designer declared it in Figma, "derived" when the CLI built it from the DTCG path by the stated rule (${cssOut.case} case, collection root included). Each entry names the file that declares the property. Use those names; never invent a third. ${code2(`${tokensDir}spec-layer.meta.json`)} still holds the raw ${code2("code_syntax.WEB")} the designer declared.`,
           ""
         );
         const partFiles = cssOut.files.filter((f) => f !== CSS_INDEX_FILE);
         lines.push(
-          `Import ${code(`${cssOut.path}/index.css`)} from the root stylesheet. It imports one file per collection and mode: ${partFiles.join(", ")}. Sets and default modes are at ${code(":root")}; every other mode is a block under ${code(cssOut.modeSelector)} in its own file, so a mode can also be imported alone. To switch, set ${code("data-theme")} on ${code("<html>")} (or whatever the selector names). To let the OS choose, set that collection's selector to ${code(":root")} under ${code("outputs[].modes")} and import the mode's file yourself under ${code("@media (prefers-color-scheme: dark)")}; the CLI never assumes that.`,
+          `Import ${code2(`${cssOut.path}/index.css`)} from the root stylesheet. It imports one file per collection and mode: ${partFiles.join(", ")}. Sets and default modes are at ${code2(":root")}; every other mode is a block under ${code2(cssOut.modeSelector)} in its own file, so a mode can also be imported alone. To switch, set ${code2("data-theme")} on ${code2("<html>")} (or whatever the selector names). To let the OS choose, set that collection's selector to ${code2(":root")} under ${code2("outputs[].modes")} and import the mode's file yourself under ${code2("@media (prefers-color-scheme: dark)")}; the CLI never assumes that.`,
           ""
         );
         if (profile.tokenTools.includes("style-dictionary") || profile.tokenTools.includes("tokens-studio")) {
           lines.push(
-            `${code(`${cssOut.path}/`)} is a projection of the same ${code(tokensDir)} files, not a second source. Import one or the other.`,
+            `${code2(`${cssOut.path}/`)} is a projection of the same ${code2(tokensDir)} files, not a second source. Import one or the other.`,
             ""
           );
         }
       } else {
         lines.push(
-          `Token identifiers for code live in ${code(`${tokensDir}spec-layer.meta.json`)} under each token's ${code(`code_syntax.${key}`)}, when the designer declared one in Figma. When a token has no WEB entry, use the DTCG path as it appears in the token file and say in your change that the code name is not declared in Figma.`,
+          `Token identifiers for code live in ${code2(`${tokensDir}spec-layer.meta.json`)} under each token's ${code2(`code_syntax.${key}`)}, when the designer declared one in Figma. When a token has no WEB entry, use the DTCG path as it appears in the token file and say in your change that the code name is not declared in Figma.`,
           ""
         );
         const configuredNotWritten = pull?.outputs.find((o) => o.platform === "web" && !o.written) ?? null;
         if (configuredNotWritten?.indexMissing) {
           lines.push(
-            `A web/css output is configured at ${code(`${configuredNotWritten.path}/`)} but its ${code("index.css")} is missing, so the file list is unknown. Run ${code("npx spec-layer pull")} to write it again.`,
+            `A web/css output is configured at ${code2(`${configuredNotWritten.path}/`)} but its ${code2("index.css")} is missing, so the file list is unknown. Run ${code2("npx spec-layer pull")} to write it again.`,
             ""
           );
         } else if (configuredNotWritten) {
           lines.push(
-            `A web/css output is configured at ${code(`${configuredNotWritten.path}/`)} but was not written, because the last pull did not write the Foundation. Pull with the Foundation selected to write it.`,
+            `A web/css output is configured at ${code2(`${configuredNotWritten.path}/`)} but was not written, because the last pull did not write the Foundation. Pull with the Foundation selected to write it.`,
             ""
           );
         } else if (pull?.foundation?.written) {
           lines.push(
-            `No token file was written for web. Add \`"outputs"\` in \`speclayer.json\` (or run \`spec-layer pull --platform web\` once) and pull again; the default lands at ${code("tokens/")}.`,
+            `No token file was written for web. Add \`"outputs"\` in \`speclayer.json\` (or run \`spec-layer pull --platform web\` once) and pull again; the default lands at ${code2("tokens/")}.`,
             ""
           );
         }
       }
       if (profile.tokenTools.includes("tailwind")) {
         lines.push(
-          `Tailwind is present (${code("tailwindcss")}). Map DTCG ${code("color")} tokens to the theme's color scale and ${code("dimension")} tokens to spacing, radius, or font size by the collection and group they sit in. Keep the mapping in one place and reference token paths, not copied values, so a republish moves the code with it.`,
+          `Tailwind is present (${code2("tailwindcss")}). Map DTCG ${code2("color")} tokens to the theme's color scale and ${code2("dimension")} tokens to spacing, radius, or font size by the collection and group they sit in. Keep the mapping in one place and reference token paths, not copied values, so a republish moves the code with it.`,
           ""
         );
       }
       if (profile.tokenTools.includes("style-dictionary")) {
         const major = profile.styleDictionaryMajor;
         lines.push(
-          `Style Dictionary is present${major !== null ? ` (major version ${major} in package.json)` : ""}. Point it at ${code(tokensDir)} and load the files ${code("resolver.json")} names for the mode you build. Exclude ${code("spec-layer.meta.json")} and ${code("report.json")} from token globs; they are not token files.`
+          `Style Dictionary is present${major !== null ? ` (major version ${major} in package.json)` : ""}. Point it at ${code2(tokensDir)} and load the files ${code2("resolver.json")} names for the mode you build. Exclude ${code2("spec-layer.meta.json")} and ${code2("report.json")} from token globs; they are not token files.`
         );
         if (major !== null && major < 5) {
           lines.push(
             "",
-            `Style Dictionary ${major} reads the string value forms, not the 2025.10 object forms. Set ${code('"dtcg": { "values": "legacy" }')} in ${code("speclayer.json")} and run ${code("spec-layer pull")}; the change re-projects tokens/ without a republish.`
+            `Style Dictionary ${major} reads the string value forms, not the 2025.10 object forms. Set ${code2('"dtcg": { "values": "legacy" }')} in ${code2("speclayer.json")} and run ${code2("spec-layer pull")}; the change re-projects tokens/ without a republish.`
           );
         }
         lines.push("");
@@ -4369,19 +6637,19 @@ function stackSection(input) {
     } else if (platform === "ios") {
       lines.push("### iOS", "");
       lines.push(
-        `Token identifiers for code live in ${code(`${tokensDir}spec-layer.meta.json`)} under each token's ${code(`code_syntax.${key}`)}, when the designer declared one in Figma. Use that as the Swift symbol. Colors arrive as hex strings or DTCG color objects with RGBA components; dimensions carry an explicit px or rem unit. A modifier with more than one context (for example a light and a dark mode) maps to a color-scheme-dependent value; a set without modes is a constant. Do not invent a dark variant for a collection that has one mode.`,
+        `Token identifiers for code live in ${code2(`${tokensDir}spec-layer.meta.json`)} under each token's ${code2(`code_syntax.${key}`)}, when the designer declared one in Figma. Use that as the Swift symbol. Colors arrive as hex strings or DTCG color objects with RGBA components; dimensions carry an explicit px or rem unit. A modifier with more than one context (for example a light and a dark mode) maps to a color-scheme-dependent value; a set without modes is a constant. Do not invent a dark variant for a collection that has one mode.`,
         ""
       );
     } else if (platform === "android") {
       lines.push("### Android", "");
       lines.push(
-        `Token identifiers for code live in ${code(`${tokensDir}spec-layer.meta.json`)} under each token's ${code(`code_syntax.${key}`)}, when the designer declared one in Figma. Use that as the Kotlin or resource name. Dimensions carry an explicit px or rem unit and no density assumption; a value is only dp when your own convention says so, and that convention belongs in your code, not in the token file. Modes map to resource qualifiers or a Compose theme switch.`,
+        `Token identifiers for code live in ${code2(`${tokensDir}spec-layer.meta.json`)} under each token's ${code2(`code_syntax.${key}`)}, when the designer declared one in Figma. Use that as the Kotlin or resource name. Dimensions carry an explicit px or rem unit and no density assumption; a value is only dp when your own convention says so, and that convention belongs in your code, not in the token file. Modes map to resource qualifiers or a Compose theme switch.`,
         ""
       );
     } else {
       lines.push("### Flutter", "");
       lines.push(
-        `Figma declares no code syntax for Flutter, so no identifier is provided for Dart. Name symbols after the DTCG path (for example ${code("Collection.group.name")} becomes a nested class or a camelCase constant) and keep the path in a comment so the source token stays traceable. Modes map to theme variants.`,
+        `Figma declares no code syntax for Flutter, so no identifier is provided for Dart. Name symbols after the DTCG path (for example ${code2("Collection.group.name")} becomes a nested class or a camelCase constant) and keep the path in a comment so the source token stays traceable. Modes map to theme variants.`,
         ""
       );
     }
@@ -4393,46 +6661,46 @@ function pullSection(input) {
   const lines = ["## What is on disk", ""];
   if (!pull) {
     lines.push(
-      `No pull has been made in this directory yet, so nothing under ${code(outDir + "/")} can be described. Run ${code("npx spec-layer pull")} (or the setup command from the plugin if there is no ${code("speclayer.json")}), then ${code("npx spec-layer skill --install")} again to list the components and token collections here.`,
+      `No pull has been made in this directory yet, so nothing under ${code2(outDir + "/")} can be described. Run ${code2("npx spec-layer pull")} (or the setup command from the plugin if there is no ${code2("speclayer.json")}), then ${code2("npx spec-layer skill --install")} again to list the components and token collections here.`,
       ""
     );
     return lines;
   }
   lines.push(
-    `Library ${code(pull.libraryId)}, published ${pull.publishedAt}${pull.pluginVersion ? ` by plugin ${pull.pluginVersion}` : ""}. Run ${code("npx spec-layer status")} first; exit code 2 means a newer publish exists and ${code("npx spec-layer pull")} fetches it.`,
+    `Library ${code2(pull.libraryId)}, published ${pull.publishedAt}${pull.pluginVersion ? ` by plugin ${pull.pluginVersion}` : ""}. Run ${code2("npx spec-layer status")} first; exit code 2 means a newer publish exists and ${code2("npx spec-layer pull")} fetches it.`,
     ""
   );
-  lines.push(`- ${code(`${outDir}/manifest.json`)}: every artifact with its content hash and file path.`);
-  lines.push(`- ${code(`${outDir}/bundle.json`)}: the whole published library, including the canonical v5 JSON of every artifact.`);
+  lines.push(`- ${code2(`${outDir}/manifest.json`)}: every artifact with its content hash and file path.`);
+  lines.push(`- ${code2(`${outDir}/bundle.json`)}: the whole published library, including the canonical v5 JSON of every artifact.`);
   if (pull.foundation) {
     if (pull.foundation.written) {
-      lines.push(`- ${code(`${outDir}/tokens/`)}: the Foundation as Design Tokens Format Module 2025.10 files.`);
-      lines.push(`  - ${code("resolver.json")}: sets, modifiers, and resolution order. Start here.`);
-      lines.push(`  - ${code("spec-layer.meta.json")}: Figma ids, scopes, publication, and ${code("code_syntax")} per DTCG path.`);
-      lines.push(`  - ${code("report.json")}: what the format could not express, with reasons. Never fill these gaps with a guess.`);
-      for (const f of pull.foundation.tokenFiles) lines.push(`  - ${code(f)}`);
+      lines.push(`- ${code2(`${outDir}/tokens/`)}: the Foundation as Design Tokens Format Module 2025.10 files.`);
+      lines.push(`  - ${code2("resolver.json")}: sets, modifiers, and resolution order. Start here.`);
+      lines.push(`  - ${code2("spec-layer.meta.json")}: Figma ids, scopes, publication, and ${code2("code_syntax")} per DTCG path.`);
+      lines.push(`  - ${code2("report.json")}: what the format could not express, with reasons. Never fill these gaps with a guess.`);
+      for (const f of pull.foundation.tokenFiles) lines.push(`  - ${code2(f)}`);
     } else {
-      lines.push(`- Foundation: present in the library but not written, because the selection excludes it. ${code("spec-layer show foundation")} still prints it.`);
+      lines.push(`- Foundation: present in the library but not written, because the selection excludes it. ${code2("spec-layer show foundation")} still prints it.`);
     }
   } else {
     lines.push("- This library has no Foundation, so there is no tokens/ directory.");
   }
-  lines.push(`- ${code(`${pull.componentSpecsDir}/`)}: one YAML per component.`);
+  lines.push(`- ${code2(`${pull.componentSpecsDir}/`)}: one ${pull.componentSpecsFormat === "md" ? "Markdown page" : "YAML"} per component.`);
   for (const o of pull.outputs) {
-    lines.push(o.written ? `- ${code(`${o.path}/`)}: ${o.platform}/${o.format} token files, ${o.case} names: ${o.files.join(", ")}. Non-default modes are under ${code(o.modeSelector)}, each in its own file. Names and provenance: ${code(`${outDir}/outputs/${o.platform}-${o.format}.map.json`)}; what it could not express: ${code(`${outDir}/outputs/${o.platform}-${o.format}.report.json`)}.` : o.indexMissing ? `- ${code(`${o.path}/`)}: ${o.platform}/${o.format} token files, but ${code("index.css")} is missing; run ${code("npx spec-layer pull")} to restore the directory.` : `- ${code(`${o.path}/`)}: ${o.platform}/${o.format} token files, configured but not written by the last pull (the Foundation was not written). Nothing is on disk at that path from Spec Layer.`);
+    lines.push(o.written ? `- ${code2(`${o.path}/`)}: ${o.platform}/${o.format} token files, ${o.case} names: ${o.files.join(", ")}. Non-default modes are under ${code2(o.modeSelector)}, each in its own file. Names and provenance: ${code2(`${outDir}/outputs/${o.platform}-${o.format}.map.json`)}; what it could not express: ${code2(`${outDir}/outputs/${o.platform}-${o.format}.report.json`)}.` : o.indexMissing ? `- ${code2(`${o.path}/`)}: ${o.platform}/${o.format} token files, but ${code2("index.css")} is missing; run ${code2("npx spec-layer pull")} to restore the directory.` : `- ${code2(`${o.path}/`)}: ${o.platform}/${o.format} token files, configured but not written by the last pull (the Foundation was not written). Nothing is on disk at that path from Spec Layer.`);
   }
   lines.push("");
   if (pull.foundation && (pull.foundation.sets.length || pull.foundation.modifiers.length)) {
     lines.push("### Token collections", "");
-    for (const set of pull.foundation.sets) lines.push(`- ${code(set)}: one mode, always applied.`);
+    for (const set of pull.foundation.sets) lines.push(`- ${code2(set)}: one mode, always applied.`);
     for (const m of pull.foundation.modifiers) {
-      lines.push(`- ${code(m.name)}: modes ${m.contexts.map(code).join(", ")}${m.default ? `, default ${code(m.default)}` : ""}.`);
+      lines.push(`- ${code2(m.name)}: modes ${m.contexts.map(code2).join(", ")}${m.default ? `, default ${code2(m.default)}` : ""}.`);
     }
     lines.push("");
     const counts = Object.entries(pull.foundation.reportCounts);
     if (counts.length) {
       lines.push(
-        `${code("report.json")} lists ${counts.map(([c, n]) => `${n} ${code(c)}`).join(", ")}. Read it before assuming a token is missing.`,
+        `${code2("report.json")} lists ${counts.map(([c, n]) => `${n} ${code2(c)}`).join(", ")}. Read it before assuming a token is missing.`,
         ""
       );
     }
@@ -4442,7 +6710,7 @@ function pullSection(input) {
     lines.push("The library documents no components.", "");
   } else {
     for (const c of pull.components) {
-      lines.push(c.path ? `- ${c.name}: ${code(c.path)}` : `- ${c.name}: not written (excluded by the selection). ${code(`spec-layer show component "${c.name}"`)} prints it.`);
+      lines.push(c.path ? `- ${c.name}: ${code2(c.path)}` : `- ${c.name}: not written (excluded by the selection). ${code2(`spec-layer show component "${c.name}"`)} prints it.`);
     }
     lines.push("");
   }
@@ -4453,42 +6721,43 @@ function commandsSection() {
   const cell = (s) => s.replace(/\|/g, "\\|");
   lines.push("| Command | What it does | When | Network | Key | Writes |", "|---|---|---|---|---|---|");
   for (const t of TOOLS) {
-    lines.push(`| ${code(cell(t.usage))} | ${cell(t.summary)} | ${cell(t.when)} | ${t.network ? "yes" : "no"} | ${t.needsKey ? "required" : "no"} | ${t.writes.length ? t.writes.map((w) => code(cell(w))).join(", ") : "nothing"} |`);
+    lines.push(`| ${code2(cell(t.usage))} | ${cell(t.summary)} | ${cell(t.when)} | ${t.network ? "yes" : "no"} | ${t.needsKey ? "required" : "no"} | ${t.writes.length ? t.writes.map((w) => code2(cell(w))).join(", ") : "nothing"} |`);
   }
   lines.push("");
   lines.push("Exit codes:", "");
   for (const t of TOOLS) {
-    lines.push(`- ${code(t.name)}: ${Object.entries(t.exits).map(([c, m]) => `${c} = ${m}`).join("; ")}.`);
+    lines.push(`- ${code2(t.name)}: ${Object.entries(t.exits).map(([c, m]) => `${c} = ${m}`).join("; ")}.`);
   }
   lines.push("");
-  for (const f of GLOBAL_FLAGS) lines.push(`- ${code(f.flag)}: ${f.summary}`);
+  for (const f of GLOBAL_FLAGS) lines.push(`- ${code2(f.flag)}: ${f.summary}`);
   lines.push("", KEY_RESOLUTION, "");
-  lines.push(`Run ${code("npx --yes spec-layer <command>")} in an unattended session so npx does not stop to ask before downloading the package. ${code("spec-layer tools --json")} prints this table for machines.`, "");
+  lines.push(`Run ${code2("npx --yes spec-layer <command>")} in an unattended session so npx does not stop to ask before downloading the package. ${code2("spec-layer tools --json")} prints this table for machines.`, "");
   return lines;
 }
 function buildSkillGuide(input) {
   const { outDir } = input;
   const lines = [];
+  const markdown = (input.pull?.componentSpecsFormat ?? input.config?.componentSpecsFormat ?? DEFAULT_COMPONENT_FORMAT) === "md";
   lines.push("# Spec Layer: design-system context for this repository", "");
   lines.push(
-    `The Spec Layer Figma plugin publishes a design system's components, variables, and styles as data. The ${code("spec-layer")} CLI (version ${input.version}) pulls that data into this repository under ${code(outDir + "/")}. Everything in those files is extracted deterministically from Figma and validated against a published schema; no model wrote any of it. Treat it as the source of truth for what the design system contains, and treat anything it does not state as unknown rather than as something to infer.`,
+    `The Spec Layer Figma plugin publishes a design system's components, variables, and styles as data. The ${code2("spec-layer")} CLI (version ${input.version}) pulls that data into this repository under ${code2(outDir + "/")}. Everything in those files is extracted deterministically from Figma and validated against a published schema, ` + (markdown ? `with two exceptions that can carry model-written prose: a section of a component page that says it was written by AI, or a component's or the foundation's ${code2("guidelines")} block, marked ${code2("origin: generated")}; and a token group's ${code2("$description")}, which carries no marker ` : `with two exceptions that can carry model-written prose: a component's or the foundation's ${code2("guidelines")} block, marked ${code2("origin: generated")}, and a token group's ${code2("$description")}, which carries no marker `) + "and can be model-written even though it looks like an ordinary field. Treat the rest as the source of truth for what the design system contains, and treat anything it does not state as unknown rather than as something to infer.",
     ""
   );
   const componentSpecsDir = input.pull?.componentSpecsDir ?? input.config?.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR;
   lines.push("## How to use it", "");
-  lines.push(`1. Run ${code("npx spec-layer status")}. Exit 0 means the local copy is current; exit 2 means run ${code("npx spec-layer pull")} first.`);
-  lines.push(`2. Building or changing a component: read its YAML under ${code(`${componentSpecsDir}/`)}, or ${code("npx spec-layer show component NAME")}. ${code("api")} gives variants, states, booleans, and slots; ${code("anatomy")} names the parts; ${code("references.bindings")} says which token each part's property uses and under which ${code("when")} conditions; ${code("unbound")} lists values that are hardcoded in Figma.`);
-  lines.push(`3. Working with colors, spacing, type, or effects: start at ${code(`${outDir}/tokens/resolver.json`)}, load the set and mode files it names, and look up ${code("code_syntax")} in ${code("spec-layer.meta.json")} for the name the designer declared for your platform.`);
+  lines.push(`1. Run ${code2("npx spec-layer status")}. Exit 0 means the local copy is current; exit 2 means run ${code2("npx spec-layer pull")} first.`);
+  lines.push(markdown ? `2. Building or changing a component: read its page under ${code2(`${componentSpecsDir}/`)}, or ${code2("npx spec-layer show component NAME")}. **Properties** gives variants, states, booleans, and slots; **Anatomy** names the parts; **Token bindings** says which token each part's property uses and under which **When** conditions; **Unbound values** lists values that are hardcoded in Figma.` : `2. Building or changing a component: read its YAML under ${code2(`${componentSpecsDir}/`)}, or ${code2("npx spec-layer show component NAME")}. ${code2("api")} gives variants, states, booleans, and slots; ${code2("anatomy")} names the parts; ${code2("references.bindings")} says which token each part's property uses and under which ${code2("when")} conditions; ${code2("unbound")} lists values that are hardcoded in Figma.`);
+  lines.push(`3. Working with colors, spacing, type, or effects: start at ${code2(`${outDir}/tokens/resolver.json`)}, load the set and mode files it names, and look up ${code2("code_syntax")} in ${code2("spec-layer.meta.json")} for the name the designer declared for your platform.`);
   lines.push(`4. Reference tokens by name in code; never paste a resolved value where a token exists. A value the design system does not define is not a token: say so in your change rather than adding one.`);
-  lines.push(`5. An ${code("unbound")} entry is design debt reported from Figma. Do not silently promote it to a token; keep the literal and note that Figma has no binding for it.`);
+  lines.push(markdown ? "5. A row under **Unbound values** is design debt reported from Figma. Do not silently promote it to a token; keep the literal and note that Figma has no binding for it." : `5. An ${code2("unbound")} entry is design debt reported from Figma. Do not silently promote it to a token; keep the literal and note that Figma has no binding for it.`);
   const writtenOutputs = input.pull?.outputs.filter((o) => o.written) ?? [];
-  const outputNote = writtenOutputs.length ? ` Never edit ${writtenOutputs.map((o) => code(`${o.path}/`)).join(", ")} either: pull replaces or removes files there.` : "";
-  lines.push(`6. Never edit files under ${code(outDir + "/")} or ${code(componentSpecsDir + "/")}: the next pull replaces or removes them.${outputNote} Configuration lives in ${code("speclayer.json")}. Never commit ${code(CREDENTIALS_NAME)}, and never print or copy the pull key.`);
+  const outputNote = writtenOutputs.length ? ` Never edit ${writtenOutputs.map((o) => code2(`${o.path}/`)).join(", ")} either: pull replaces or removes files there.` : "";
+  lines.push(`6. Never edit files under ${code2(outDir + "/")} or ${code2(componentSpecsDir + "/")}: the next pull replaces or removes them.${outputNote} Configuration lives in ${code2("speclayer.json")}. Never commit ${code2(CREDENTIALS_NAME)}, and never print or copy the pull key.`);
   lines.push("");
   lines.push(...pullSection(input));
   lines.push(...stackSection(input));
   lines.push(...commandsSection());
-  lines.push(`Generated by ${code("spec-layer skill")}. Re-run ${code("npx spec-layer skill --install")} after a pull that adds components, after changing ${code("outputs")} or ${code("componentSpecsDir")}, or when the codebase changes stack; the file is replaced, not appended.`);
+  lines.push(`Generated by ${code2("spec-layer skill")}. Re-run ${code2("npx spec-layer skill --install")} after a pull that adds components, after changing ${code2("outputs")} or ${code2("componentSpecsDir")}, or when the codebase changes stack; the file is replaced, not appended.`);
   return `${lines.join("\n")}
 `;
 }
@@ -4561,19 +6830,27 @@ ${BLOCK_END}
   const sep2 = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
   return `${existing}${sep2}${block}`;
 }
+var SNAPSHOT_DIRS = ["components", "tokens"];
+function staleSnapshotDirs(cwd, target) {
+  if (target.host !== "claude") return [];
+  const dir = dirname3(target.path);
+  return SNAPSHOT_DIRS.map((name) => `${dir}/${name}`).filter((rel) => existsSync7(join7(cwd, rel)));
+}
 function installSkill(cwd, host, guide) {
   const target = installTarget(host);
   const abs = join7(cwd, target.path);
   const existing = existsSync7(abs) ? readFileSync8(abs, "utf8") : null;
+  const staleSnapshot = staleSnapshotDirs(cwd, target);
   const next = target.mode === "file" ? renderForHost(host, guide) : upsertBlock(existing, renderForHost(host, guide));
-  if (existing === next) return { path: target.path, result: "unchanged" };
+  if (existing === next) return { path: target.path, result: "unchanged", staleSnapshot };
   mkdirSync3(dirname3(abs), { recursive: true });
   writeFileSync6(abs, next);
-  return { path: target.path, result: existing === null ? "created" : "updated" };
+  return { path: target.path, result: existing === null ? "created" : "updated", staleSnapshot };
 }
 
 // src/commands.ts
 var NO_LOCAL_PULL = "No local pull found. Run spec-layer pull.";
+var FORMAT_NAME = { yaml: "YAML", md: "Markdown" };
 function manifestReader() {
   const cache = /* @__PURE__ */ new Map();
   return (outDir) => {
@@ -4584,7 +6861,7 @@ function manifestReader() {
 function sameOutput(a, b) {
   const selectionKey = (s) => JSON.stringify([s.foundation, s.components === null ? null : [...new Set(s.components.map(slugify))].sort()]);
   const key = (v) => JSON.stringify(sortKeys(v ?? {}));
-  return selectionKey(a.selection) === selectionKey(b.selection) && key(a.dtcg) === key(b.dtcg) && key(a.outputs ?? []) === key(b.outputs ?? []) && (a.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR) === (b.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR);
+  return selectionKey(a.selection) === selectionKey(b.selection) && key(a.dtcg) === key(b.dtcg) && key(a.outputs ?? []) === key(b.outputs ?? []) && (a.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR) === (b.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR) && (a.componentSpecsFormat ?? DEFAULT_COMPONENT_FORMAT) === (b.componentSpecsFormat ?? DEFAULT_COMPONENT_FORMAT);
 }
 function sortKeys(value) {
   if (Array.isArray(value)) return value.map(sortKeys);
@@ -4605,6 +6882,13 @@ function platformsFromFlags(flags, io2) {
   }
   return out;
 }
+function componentFormatFromFlags(flags, io2) {
+  const value = flags["component-format"];
+  if (value === void 0) return void 0;
+  if (isComponentFormat(value)) return value;
+  io2.err(`--component-format takes ${COMPONENT_FORMATS.join(" or ")}, not "${value}".`);
+  return null;
+}
 function resolvePlatforms(cwd, fromFlags, config) {
   if (fromFlags) return { platforms: fromFlags, source: "flag" };
   if (config?.platforms && config.platforms.length > 0) return { platforms: config.platforms, source: "config" };
@@ -4637,6 +6921,8 @@ function runInit(cwd, flags, io2) {
   }
   const fromFlags = platformsFromFlags(flags, io2);
   if (fromFlags === null) return 1;
+  const format = componentFormatFromFlags(flags, io2);
+  if (format === null) return 1;
   const { platforms, source } = resolvePlatforms(cwd, fromFlags, null);
   const outputs = defaultOutputs(platforms);
   const outDir = flags.out ?? DEFAULT_OUT_DIR;
@@ -4644,6 +6930,7 @@ function runInit(cwd, flags, io2) {
     libraryId: flags.id,
     outDir,
     componentSpecsDir: DEFAULT_COMPONENT_SPECS_DIR,
+    ...format ? { componentSpecsFormat: format } : {},
     ...include ? { include } : {},
     ...platforms.length > 0 ? { platforms } : {},
     ...outputs.length > 0 ? { outputs } : {}
@@ -4715,16 +7002,20 @@ async function runSetup(cwd, flags, env, io2, fetcher) {
   }
   const fromFlags = platformsFromFlags(flags, io2);
   if (fromFlags === null) return 1;
+  const format = componentFormatFromFlags(flags, io2);
+  if (format === null) return 1;
   const outDir = flags.out ?? existing?.outDir ?? DEFAULT_OUT_DIR;
   const componentSpecsDir = existing?.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR;
   const keptInclude = include ?? existing?.include ?? null;
   const keptDtcg = existing?.dtcg ?? null;
+  const keptFormat = format ?? existing?.componentSpecsFormat ?? null;
   const { platforms } = resolvePlatforms(cwd, fromFlags, existing);
   const outputs = withDefaults(existing?.outputs ?? [], platforms);
   writeConfig(cwd, {
     libraryId: flags.id,
     outDir,
     componentSpecsDir,
+    ...keptFormat ? { componentSpecsFormat: keptFormat } : {},
     ...keptInclude ? { include: keptInclude } : {},
     ...keptDtcg ? { dtcg: keptDtcg } : {},
     ...platforms.length > 0 ? { platforms } : {},
@@ -4768,8 +7059,8 @@ git rm --cached ${ignored.line}`);
   }
   const { replaced } = writeCredentials(cwd, { libraryId: flags.id, key });
   io2.out(replaced ? `Replaced the stored key in ${CREDENTIALS_NAME}.` : `Stored the pull key in ${CREDENTIALS_NAME}.`);
-  const code2 = await runPull(cwd, { ...flags, key }, env, io2, fetcher);
-  if (code2 !== 0) return code2;
+  const code3 = await runPull(cwd, { ...flags, key }, env, io2, fetcher);
+  if (code3 !== 0) return code3;
   const hosts = detectRepo(cwd).agents;
   io2.out("");
   io2.out("Next step for a coding agent: npx spec-layer skill --install");
@@ -4831,6 +7122,9 @@ function printReportSummary(cwd, outDir, outputs, io2) {
   }
   return errors;
 }
+function publishedPhrase(version, publishedAt) {
+  return version ? `(v${version}, published ${publishedAt})` : `(published ${publishedAt})`;
+}
 async function runPull(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
   const opts = resolved(cwd, flags, env, io2, manifestAt);
@@ -4844,6 +7138,9 @@ async function runPull(cwd, flags, env, io2, fetcher) {
   }
   const fromFlags = platformsFromFlags(flags, io2);
   if (fromFlags === null) return 1;
+  const flagFormat = componentFormatFromFlags(flags, io2);
+  if (flagFormat === null) return 1;
+  const componentSpecsFormat = flagFormat ?? opts.componentSpecsFormat ?? DEFAULT_COMPONENT_FORMAT;
   const { platforms, source } = resolvePlatforms(cwd, fromFlags, opts);
   const outputs = outputsForRun(fromFlags, opts, platforms);
   const manifest = manifestAt(join8(cwd, opts.outDir));
@@ -4851,8 +7148,14 @@ async function runPull(cwd, flags, env, io2, fetcher) {
   const willWriteFoundation = selection.foundation && foundationOnDisk;
   const briefsOnDisk = (manifest?.artifacts ?? []).filter((a) => a.kind === "component" && a.path !== null).every((a) => existsSync8(resolve5(cwd, a.path)));
   const etag = manifest && manifest.cliVersion === cliVersion() && sameOutput(
-    { selection: manifest.selection ?? DEFAULT_SELECTION, dtcg: manifest.dtcg, outputs: manifest.outputs, componentSpecsDir: manifest.componentSpecsDir },
-    { selection, dtcg: opts.dtcg, outputs, componentSpecsDir: opts.componentSpecsDir }
+    {
+      selection: manifest.selection ?? DEFAULT_SELECTION,
+      dtcg: manifest.dtcg,
+      outputs: manifest.outputs,
+      componentSpecsDir: manifest.componentSpecsDir,
+      componentSpecsFormat: manifest.componentSpecsFormat
+    },
+    { selection, dtcg: opts.dtcg, outputs, componentSpecsDir: opts.componentSpecsDir, componentSpecsFormat }
   ) && briefsOnDisk && (!willWriteFoundation || foundationFilesOnDisk(cwd, opts.outDir)) && (!willWriteFoundation || outputs.every((o) => outputFilesOnDisk(cwd, opts.outDir, o))) ? manifest.bundleHash : void 0;
   const result = await fetchBundle({
     api: opts.api,
@@ -4866,7 +7169,7 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     return 1;
   }
   if (result.kind === "not_modified") {
-    io2.out(`Already up to date (published ${manifest?.publishedAt ?? "unknown"}).`);
+    io2.out(`Already up to date ${publishedPhrase(result.version ?? manifest?.version, manifest?.publishedAt ?? "unknown")}.`);
     const cachedErrors = printReportSummary(cwd, opts.outDir, outputs, io2);
     if (flags.strict && cachedErrors > 0) return 1;
     return 0;
@@ -4886,16 +7189,18 @@ async function runPull(cwd, flags, env, io2, fetcher) {
       libraryId: opts.libraryId,
       publishedAt: result.publishedAt,
       bundleHash: result.bundleHash,
+      version: result.version,
       dtcg: opts.dtcg,
       platforms,
       outputs,
-      componentSpecsDir: opts.componentSpecsDir
+      componentSpecsDir: opts.componentSpecsDir,
+      componentSpecsFormat
     });
     written = writeResult.written;
     componentSpecs = writeResult.componentSpecs;
     outputResults = writeResult.outputs;
     io2.out(
-      `Pulled ${bundle.fileName ?? opts.libraryId}: ${describePull(bundle, selection, selected)} (published ${result.publishedAt}).`
+      `Pulled ${bundle.fileName ?? opts.libraryId}: ${describePull(bundle, selection, selected)} ${publishedPhrase(result.version, result.publishedAt)}.`
     );
   } catch (err) {
     io2.err(errorText(err));
@@ -4903,7 +7208,10 @@ async function runPull(cwd, flags, env, io2, fetcher) {
   }
   const count = (n) => `${n} file${n === 1 ? "" : "s"}`;
   io2.out(`Wrote ${written.length} files under ${opts.outDir}/.`);
-  if (componentSpecs.files.length > 0) io2.out(`Wrote ${componentSpecs.path}/ (${count(componentSpecs.files.length)}).`);
+  if (componentSpecs.files.length > 0) {
+    const n = componentSpecs.files.length;
+    io2.out(`Wrote ${componentSpecs.path}/ (${n} ${FORMAT_NAME[componentSpecsFormat]} file${n === 1 ? "" : "s"}).`);
+  }
   for (const r of outputResults) {
     const o = outputs.find((x) => x.path === r.path);
     if (o) io2.out(`Wrote ${r.path}/ (${count(r.files.length)}, ${o.platform}/${o.format}, ${o.case} names).`);
@@ -4948,10 +7256,10 @@ async function runStatus(cwd, flags, env, io2, fetcher) {
     return 1;
   }
   if (result.kind === "not_modified") {
-    io2.out(`Up to date (published ${manifest.publishedAt}).`);
+    io2.out(`Up to date ${publishedPhrase(result.version ?? manifest.version, manifest.publishedAt)}.`);
     return 0;
   }
-  io2.out(`Behind: remote published ${result.publishedAt}. Run spec-layer pull.`);
+  io2.out(result.version ? `Behind: remote is v${result.version}, published ${result.publishedAt}. Run spec-layer pull.` : `Behind: remote published ${result.publishedAt}. Run spec-layer pull.`);
   return 2;
 }
 function runList(cwd, flags, io2) {
@@ -4962,7 +7270,7 @@ function runList(cwd, flags, io2) {
     io2.err(NO_LOCAL_PULL);
     return 1;
   }
-  io2.out(`Library ${manifest.libraryId}, published ${manifest.publishedAt}.`);
+  io2.out(manifest.version ? `Library ${manifest.libraryId}, v${manifest.version}, published ${manifest.publishedAt}.` : `Library ${manifest.libraryId}, published ${manifest.publishedAt}.`);
   const rows = manifest.artifacts.map((a) => [a.kind, a.name, a.path ?? "not written", a.contentHash]);
   const widths = [0, 1, 2].map((i) => Math.max(...rows.map((r) => r[i].length)));
   for (const row of rows) {
@@ -4983,6 +7291,12 @@ function runShow(cwd, flags, args, io2) {
     io2.err(SHOW_USAGE);
     return 1;
   }
+  const flagFormat = componentFormatFromFlags(flags, io2);
+  if (flagFormat === null) return 1;
+  if (wantsFoundation && flagFormat !== void 0) {
+    io2.err("--component-format applies to components. The Foundation prints as its DTCG document.");
+    return 1;
+  }
   const outDir = resolvedOutDir(cwd, flags, io2);
   if (!outDir) return 1;
   let bundle;
@@ -4997,6 +7311,7 @@ function runShow(cwd, flags, args, io2) {
     return 1;
   }
   let entry2;
+  let component = null;
   if (wantsFoundation) {
     if (!bundle.foundation) {
       io2.err("This library has no Foundation. Run spec-layer list to see what it holds.");
@@ -5016,9 +7331,33 @@ Available: ${available || "none"}.`);
       return 1;
     }
     entry2 = matches[0];
+    component = matches[0];
+  }
+  if (flags.canonical) {
+    io2.write(`${JSON.stringify(entry2.artifact, null, 2)}
+`);
+    return 0;
+  }
+  if (component) {
+    let configFormat;
+    try {
+      configFormat = readConfig(cwd)?.componentSpecsFormat;
+    } catch (err) {
+      io2.err(errorText(err));
+      return 1;
+    }
+    const format = flagFormat ?? configFormat ?? readManifest(outDir)?.componentSpecsFormat ?? DEFAULT_COMPONENT_FORMAT;
+    if (format === "md") {
+      try {
+        io2.write(componentMarkdownPage(component));
+      } catch (err) {
+        io2.err(errorText(err));
+        return 1;
+      }
+      return 0;
+    }
   }
-  io2.write(flags.canonical ? `${JSON.stringify(entry2.artifact, null, 2)}
-` : entry2.ai);
+  io2.write(entry2.ai);
   return 0;
 }
 function runTools(flags, io2) {
@@ -5090,6 +7429,11 @@ function runSkill(cwd, flags, io2) {
     }
     const verb = outcome.result === "created" ? "Wrote" : outcome.result === "updated" ? "Updated" : "Unchanged:";
     io2.out(`${verb} ${outcome.path} (${host}, ${chosen}).`);
+    if (outcome.staleSnapshot.length > 0) {
+      io2.out(
+        `A downloaded snapshot is still in ${outcome.staleSnapshot.join(" and ")}. The guide above supersedes it, and those folders can be deleted.`
+      );
+    }
   }
   if (!input.pull) io2.out(`No local pull yet, so the guide lists no components. Run spec-layer pull, then spec-layer skill --install again.`);
   if (input.platformSource === "none") io2.out(`No target platform detected. Pass --platform ${PLATFORMS.join("|")} to write platform-specific token advice.`);
@@ -5100,17 +7444,17 @@ function runSkill(cwd, flags, io2) {
 var USAGE = `spec-layer <command>
 
 Commands:
-  setup   --id lib_... --key sl_... [--out DIR] [selection] [--platform P]...
+  setup   --id lib_... --key sl_... [--out DIR] [selection] [--platform P]... [--component-format F]
                                                  store the key, then pull
-  init    --id lib_... [--out DIR] [selection] [--platform P]...
+  init    --id lib_... [--out DIR] [selection] [--platform P]... [--component-format F]
                                                  write speclayer.json
-  pull    [--id lib_...] [--key sl_...] [selection] [--platform P]... [--strict]
+  pull    [--id lib_...] [--key sl_...] [selection] [--platform P]... [--component-format F] [--strict]
                                                  fetch the library into DIR (default .speclayer); the foundation lands as DTCG under DIR/tokens/;
                                                  --strict exits 1 when tokens/report.json or an outputs/*.report.json holds an error-severity entry, even on a cached pull (default exit stays 0)
   status  [--id lib_...] [--key sl_...]          check freshness; exits 2 when behind
   list                                           list every artifact in the last pull
-  show    foundation | component NAME [--canonical]
-                                                 print one artifact (foundation: the DTCG document; component: its AI YAML; --canonical for JSON)
+  show    foundation | component NAME [--component-format F] [--canonical]
+                                                 print one artifact (foundation: the DTCG document; component: its AI YAML or Markdown; --canonical for JSON)
   tools   [--json]                               list every command with what it reaches and writes
   skill   [--install] [--agent HOST]... [--platform P]... [--json]
                                                  print a guide for a coding agent, adapted to this repo and the last pull;
@@ -5123,6 +7467,7 @@ Selection (setup, pull and init; flags replace the include block in speclayer.js
 Options:
   --api URL   override the API origin (default https://api.spec-layer.com)
   --platform web|ios|android|flutter   the target this repo builds for (repeatable); applies to setup, init, pull, and skill; setup and init store it, pull uses it for the run
+  --component-format yaml|md   how component-specs/ is written and show prints a component (default yaml); setup and init store it, pull and show use it for the run
 The pull key comes from --key, SPEC_LAYER_KEY, or speclayer.local.json written by setup.`;
 var io = {
   out: (l) => console.log(l),
@@ -5149,7 +7494,8 @@ async function main() {
         install: { type: "boolean" },
         strict: { type: "boolean" },
         agent: { type: "string", multiple: true },
-        platform: { type: "string", multiple: true }
+        platform: { type: "string", multiple: true },
+        "component-format": { type: "string" }
       }
     }));
   } catch {