spec-layer 0.8.2 → 0.9.0

package/README.md

@@ -64,7 +64,7 @@ Module 2025.10 files, rather than `ai/foundation.yaml`, needs 0.4.0 or later.
 `componentSpecsDir`, cwd-relative manifest paths, and the `tokens/` directory
 need 0.7.0 or later. The `census` and `config_hash` blocks inside
 `resolver.json`, and the `transform` and `resolved` fields in
-`spec-layer.meta.json`, need 0.8.0 or later; an earlier version pulls the same
+`spec-layer.meta.json`, need 0.8.2 or later; an earlier version pulls the same
 files without those fields.
 
 ## Commands

package/dist/cli.js

@@ -559,7 +559,7 @@ var require_sha256 = __commonJS({
 import { parseArgs } from "node:util";
 
 // src/commands.ts
-import { existsSync as existsSync8 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync9 } from "node:fs";
 import { join as join8, resolve as resolve5 } from "node:path";
 
 // ../extractor/src/statesMatrix.ts
@@ -814,6 +814,26 @@ var SUPPORTED_TOKEN_TYPES = [
 var SUPPORTED_VALUE_KINDS = ["literal", "alias", "missing"];
 var SUPPORTED_DURATION_UNITS = ["ms", "s"];
 
+// ../extractor/src/v5/units.ts
+var UNIT_BY_SCOPE = {
+  WIDTH_HEIGHT: "px",
+  CORNER_RADIUS: "px",
+  GAP: "px",
+  FONT_SIZE: "px",
+  STROKE_FLOAT: "px",
+  PARAGRAPH_SPACING: "px",
+  PARAGRAPH_INDENT: "px",
+  EFFECT_FLOAT: "px",
+  FONT_WEIGHT: "number",
+  OPACITY: "number"
+};
+function scopesStateUnit(scopes) {
+  return (scopes ?? []).some((s) => UNIT_BY_SCOPE[s] !== void 0);
+}
+function scopesStateNumber(scopes) {
+  return (scopes ?? []).some((s) => UNIT_BY_SCOPE[s] === "number");
+}
+
 // ../extractor/src/v5/canonical.ts
 var import_js_sha2562 = __toESM(require_sha256(), 1);
 var SCHEMA_VERSION = "5.1.0";
@@ -1325,6 +1345,25 @@ function validateLevel1(artifact) {
   }
 }
 
+// ../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/dtcg.ts
 var import_js_sha2563 = __toESM(require_sha256(), 1);
 function dtcgSegments(name) {
@@ -1344,6 +1383,9 @@ function dtcgSegments(name) {
   }
   return { segments, notes };
 }
+function dtcgPathOf(collectionName, tokenName) {
+  return [...dtcgSegments(collectionName).segments, ...dtcgSegments(tokenName).segments].join(".");
+}
 function trimDashes(s) {
   let start = 0;
   let end = s.length;
@@ -1514,25 +1556,73 @@ function unitOverrideFor(p, token, collection) {
   }
   return void 0;
 }
-var STATED_NUMBER_SCOPES = ["FONT_WEIGHT", "OPACITY"];
-function projectedLiteral(p, token, resolved2, onOverrideConflict) {
+function reportPathOf(p, token) {
+  const path = p.pathById.get(token.id) ?? p.segmentsById.get(token.id)?.join(".") ?? token.name;
+  return p.collidedIds.has(token.id) ? `${path} [${token.id}]` : path;
+}
+function ownerFor(p, token) {
+  const path = reportPathOf(p, token);
+  return {
+    overrideConflict: (override) => {
+      reportOnce(p, {
+        code: "unit_override_conflicts_with_scope",
+        severity: "warning",
+        path,
+        message: "A unit override names this token but its scopes state a unitless number; the override was ignored.",
+        details: { id: token.id, override, scopes: [...token.scopes] }
+      });
+    },
+    // Reported without a mode, like the override conflict above: the evidence
+    // is a fact about the token, not about one of its values, so a token in
+    // three modes earns one entry rather than three.
+    derivedUnit: (evidence) => {
+      reportOnce(p, {
+        code: "unit_derived_from_usage",
+        severity: "info",
+        path,
+        // "its own variable", not "no scope": for `via: 'alias-scope'` a scope
+        // is exactly what stated the unit, and this same sentence goes on to
+        // name it. What is true of both kinds of evidence is that the token's
+        // OWN variable states nothing. The CSS header that points a reader at
+        // this entry says it the same way, for the same reason.
+        message: `This token's own variable states no unit, so ${evidence.unit} was taken from how the library uses it: ${evidence.source} ${evidence.via === "binding" ? "binds it to" : "is scoped"} ${evidence.reason}.`,
+        details: {
+          id: token.id,
+          unit: evidence.unit,
+          via: evidence.via,
+          source: evidence.source,
+          reason: evidence.reason
+        }
+      });
+    }
+  };
+}
+function projectedLiteral(p, token, resolved2, owner) {
   const collection = p.collectionById.get(token.collection_id);
   const override = collection ? unitOverrideFor(p, token, collection) : void 0;
   let literal = resolved2;
   let overrode = false;
+  let derived;
   if (override !== void 0 && literal.type === "number") {
-    if (token.scopes.some((s) => STATED_NUMBER_SCOPES.includes(s))) onOverrideConflict?.(override);
+    if (scopesStateNumber(token.scopes)) owner?.overrideConflict(override);
     else {
       literal = { type: "dimension", number: literal.value, unit: override };
       overrode = true;
     }
+  } else if (literal.type === "number" && !scopesStateUnit(token.scopes)) {
+    const evidence = p.derivedUnits.get(token.id);
+    if (evidence !== void 0) {
+      literal = { type: "dimension", number: literal.value, unit: evidence.unit };
+      derived = evidence;
+      owner?.derivedUnit(evidence);
+    }
   }
   const converted2 = dtcgLiteral(literal, token.scopes, p.options.values);
   if ("omit" in converted2) return { converted: converted2, transform: null };
-  return {
-    converted: converted2,
-    transform: overrode ? "number-unit-override" : literalTransform(literal, token.scopes)
-  };
+  let transform = literalTransform(literal, token.scopes);
+  if (overrode) transform = "number-unit-override";
+  else if (derived !== void 0) transform = "number-unit-usage";
+  return { converted: converted2, transform };
 }
 function literalTransform(value, scopes) {
   switch (value.type) {
@@ -1559,7 +1649,24 @@ function literalTransform(value, scopes) {
 }
 function aliasLeafType(p, token, chain, resolved2) {
   const terminal = chain.length > 0 ? p.tokenById.get(chain[chain.length - 1].token_id) : void 0;
-  return projectedLiteral(p, terminal ?? token, resolved2).converted;
+  const subject = terminal ?? token;
+  return projectedLiteral(p, subject, resolved2, ownerFor(p, subject)).converted;
+}
+function terminalOwnType(p, chain) {
+  const hop = chain.length > 0 ? chain[chain.length - 1] : void 0;
+  const terminal = hop ? p.tokenById.get(hop.token_id) : void 0;
+  const value = terminal && hop ? terminal.values[hop.mode_id] : void 0;
+  if (!terminal || !value || value.kind !== "literal") return void 0;
+  return projectedLiteral(p, terminal, value.value, ownerFor(p, terminal)).converted;
+}
+function reportAliasTypeMismatch(p, path, targetPath, ownType, targetType) {
+  reportOnce(p, {
+    code: "alias_type_mismatch",
+    severity: "error",
+    path,
+    message: `This token is "${ownType}" but its alias target ${targetPath} is "${targetType}"; a consumer reading the declared type gets a value the target cannot carry.`,
+    details: { target: targetPath, own_type: ownType, target_type: targetType }
+  });
 }
 function modeLabels(collection) {
   const counts = /* @__PURE__ */ new Map();
@@ -1978,10 +2085,11 @@ function styleCensus(tree) {
   walk(tree);
   return { tokens: a.tokens, types: histogram(a.types), descriptions: { present: a.present, missing: a.missing } };
 }
-function foundationDtcg(artifact, options = {}) {
+function foundationDtcg(artifact, options = {}, derivedUnits) {
   const p = {
     artifact,
     options: { values: options.values ?? "standard", ...options.units ? { units: options.units } : {} },
+    derivedUnits: derivedUnits ?? /* @__PURE__ */ new Map(),
     tokenById: new Map(artifact.tokens.map((t) => [t.id, t])),
     tokenIds: new Set(artifact.tokens.map((t) => t.id)),
     collectionById: new Map(artifact.collections.map((c) => [c.id, c])),
@@ -2170,18 +2278,17 @@ function tokenLeaf(p, token, collection, modeId) {
       });
       return null;
     }
+    const terminalType = terminalOwnType(p, value.resolved.chain);
+    if (terminalType && !("omit" in terminalType) && terminalType.$type !== typed.$type) {
+      reportAliasTypeMismatch(p, path, targetPath, typed.$type, terminalType.$type);
+      const transform = literalTransform(value.resolved.value, token.scopes);
+      if (transform !== null) recordFact(p, token.id, mode, transform);
+      return { $type: typed.$type, $value: typed.$value, ...description };
+    }
     recordFact(p, token.id, mode, "alias", typed.$value);
     return { $type: typed.$type, $value: `{${targetPath}}`, ...description };
   }
-  const projected = projectedLiteral(p, token, value.value, (override) => {
-    reportOnce(p, {
-      code: "unit_override_conflicts_with_scope",
-      severity: "warning",
-      path,
-      message: "A unit override names this token but its scopes state a unitless number; the override was ignored.",
-      details: { id: token.id, override, scopes: [...token.scopes] }
-    });
-  });
+  const projected = projectedLiteral(p, token, value.value, ownerFor(p, token));
   const converted2 = projected.converted;
   if ("omit" in converted2) {
     reportOnce(p, {
@@ -2211,6 +2318,124 @@ function dtcgExportFiles(out) {
   return files;
 }
 
+// ../extractor/src/v5/usageUnits.ts
+var LENGTH_SCOPES = ["CORNER_RADIUS", "WIDTH_HEIGHT", "GAP", "FONT_SIZE", "STROKE_FLOAT"];
+var LENGTH_PROPERTIES = [
+  "border-radius",
+  "border-top-left-radius",
+  "border-top-right-radius",
+  "border-bottom-left-radius",
+  "border-bottom-right-radius",
+  "gap",
+  "height",
+  "padding-x",
+  "padding-y",
+  "width"
+];
+var MAX_ALIAS_DEPTH = 16;
+var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+function foundationOf(bundle) {
+  const artifact = bundle.foundation?.artifact;
+  if (!isRecord2(artifact)) return null;
+  if (!Array.isArray(artifact.tokens) || !Array.isArray(artifact.collections)) return null;
+  return artifact;
+}
+function precedes(a, b) {
+  return (compareCodeUnits(a.via, b.via) || compareCodeUnits(a.source, b.source) || compareCodeUnits(a.reason, b.reason)) < 0;
+}
+function bindingsOf(artifact) {
+  if (!isRecord2(artifact) || !isRecord2(artifact.references)) return [];
+  const bindings = artifact.references.bindings;
+  if (!Array.isArray(bindings)) return [];
+  return bindings.filter((b) => isRecord2(b) && b.kind === "variable" && typeof b.source_id === "string" && typeof b.property === "string");
+}
+function aliasTargets(token) {
+  const out = [];
+  for (const value of Object.values(token.values)) {
+    if (value.kind !== "alias" || value.reference.external) continue;
+    const id = value.reference.target_id;
+    if (id !== null && !out.includes(id)) out.push(id);
+  }
+  return out;
+}
+function usageUnits(bundle) {
+  const evidence = /* @__PURE__ */ new Map();
+  const artifact = foundationOf(bundle);
+  if (artifact === null) return evidence;
+  const tokenById = new Map(artifact.tokens.map((t) => [t.id, t]));
+  const collectionById = new Map(artifact.collections.map((c) => [c.id, c]));
+  const lengthUse = /* @__PURE__ */ new Map();
+  const nonLengthUse = [];
+  for (const component of bundle.components) {
+    for (const binding of bindingsOf(component.artifact)) {
+      if (!LENGTH_PROPERTIES.includes(binding.property)) {
+        nonLengthUse.push(binding.source_id);
+        continue;
+      }
+      const found = {
+        unit: "px",
+        via: "binding",
+        source: component.name,
+        reason: binding.property
+      };
+      const prior = lengthUse.get(binding.source_id);
+      if (prior === void 0 || precedes(found, prior)) lengthUse.set(binding.source_id, found);
+    }
+  }
+  const vetoedIds = /* @__PURE__ */ new Set();
+  const walkChain = (startId, includeStart, visit) => {
+    const seen = /* @__PURE__ */ new Set([startId]);
+    let frontier = [startId];
+    for (let depth = 0; depth <= MAX_ALIAS_DEPTH && frontier.length > 0; depth += 1) {
+      const next = [];
+      for (const id of frontier) {
+        const token = tokenById.get(id);
+        if (id !== startId && token !== void 0 && scopesStateUnit(token.scopes)) continue;
+        if (id !== startId || includeStart) visit(id);
+        if (token === void 0) continue;
+        for (const target of aliasTargets(token)) {
+          if (seen.has(target)) continue;
+          seen.add(target);
+          next.push(target);
+        }
+      }
+      frontier = next;
+    }
+  };
+  for (const id of nonLengthUse) walkChain(id, true, (reached) => vetoedIds.add(reached));
+  for (const token of artifact.tokens) {
+    if (!scopesStateNumber(token.scopes)) continue;
+    walkChain(token.id, false, (reached) => vetoedIds.add(reached));
+  }
+  const isCandidate = (id) => {
+    const token = tokenById.get(id);
+    return token !== void 0 && token.type === "number" && !scopesStateUnit(token.scopes);
+  };
+  const record = (id, found) => {
+    if (!isCandidate(id) || vetoedIds.has(id)) return;
+    const prior = evidence.get(id);
+    if (prior === void 0 || precedes(found, prior)) evidence.set(id, found);
+  };
+  const pin = (startId, found, includeStart) => walkChain(startId, includeStart, (id) => record(id, found));
+  for (const token of artifact.tokens) {
+    const scopes = token.scopes.filter((s) => LENGTH_SCOPES.includes(s)).sort(compareCodeUnits);
+    if (scopes.length === 0) continue;
+    const collection = collectionById.get(token.collection_id);
+    if (collection === void 0) continue;
+    pin(token.id, {
+      unit: "px",
+      via: "alias-scope",
+      source: dtcgPathOf(collection.name, token.name),
+      reason: scopes[0]
+    }, false);
+  }
+  for (const token of artifact.tokens) {
+    const found = lengthUse.get(token.id);
+    if (found !== void 0) pin(token.id, found, true);
+  }
+  return evidence;
+}
+
 // ../extractor/src/v5/outputs/naming.ts
 var NAME_CASES = ["kebab", "camel", "pascal", "snake", "constant"];
 function splitWords(segment) {
@@ -2424,10 +2649,22 @@ function cssValue(ctx, type, value, property) {
       if (d && typeof d.value === "number" && typeof d.unit === "string") return `${d.value}${d.unit}`;
       break;
     }
-    case "number":
     case "fontWeight":
       if (typeof value === "number") return String(value);
       break;
+    case "number":
+      if (typeof value === "number") {
+        if (property !== "lineHeight") {
+          report(ctx, {
+            code: "unitless_number",
+            severity: "warning",
+            message: ctx.statesNumber ? "This token has no unit, because its Figma scopes state it is a unitless number. CSS reads it as a number, not a length, which is what those scopes ask for. Do not use it where a length is expected." : "This token has no unit, because its Figma variable states none. CSS reads it as a number, not a length. Narrow the variable's scopes in Figma and pull again.",
+            details: { value, ...member }
+          });
+        }
+        return String(value);
+      }
+      break;
     case "cubicBezier":
       if (Array.isArray(value) && value.length === 4 && value.every((n) => typeof n === "number")) {
         return `cubic-bezier(${value.join(", ")})`;
@@ -2582,22 +2819,59 @@ function shadowDecl(ctx, leaf, name) {
   return `${name}: ${parts.join(", ")};`;
 }
 var commentSafe = (text) => text.replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ");
-function headerText(header, nameCase) {
-  return `${CSS_HEADER_PREFIX} from library ${commentSafe(header.libraryId)}, foundation ${header.contentHash}, ${header.platform}/${header.format}/${nameCase}.
-   Do not edit. Change the design in Figma, republish, and run spec-layer pull. */`;
+function headerText(header, nameCase, unitlessCount = 0, derivedCount = 0) {
+  const lines = [
+    `${CSS_HEADER_PREFIX} from library ${commentSafe(header.libraryId)}, foundation ${header.contentHash}, ${header.platform}/${header.format}/${nameCase}.`,
+    "   Do not edit. Change the design in Figma, republish, and run spec-layer pull."
+  ];
+  if (unitlessCount > 0) {
+    const reportFile = `${header.platform}-${header.format}.report.json`;
+    if (unitlessCount === 1) {
+      lines.push(
+        "   1 property in this file has no unit, because its Figma variable states none.",
+        `   CSS reads it as a number, not a length. See outputs/${reportFile} under your pull's output directory, or narrow the variable's scopes in Figma.`
+      );
+    } else {
+      lines.push(
+        `   ${unitlessCount} properties in this file have no unit, because their Figma variables state none.`,
+        `   CSS reads them as numbers, not lengths. See outputs/${reportFile} under your pull's output directory, or narrow the variables' scopes in Figma.`
+      );
+    }
+  }
+  if (derivedCount > 0) {
+    lines.push(
+      derivedCount === 1 ? "   1 property in this file has a unit its own Figma variable does not state, taken from how the library uses the token." : `   ${derivedCount} properties in this file have a unit their own Figma variables do not state, taken from how the library uses those tokens.`,
+      `   See tokens/report.json under your pull's output directory for what pinned ${derivedCount === 1 ? "it" : "each one"}.`
+    );
+  }
+  return `${lines.join("\n")} */`;
 }
-function emitPass(sources, leavesByFile, names, alive, root, template, modes) {
+function emitPass(sources, leavesByFile, names, alive, root, template, modes, facts) {
   const entries = [];
   const declared = /* @__PURE__ */ new Set();
   const firstFile = /* @__PURE__ */ new Map();
   const blocks = /* @__PURE__ */ new Map();
+  const unitlessByFile = /* @__PURE__ */ new Map();
+  const derivedByFile = /* @__PURE__ */ new Map();
+  const note = (by, file, path) => {
+    const set = by.get(file) ?? /* @__PURE__ */ new Set();
+    set.add(path);
+    by.set(file, set);
+  };
   for (const s of sources) {
     const perCollection = modes?.[s.collection];
     const selector = s.isDefault ? root : (perCollection ?? template).replace(/\{mode\}/g, modeSlug(s.file)).replace(/\{collection\}/g, collectionSlug(s.file));
     const decls = [];
     const declaredHere = [];
     for (const leaf of leavesByFile.get(s.file) ?? []) {
-      const ctx = { names, alive, report: entries, path: leaf.path, ...s.mode !== null ? { mode: s.mode } : {} };
+      const ctx = {
+        names,
+        alive,
+        report: entries,
+        path: leaf.path,
+        statesNumber: facts.statesNumber.has(leaf.path),
+        ...s.mode !== null ? { mode: s.mode } : {}
+      };
       if (leaf.type === "typography") {
         const t = typographyDecls(ctx, leaf, names);
         decls.push(...t.decls);
@@ -2616,12 +2890,17 @@ function emitPass(sources, leavesByFile, names, alive, root, template, modes) {
             declaredHere.push(leaf.path);
           }
         } else {
+          const before = entries.length;
           const v = cssValue(ctx, leaf.type, leaf.value);
           if (v !== null) {
             decls.push(`${name}: ${v};`);
             declared.add(leaf.path);
             declaredHere.push(leaf.path);
           }
+          if (entries.length > before && entries[entries.length - 1].code === "unitless_number" && !ctx.statesNumber) {
+            note(unitlessByFile, s.file, leaf.path);
+          }
+          if (v !== null && facts.derived.has(leaf.path)) note(derivedByFile, s.file, leaf.path);
         }
       }
     }
@@ -2632,7 +2911,7 @@ function emitPass(sources, leavesByFile, names, alive, root, template, modes) {
     if (existing) existing.decls.push(...decls);
     else blocks.set(s.file, { selector, comment, decls });
   }
-  return { blocks, entries, declared, firstFile };
+  return { blocks, entries, declared, firstFile, unitlessByFile, derivedByFile };
 }
 function cssOutput(exp, header, options = {}) {
   const nameCase = options.case ?? CSS_DEFAULTS.case;
@@ -2666,7 +2945,11 @@ function cssOutput(exp, header, options = {}) {
     nameCase
   });
   const names = resolved2.names;
-  const emit = (alive2) => emitPass(sources, leavesByFile, names, alive2, root, template, options.modes);
+  const facts = {
+    statesNumber: new Set(Object.entries(exp.meta).filter(([, entry2]) => scopesStateNumber(entry2.scopes)).map(([path]) => path)),
+    derived: new Set(exp.report.filter((entry2) => entry2.code === "unit_derived_from_usage").map((entry2) => entry2.path))
+  };
+  const emit = (alive2) => emitPass(sources, leavesByFile, names, alive2, root, template, options.modes, facts);
   let alive = new Set(names.keys());
   let pass = emit(alive);
   for (; ; ) {
@@ -2693,11 +2976,16 @@ function cssOutput(exp, header, options = {}) {
       });
     }
   }
-  const head = headerText(header, nameCase);
   const files = {};
   const imports = [];
   for (const [source, block] of pass.blocks) {
     const name = fileNames.get(source);
+    const head = headerText(
+      header,
+      nameCase,
+      pass.unitlessByFile.get(source)?.size ?? 0,
+      pass.derivedByFile.get(source)?.size ?? 0
+    );
     files[name] = `${head}
 
 ${block.selector} {
@@ -2707,7 +2995,7 @@ ${block.decls.map((d) => `  ${d}`).join("\n")}
 `;
     imports.push(block.comment, `@import "./${name}";`);
   }
-  if (imports.length > 0) files[CSS_INDEX_FILE] = `${head}
+  if (imports.length > 0) files[CSS_INDEX_FILE] = `${headerText(header, nameCase)}
 
 ${imports.join("\n")}
 `;
@@ -2726,14 +3014,14 @@ var LibraryBundleError = class extends Error {
     this.code = code2;
   }
 };
-var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isRecord3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function hasContentHash(artifact) {
-  if (!isRecord2(artifact) || !isRecord2(artifact.spec_layer)) return false;
+  if (!isRecord3(artifact) || !isRecord3(artifact.spec_layer)) return false;
   const exp = artifact.spec_layer.export;
-  return isRecord2(exp) && typeof exp.content_hash === "string";
+  return isRecord3(exp) && typeof exp.content_hash === "string";
 }
 function entry(v, where) {
-  if (!isRecord2(v) || typeof v.name !== "string" || typeof v.ai !== "string" || !hasContentHash(v.artifact)) {
+  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 };
@@ -2750,7 +3038,7 @@ function parseLibraryBundle(input) {
       throw new LibraryBundleError("not_json", "This is not valid JSON.");
     }
   }
-  if (!isRecord2(parsed) || parsed.schema !== LIBRARY_BUNDLE_SCHEMA) {
+  if (!isRecord3(parsed) || parsed.schema !== LIBRARY_BUNDLE_SCHEMA) {
     throw new LibraryBundleError("not_bundle", "This is not a Spec Layer library bundle.");
   }
   if (!supportedVersion(parsed.version)) {
@@ -2766,7 +3054,7 @@ function parseLibraryBundle(input) {
   const foundationRaw = parsed.foundation ?? null;
   let foundation = null;
   if (foundationRaw !== null) {
-    if (!isRecord2(foundationRaw) || typeof foundationRaw.ai !== "string" || !hasContentHash(foundationRaw.artifact)) {
+    if (!isRecord3(foundationRaw) || typeof foundationRaw.ai !== "string" || !hasContentHash(foundationRaw.artifact)) {
       throw new LibraryBundleError("malformed", "The foundation entry in this bundle is malformed.");
     }
     foundation = { ai: foundationRaw.ai, artifact: foundationRaw.artifact };
@@ -2851,8 +3139,7 @@ var CODE_SYNTAX_KEY = {
 var PLATFORMS = ["web", "ios", "android", "flutter"];
 var AGENT_HOSTS = ["claude", "cursor", "copilot", "windsurf", "gemini", "agents-md"];
 var uniq = (xs) => [...new Set(xs)];
-function readPackageJson(cwd) {
-  const path = join2(cwd, "package.json");
+function readJsonObject(path) {
   if (!existsSync2(path)) return null;
   let parsed;
   try {
@@ -2861,7 +3148,11 @@ function readPackageJson(cwd) {
     return null;
   }
   if (typeof parsed !== "object" || parsed === null) return null;
-  const record = parsed;
+  return parsed;
+}
+function readPackageJson(cwd) {
+  const record = readJsonObject(join2(cwd, "package.json"));
+  if (!record) return null;
   const deps = {};
   for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
     const block = record[field];
@@ -2987,6 +3278,97 @@ function isPlatform(value) {
 function isAgentHost(value) {
   return AGENT_HOSTS.includes(value);
 }
+function fontPackageSlug(family) {
+  return family.toLowerCase().split(" ").join("-");
+}
+function dependencyNamesFamily(dependencyName, slug2) {
+  const lower = dependencyName.toLowerCase();
+  return lower === slug2 || lower.endsWith(`/${slug2}`);
+}
+function cssNamesFamily(cssText, family) {
+  if (!cssText.includes("@font-face")) return false;
+  return cssText.includes(`"${family}"`) || cssText.includes(`'${family}'`);
+}
+function googleFontsLinkNamesFamily(htmlText, family) {
+  for (const quoted of htmlText.split('"')) {
+    for (const fragment of quoted.split("'")) {
+      const trimmed = fragment.trim();
+      const candidate = trimmed.startsWith("//") ? `https:${trimmed}` : trimmed;
+      if (!candidate.startsWith("http")) continue;
+      let url;
+      try {
+        url = new URL(candidate);
+      } catch {
+        continue;
+      }
+      if (url.hostname !== "fonts.googleapis.com") continue;
+      for (const value of url.searchParams.getAll("family")) {
+        if (value === family || value.startsWith(`${family}:`)) return true;
+      }
+    }
+  }
+  return false;
+}
+function missingFontSources(families, repo) {
+  const dependencyNames = Object.keys({ ...repo.packageJson.dependencies, ...repo.packageJson.devDependencies });
+  return families.filter((family) => {
+    const slug2 = fontPackageSlug(family);
+    if (dependencyNames.some((name) => dependencyNamesFamily(name, slug2))) return false;
+    if (cssNamesFamily(repo.cssText, family)) return false;
+    if (googleFontsLinkNamesFamily(repo.htmlText, family)) return false;
+    return true;
+  });
+}
+function dependencyField(record, field) {
+  const block = record?.[field];
+  if (typeof block !== "object" || block === null) return {};
+  const out = {};
+  for (const [name, range] of Object.entries(block)) {
+    if (typeof range === "string") out[name] = range;
+  }
+  return out;
+}
+function readRootCssText(cwd) {
+  let names = [];
+  try {
+    names = readdirSync(cwd);
+  } catch {
+    names = [];
+  }
+  const chunks = [];
+  for (const name of names) {
+    if (!name.endsWith(".css")) continue;
+    try {
+      chunks.push(readFileSync2(join2(cwd, name), "utf8"));
+    } catch {
+    }
+  }
+  return chunks.join("\n");
+}
+function readEntryHtmlText(cwd) {
+  const chunks = [];
+  for (const path of [join2(cwd, "index.html"), join2(cwd, "public", "index.html")]) {
+    try {
+      if (existsSync2(path)) chunks.push(readFileSync2(path, "utf8"));
+    } catch {
+    }
+  }
+  return chunks.join("\n");
+}
+function readFontRepoSignals(cwd) {
+  const record = readJsonObject(join2(cwd, "package.json"));
+  return {
+    packageJson: {
+      dependencies: dependencyField(record, "dependencies"),
+      devDependencies: dependencyField(record, "devDependencies")
+    },
+    cssText: readRootCssText(cwd),
+    htmlText: readEntryHtmlText(cwd)
+  };
+}
+function missingFontSourcesInRepo(families, cwd) {
+  return missingFontSources(families, readFontRepoSignals(cwd));
+}
 
 // src/outputs.ts
 import { readFileSync as readFileSync3 } from "node:fs";
@@ -3317,7 +3699,7 @@ async function fetchBundle(opts) {
 }
 
 // src/files.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4, readFileSync as readFileSync5, readdirSync as readdirSync3, rmSync as rmSync2, renameSync as renameSync2, existsSync as existsSync5 } from "node:fs";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4, readFileSync as readFileSync6, readdirSync as readdirSync3, rmSync as rmSync2, renameSync as renameSync2, existsSync as existsSync5 } from "node:fs";
 import { join as join5, dirname, relative as relative2, resolve as resolve3, isAbsolute as isAbsolute2, sep } from "node:path";
 
 // src/selection.ts
@@ -3351,6 +3733,17 @@ Available: ${available || "none"}.`
   return bundle.components.map((c) => wanted.some((name) => matchesName(name, c.name)));
 }
 
+// src/version.ts
+import { readFileSync as readFileSync5 } from "node:fs";
+function cliVersion() {
+  try {
+    const parsed = JSON.parse(readFileSync5(new URL("../package.json", import.meta.url), "utf8"));
+    return typeof parsed.version === "string" ? parsed.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 // src/files.ts
 function slugify(name) {
   const slug2 = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
@@ -3361,7 +3754,7 @@ function readManifest(outDir) {
   const path = join5(outDir, "manifest.json");
   if (!existsSync5(path)) return null;
   try {
-    const parsed = JSON.parse(readFileSync5(path, "utf8"));
+    const parsed = JSON.parse(readFileSync6(path, "utf8"));
     parsed.artifacts = parsed.artifacts.map((artifact) => {
       const { aiPath, ...rest } = artifact;
       return {
@@ -3378,7 +3771,7 @@ function readLocalBundle(outDir) {
   const path = join5(outDir, "bundle.json");
   if (!existsSync5(path)) return null;
   try {
-    return parseBundle(readFileSync5(path, "utf8"));
+    return parseBundle(readFileSync6(path, "utf8"));
   } catch {
     throw new Error(`${path} could not be read as a library bundle. Run spec-layer pull again.`);
   }
@@ -3458,7 +3851,12 @@ function writeBundleFiles(opts) {
         if (validateLevel1(artifact).some((d) => d.severity === "error")) {
           throw new Error("The published Foundation context did not pass schema validation. Republish from the plugin, then pull again.");
         }
-        const exp = foundationDtcg(artifact, opts.dtcg ?? {});
+        put("fonts.json", json(fontRequirements(artifact)));
+        const exp = foundationDtcg(
+          artifact,
+          opts.dtcg ?? {},
+          usageUnits(opts.bundle)
+        );
         for (const [name, text] of Object.entries(dtcgExportFiles(exp))) put(`tokens/${name}`, text);
         path = `${outDirRel}/tokens/resolver.json`;
         const header = { libraryId: opts.libraryId, contentHash: opts.bundle.foundation.artifact.spec_layer.export.content_hash };
@@ -3490,6 +3888,7 @@ function writeBundleFiles(opts) {
       bundleHash: opts.bundleHash,
       pluginVersion: opts.bundle.pluginVersion,
       extractorVersion: opts.bundle.extractorVersion,
+      cliVersion: cliVersion(),
       selection,
       componentSpecsDir,
       artifacts,
@@ -3513,7 +3912,7 @@ function writeBundleFiles(opts) {
 }
 
 // src/gitignore.ts
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync6 } from "node:fs";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync5, existsSync as existsSync6 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join as join6, dirname as dirname2, resolve as resolve4 } from "node:path";
 var COMMENT = "# Spec Layer pull key, not for committing";
@@ -3550,7 +3949,7 @@ function ensureIgnored(cwd, fileName) {
 ${fileName}
 `);
     } else {
-      const body = readFileSync6(path, "utf8");
+      const body = readFileSync7(path, "utf8");
       if (!hasEntryLine(body, fileName)) {
         const lead = body.length === 0 || body.endsWith("\n") ? "" : "\n";
         writeFileSync5(path, `${body}${lead}${COMMENT}
@@ -3567,12 +3966,16 @@ ${fileName}
 }
 
 // src/skill.ts
-import { existsSync as existsSync7, mkdirSync as mkdirSync3, readdirSync as readdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, readdirSync as readdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync6 } from "node:fs";
 import { dirname as dirname3, join as join7 } from "node:path";
 
 // src/tools.ts
 var OK_OR_ERROR = { "0": "success", "1": "usage error, bad key or id, or a network or server failure" };
 var LOCAL_ONLY = { "0": "success", "1": "no local pull, or a usage error" };
+var PULL_EXITS = {
+  "0": "success, even when tokens/report.json or an outputs/*.report.json holds an error-severity entry (pass --strict to fail on that instead)",
+  "1": "usage error, bad key or id, a network or server failure, or --strict with an error-severity entry in tokens/report.json or an outputs/*.report.json, including on a cached (304) pull"
+};
 var TOOLS = [
   {
     name: "setup",
@@ -3603,9 +4006,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]...",
-    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.",
-    when: "After setup, whenever status says the local copy is behind, or after changing the include, dtcg, outputs, or componentSpecsDir blocks.",
+    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.",
     network: true,
     needsKey: true,
     writes: [
@@ -3613,7 +4016,7 @@ var TOOLS = [
       "outputs[].path from speclayer.json (default tokens/ for web), a directory written in place",
       "componentSpecsDir from speclayer.json (default component-specs/), written in place"
     ],
-    exits: OK_OR_ERROR
+    exits: PULL_EXITS
   },
   {
     name: "status",
@@ -3700,25 +4103,43 @@ function toolsJson(version) {
 
 // src/skill.ts
 var RESERVED = /* @__PURE__ */ new Set(["resolver.json", "spec-layer.meta.json", "report.json"]);
-function countNumberTokens(tree) {
-  if (typeof tree !== "object" || tree === null || Array.isArray(tree)) return 0;
+function collectNumberTokenPaths(tree, path, legitimatelyUnitless, out) {
+  if (typeof tree !== "object" || tree === null || Array.isArray(tree)) return;
   const record = tree;
-  if (record.$type === "number" && "$value" in record) return 1;
-  let n = 0;
+  if (record.$type === "number" && "$value" in record) {
+    const dotted = path.join(".");
+    if (!legitimatelyUnitless.has(dotted)) out.add(dotted);
+    return;
+  }
   for (const [key, value] of Object.entries(record)) {
     if (key.startsWith("$")) continue;
-    n += countNumberTokens(value);
+    collectNumberTokenPaths(value, [...path, key], legitimatelyUnitless, out);
   }
-  return n;
 }
 function readJson(path) {
   if (!existsSync7(path)) return null;
   try {
-    return JSON.parse(readFileSync7(path, "utf8"));
+    return JSON.parse(readFileSync8(path, "utf8"));
   } catch {
     return null;
   }
 }
+function unitlessScopedPaths(tokensDir) {
+  const meta = readJson(join7(tokensDir, "spec-layer.meta.json"));
+  const out = /* @__PURE__ */ new Set();
+  if (typeof meta !== "object" || meta === null || Array.isArray(meta)) return out;
+  for (const [path, entry2] of Object.entries(meta)) {
+    if (typeof entry2 !== "object" || entry2 === null) continue;
+    const { type, scopes } = entry2;
+    if (type === "number" && Array.isArray(scopes) && scopesStateNumber(scopes)) out.add(path);
+  }
+  return out;
+}
+function isFontRequirement(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const r = v;
+  return typeof r.family === "string" && Array.isArray(r.weights) && r.weights.every((w) => typeof w === "number") && Array.isArray(r.used_by) && r.used_by.every((u) => typeof u === "string");
+}
 function summarizePull(cwd, outDir, manifest) {
   if (!manifest) return null;
   const absOut = join7(cwd, outDir);
@@ -3735,17 +4156,37 @@ function summarizePull(cwd, outDir, manifest) {
     } catch {
       tokenFiles = [];
     }
-    let unitlessNumbers = 0;
+    const legitimatelyUnitless = unitlessScopedPaths(tokensDir);
+    const unitlessPaths = /* @__PURE__ */ new Set();
     for (const file of tokenFiles) {
       if (file.startsWith("styles.")) continue;
-      unitlessNumbers += countNumberTokens(readJson(join7(tokensDir, file)));
+      collectNumberTokenPaths(readJson(join7(tokensDir, file)), [], legitimatelyUnitless, unitlessPaths);
     }
+    const unitlessNumbers = unitlessPaths.size;
     const reportCounts = {};
     if (Array.isArray(report2)) {
       for (const entry2 of report2) {
         if (typeof entry2?.code === "string") reportCounts[entry2.code] = (reportCounts[entry2.code] ?? 0) + 1;
       }
     }
+    const fontsPath = join7(absOut, "fonts.json");
+    let fontsStatus = "missing";
+    let fonts = [];
+    if (existsSync7(fontsPath)) {
+      let parsed;
+      try {
+        parsed = JSON.parse(readFileSync8(fontsPath, "utf8"));
+      } catch {
+        parsed = void 0;
+      }
+      if (Array.isArray(parsed)) {
+        fontsStatus = "ok";
+        fonts = parsed.filter(isFontRequirement);
+      } else {
+        fontsStatus = "unreadable";
+      }
+    }
+    const missingFontFamilies = fontsStatus === "ok" && fonts.length > 0 ? missingFontSourcesInRepo(fonts.map((f) => f.family), cwd) : [];
     foundation = {
       written: foundationEntry.path !== null && resolver !== null,
       sets: resolver ? Object.keys(resolver.sets ?? {}) : [],
@@ -3756,7 +4197,10 @@ function summarizePull(cwd, outDir, manifest) {
       })) : [],
       tokenFiles,
       unitlessNumbers,
-      reportCounts
+      reportCounts,
+      fontsStatus,
+      fonts,
+      missingFontFamilies
     };
   }
   return {
@@ -3820,12 +4264,49 @@ function stackSection(input) {
     const label = platformSource === "flag" ? "chosen with --platform" : platformSource === "config" ? "set in speclayer.json" : "detected";
     lines.push(`Target platform${platforms.length > 1 ? "s" : ""} (${label}): ${platforms.join(", ")}.`, "");
   }
+  const tokensDir = `${input.outDir}/tokens/`;
+  if (pull?.foundation && pull.foundation.unitlessNumbers > 0) {
+    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.` : "."),
+      ""
+    );
+  }
   for (const platform of platforms) {
     const key = CODE_SYNTAX_KEY[platform];
-    const tokensDir = `${input.outDir}/tokens/`;
     if (platform === "web") {
       lines.push("### Web", "");
       const cssOut = pull?.outputs.find((o) => o.platform === "web" && o.format === "css" && o.written) ?? null;
+      if (pull?.foundation?.written) {
+        const { fontsStatus, fonts, missingFontFamilies } = pull.foundation;
+        if (fontsStatus === "ok" && fonts.length > 0) {
+          const fontList = fonts.map((f) => `${f.family} at ${f.weights.join(", ")}`).join("; ");
+          lines.push(
+            `**Fonts.** This library's type is ${fontList}. Load every weight listed; a missing weight renders as a synthesised bold that matches nothing in the design.`
+          );
+          for (const family of missingFontFamilies) {
+            lines.push(
+              `${family}: nothing in this repository loads it. Add a font source before building UI, or every component that uses it renders in the browser default.`
+            );
+          }
+          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.`,
+            ""
+          );
+        } 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.`,
+            ""
+          );
+        } 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.`,
+            ""
+          );
+        }
+      }
       if (cssOut) {
         const mapPath = `${input.outDir}/outputs/web-css.map.json`;
         lines.push(
@@ -3905,13 +4386,6 @@ function stackSection(input) {
       );
     }
   }
-  if (pull?.foundation && pull.foundation.unitlessNumbers > 0) {
-    const n = pull.foundation.unitlessNumbers;
-    lines.push(
-      `${n} token${n === 1 ? " is" : "s are"} exported as ${code('$type: "number"')} because the Figma scopes state no unit. If your code needs them as px or rem, declare it in ${code("speclayer.json")}: ${code('"dtcg": { "units": { "<Collection>/<name glob>": "px" } }')}, then run ${code("spec-layer pull")}. Nothing is inferred from a name; an override that contradicts a stated scope is ignored and listed in ${code("report.json")}.`,
-      ""
-    );
-  }
   return lines;
 }
 function pullSection(input) {
@@ -4090,7 +4564,7 @@ ${BLOCK_END}
 function installSkill(cwd, host, guide) {
   const target = installTarget(host);
   const abs = join7(cwd, target.path);
-  const existing = existsSync7(abs) ? readFileSync7(abs, "utf8") : null;
+  const existing = existsSync7(abs) ? readFileSync8(abs, "utf8") : null;
   const next = target.mode === "file" ? renderForHost(host, guide) : upsertBlock(existing, renderForHost(host, guide));
   if (existing === next) return { path: target.path, result: "unchanged" };
   mkdirSync3(dirname3(abs), { recursive: true });
@@ -4098,17 +4572,6 @@ function installSkill(cwd, host, guide) {
   return { path: target.path, result: existing === null ? "created" : "updated" };
 }
 
-// src/version.ts
-import { readFileSync as readFileSync8 } from "node:fs";
-function cliVersion() {
-  try {
-    const parsed = JSON.parse(readFileSync8(new URL("../package.json", import.meta.url), "utf8"));
-    return typeof parsed.version === "string" ? parsed.version : "unknown";
-  } catch {
-    return "unknown";
-  }
-}
-
 // src/commands.ts
 var NO_LOCAL_PULL = "No local pull found. Run spec-layer pull.";
 function manifestReader() {
@@ -4315,11 +4778,59 @@ git rm --cached ${ignored.line}`);
   return 0;
 }
 function outputFilesOnDisk(cwd, outDir, o) {
-  const mapPath = join8(cwd, outDir, "outputs", `${outputId(o)}.map.json`);
-  if (!existsSync8(mapPath)) return false;
+  const id = outputId(o);
+  for (const rel of [`${id}.map.json`, `${id}.report.json`]) {
+    if (!existsSync8(join8(cwd, outDir, "outputs", rel))) return false;
+  }
   const imports = readIndexImports(cwd, o);
   return imports !== null && imports.every((f) => existsSync8(resolve5(cwd, o.path, f)));
 }
+function foundationFilesOnDisk(cwd, outDir) {
+  return ["fonts.json", join8("tokens", "report.json"), join8("tokens", "resolver.json")].every((rel) => existsSync8(join8(cwd, outDir, rel)));
+}
+function readJsonArray(path) {
+  if (!existsSync8(path)) return [];
+  try {
+    const parsed = JSON.parse(readFileSync9(path, "utf8"));
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function readReportSeverities(path) {
+  return readJsonArray(path).map((entry2) => entry2.severity).filter((s) => s === "error" || s === "warning" || s === "info");
+}
+function readFontFamilies(cwd, outDir) {
+  return readJsonArray(join8(cwd, outDir, "fonts.json")).map((entry2) => entry2.family).filter((f) => typeof f === "string");
+}
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? "" : "s"}`;
+}
+function printReportSummary(cwd, outDir, outputs, io2) {
+  const reportPaths = [];
+  let errors = 0;
+  let warnings = 0;
+  const add = (severities, path) => {
+    if (severities.length === 0) return;
+    errors += severities.filter((s) => s === "error").length;
+    warnings += severities.filter((s) => s === "warning").length;
+    reportPaths.push(path);
+  };
+  add(readReportSeverities(join8(cwd, outDir, "tokens", "report.json")), `${outDir}/tokens/report.json`);
+  for (const o of outputs) {
+    add(readReportSeverities(join8(cwd, outDir, "outputs", `${outputId(o)}.report.json`)), `${outDir}/outputs/${outputId(o)}.report.json`);
+  }
+  if (errors > 0 || warnings > 0) {
+    io2.err(`${plural(errors, "error")}, ${plural(warnings, "warning")} in the token output. See ${reportPaths.join(", ")}.`);
+  }
+  const fontFamilies = readFontFamilies(cwd, outDir);
+  if (fontFamilies.length > 0) {
+    for (const family of missingFontSourcesInRepo(fontFamilies, cwd)) {
+      io2.err(`This library needs ${family}, and nothing in this repository loads it. See fonts.json.`);
+    }
+  }
+  return errors;
+}
 async function runPull(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
   const opts = resolved(cwd, flags, env, io2, manifestAt);
@@ -4339,10 +4850,10 @@ async function runPull(cwd, flags, env, io2, fetcher) {
   const foundationOnDisk = Boolean(manifest?.artifacts.find((a) => a.kind === "foundation")?.path);
   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 && sameOutput(
+  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 }
-  ) && briefsOnDisk && (!willWriteFoundation || outputs.every((o) => outputFilesOnDisk(cwd, opts.outDir, o))) ? manifest.bundleHash : void 0;
+  ) && 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,
     libraryId: opts.libraryId,
@@ -4356,6 +4867,8 @@ async function runPull(cwd, flags, env, io2, fetcher) {
   }
   if (result.kind === "not_modified") {
     io2.out(`Already up to date (published ${manifest?.publishedAt ?? "unknown"}).`);
+    const cachedErrors = printReportSummary(cwd, opts.outDir, outputs, io2);
+    if (flags.strict && cachedErrors > 0) return 1;
     return 0;
   }
   let written;
@@ -4410,6 +4923,8 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     const missing = platformsMissingFormat(platforms);
     if (missing.length > 0) io2.out(missingFormatNote(missing));
   }
+  const errors = printReportSummary(cwd, opts.outDir, outputs, io2);
+  if (flags.strict && errors > 0) return 1;
   return 0;
 }
 async function runStatus(cwd, flags, env, io2, fetcher) {
@@ -4589,8 +5104,9 @@ Commands:
                                                  store the key, then pull
   init    --id lib_... [--out DIR] [selection] [--platform P]...
                                                  write speclayer.json
-  pull    [--id lib_...] [--key sl_...] [selection] [--platform P]...
-                                                 fetch the library into DIR (default .speclayer); the foundation lands as DTCG under DIR/tokens/
+  pull    [--id lib_...] [--key sl_...] [selection] [--platform P]... [--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]
@@ -4631,6 +5147,7 @@ async function main() {
         canonical: { type: "boolean" },
         json: { type: "boolean" },
         install: { type: "boolean" },
+        strict: { type: "boolean" },
         agent: { type: "string", multiple: true },
         platform: { type: "string", multiple: true }
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-layer",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "Pull design-system context published by the Spec Layer Figma plugin",
   "license": "MIT",
   "type": "module",