spec-layer 0.2.1 → 0.4.0

package/dist/cli.js

@@ -559,7 +559,7 @@ var require_sha256 = __commonJS({
 import { parseArgs } from "node:util";
 
 // src/commands.ts
-import { join as join3 } from "node:path";
+import { join as join5 } from "node:path";
 
 // ../extractor/src/statesMatrix.ts
 var STATE_ORDER = [
@@ -588,6 +588,71 @@ var STATE_ORDER = [
 ];
 var STATE_VOCAB = new Set(STATE_ORDER);
 
+// ../extractor/src/v5/precision.ts
+var SIGNIFICANT_DIGITS = 7;
+var FLOAT32_EXACT_LIMIT = 16777216;
+function canonicalNumber(n) {
+  if (!Number.isFinite(n)) return n;
+  if (Number.isInteger(n)) return n + 0;
+  if (Math.abs(n) >= FLOAT32_EXACT_LIMIT) return n + 0;
+  return Number(n.toPrecision(SIGNIFICANT_DIGITS)) + 0;
+}
+
+// ../extractor/src/v5/diagnostics.ts
+var DEFAULT_SEVERITY = {
+  UNRESOLVED_ALIAS: "error",
+  UNRESOLVED_EXTERNAL_ALIAS: "error",
+  ALIAS_CYCLE: "error",
+  ALIAS_TYPE_MISMATCH: "error",
+  MISSING_MODE_VALUE: "error",
+  DUPLICATE_SOURCE_ID: "error",
+  PATH_COLLISION: "error",
+  UNSUPPORTED_VALUE_TYPE: "error",
+  INCONSISTENT_VALUE_SHAPE: "error",
+  AMBIGUOUS_ALIAS_TARGET: "error",
+  INVALID_SOURCE_COLOR: "error",
+  // Error, and the same severity UNRESOLVED_ALIAS carries: §18 Level 2 makes
+  // no distinction between reference classes, and an artifact whose token
+  // points at a collection that is not there is broken in exactly the way a
+  // dangling alias is -- a consumer joining on the id gets nothing.
+  UNRESOLVED_REFERENCE: "error",
+  SOURCE_PARTIALLY_UNAVAILABLE: "error",
+  STYLE_BINDING_DRIFT: "warning",
+  CONFUSABLE_NAME: "warning",
+  INFERRED_LIFECYCLE: "warning",
+  DEPRECATED_REFERENCE: "warning",
+  GENERATED_NAME_COLLISION: "warning",
+  // Warning, not error: a migrated artifact with synthetic ids is still usable
+  // for generation -- what it cannot do is survive a rename, which is a fact
+  // about future diffs rather than about this artifact's correctness.
+  SYNTHETIC_IDENTITY: "warning",
+  // Warning, not error: the number is retained and usable, and Level 4
+  // readiness is a consumer's judgment. What the consumer must decide is the
+  // unit; the message says so and `units` overrides in the CLI are the
+  // remedy.
+  UNIT_METADATA_UNAVAILABLE: "warning",
+  MODE_VALUES_IDENTICAL: "info",
+  MISSING_DESCRIPTION: "info",
+  // Info, not error: no value depends on metadata the Plugin API never
+  // exposes in the first place -- there is nothing for a consumer to decide
+  // and nothing missing that this export could have captured.
+  METADATA_UNAVAILABLE: "info",
+  // Info, not error: a deliberately scoped export states its own scope in
+  // `completeness`; that is a fact about the request, not a defect in it.
+  EXPORT_SCOPED: "info"
+};
+var compareCodeUnits = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+function diagnostic(code, fields) {
+  return {
+    code,
+    severity: DEFAULT_SEVERITY[code],
+    entity_id: fields.entity_id,
+    ...fields.mode_id !== void 0 ? { mode_id: fields.mode_id } : {},
+    message: fields.message,
+    ...fields.details !== void 0 ? { details: fields.details } : {}
+  };
+}
+
 // ../extractor/src/hash.ts
 var import_js_sha256 = __toESM(require_sha256(), 1);
 
@@ -733,9 +798,1241 @@ var FOUNDATION_SYSTEM_PROMPT = [
   "No prose outside the JSON, no code fence."
 ].join("\n");
 
+// ../extractor/src/v5/value.ts
+var SUPPORTED_UNITS = ["px", "rem", "em", "%", "deg", "ms", "s"];
+var SUPPORTED_TOKEN_TYPES = [
+  "color",
+  "dimension",
+  "number",
+  "string",
+  "boolean",
+  "duration",
+  "cubic_bezier",
+  "font_family"
+];
+var SUPPORTED_VALUE_KINDS = ["literal", "alias", "missing"];
+var SUPPORTED_DURATION_UNITS = ["ms", "s"];
+
 // ../extractor/src/v5/canonical.ts
 var import_js_sha2562 = __toESM(require_sha256(), 1);
 
+// ../extractor/src/v5/validate.ts
+var ROOT = "<artifact>";
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isNonEmptyString = (v) => typeof v === "string" && v.length > 0;
+var isFiniteNumber = (v) => typeof v === "number" && Number.isFinite(v);
+var isStringArray = (v) => Array.isArray(v) && v.every((item) => typeof item === "string");
+var HEX_RE = /^#[0-9a-f]{6}$/;
+function shape(entityId, message, modeId) {
+  return diagnostic("INCONSISTENT_VALUE_SHAPE", {
+    entity_id: entityId,
+    message,
+    ...modeId !== void 0 ? { mode_id: modeId } : {}
+  });
+}
+function unsupported(entityId, message, modeId) {
+  return diagnostic("UNSUPPORTED_VALUE_TYPE", {
+    entity_id: entityId,
+    message,
+    ...modeId !== void 0 ? { mode_id: modeId } : {}
+  });
+}
+function validateTypedValue(type, tv, entityId, out, modeId) {
+  switch (type) {
+    case "color": {
+      if (tv.color_space !== "srgb") {
+        out.push(unsupported(entityId, 'color.color_space must be "srgb".', modeId));
+      }
+      if (typeof tv.hex !== "string" || !HEX_RE.test(tv.hex)) {
+        out.push(unsupported(entityId, 'color.hex must be six lowercase hex digits with a leading "#".', modeId));
+      }
+      if (!isFiniteNumber(tv.alpha) || tv.alpha < 0 || tv.alpha > 1) {
+        out.push(unsupported(entityId, "color.alpha must be a finite number between 0 and 1.", modeId));
+      }
+      if (tv.channels !== void 0) {
+        const channels = tv.channels;
+        if (!Array.isArray(channels) || channels.length !== 3 || !channels.every(isFiniteNumber)) {
+          out.push(unsupported(entityId, "color.channels must be three finite numbers when present.", modeId));
+        }
+      }
+      break;
+    }
+    case "dimension": {
+      if (!isFiniteNumber(tv.number)) {
+        out.push(unsupported(entityId, "dimension.number must be a finite number.", modeId));
+      }
+      if (typeof tv.unit !== "string" || !SUPPORTED_UNITS.includes(tv.unit)) {
+        out.push(unsupported(entityId, "dimension.unit is missing or outside the supported unit vocabulary.", modeId));
+      }
+      break;
+    }
+    case "number": {
+      if (!isFiniteNumber(tv.value)) {
+        out.push(unsupported(entityId, "number.value must be a finite number.", modeId));
+      }
+      break;
+    }
+    case "string": {
+      if (typeof tv.value !== "string") {
+        out.push(unsupported(entityId, "string.value must be a string.", modeId));
+      }
+      break;
+    }
+    case "boolean": {
+      if (typeof tv.value !== "boolean") {
+        out.push(unsupported(entityId, "boolean.value must be a boolean.", modeId));
+      }
+      break;
+    }
+    case "duration": {
+      if (!isFiniteNumber(tv.number)) {
+        out.push(unsupported(entityId, "duration.number must be a finite number.", modeId));
+      }
+      if (typeof tv.unit !== "string" || !SUPPORTED_DURATION_UNITS.includes(tv.unit)) {
+        out.push(unsupported(entityId, 'duration.unit must be "ms" or "s".', modeId));
+      }
+      break;
+    }
+    case "cubic_bezier": {
+      const value = tv.value;
+      if (!Array.isArray(value) || value.length !== 4 || !value.every(isFiniteNumber)) {
+        out.push(unsupported(entityId, "cubic_bezier.value must be four finite numbers.", modeId));
+      }
+      break;
+    }
+    case "font_family": {
+      if (typeof tv.value !== "string") {
+        out.push(unsupported(entityId, "font_family.value must be a string.", modeId));
+      }
+      break;
+    }
+    default:
+      break;
+  }
+}
+function validateTypedValueEnvelope(value, entityId, out, modeId, expectedType) {
+  if (!isRecord(value)) {
+    out.push(shape(entityId, "A typed value must be an object.", modeId));
+    return;
+  }
+  const { type } = value;
+  if (typeof type !== "string" || !SUPPORTED_TOKEN_TYPES.includes(type)) {
+    out.push(shape(entityId, `Typed value has an unrecognized or missing "type" discriminant: ${JSON.stringify(type)}.`, modeId));
+    return;
+  }
+  if (expectedType !== void 0 && type !== expectedType) {
+    out.push(shape(
+      entityId,
+      `Expected a "${expectedType}" typed value, but the value declares "${type}".`,
+      modeId
+    ));
+  }
+  validateTypedValue(type, value, entityId, out, modeId);
+}
+function validateChainStep(step, entityId, out, modeId) {
+  if (!isRecord(step) || typeof step.token_id !== "string" || typeof step.mode_id !== "string") {
+    out.push(shape(entityId, "A resolution chain step must carry both token_id and mode_id.", modeId));
+  }
+}
+function validateAliasReference(ref, entityId, out, modeId) {
+  if (!(ref.target_id === null || typeof ref.target_id === "string")) {
+    out.push(shape(entityId, "alias.reference.target_id must be a string or null.", modeId));
+  }
+  if (!(ref.target_collection_id === null || typeof ref.target_collection_id === "string")) {
+    out.push(shape(entityId, "alias.reference.target_collection_id must be a string or null.", modeId));
+  }
+  if (!isStringArray(ref.target_path)) {
+    out.push(shape(entityId, "alias.reference.target_path must be an array of strings.", modeId));
+  }
+  if (typeof ref.external !== "boolean") {
+    out.push(shape(entityId, "alias.reference.external must be a boolean.", modeId));
+  }
+  if (ref.source_library_name !== void 0 && typeof ref.source_library_name !== "string") {
+    out.push(shape(entityId, "alias.reference.source_library_name must be a string when present.", modeId));
+  }
+}
+function validateAliasResolution(resolved2, entityId, out, modeId, expectedType) {
+  const { status } = resolved2;
+  if (status === "resolved") {
+    validateTypedValueEnvelope(resolved2.value, entityId, out, modeId, expectedType);
+  } else if (status === "unresolved") {
+    if (!isNonEmptyString(resolved2.reason)) {
+      out.push(shape(entityId, "An unresolved alias must carry a non-empty reason.", modeId));
+    }
+    if (resolved2.value !== null) {
+      out.push(shape(entityId, "An unresolved alias must carry a null value.", modeId));
+    }
+  } else {
+    out.push(shape(entityId, `alias.resolved.status has an unrecognized value: ${JSON.stringify(status)}.`, modeId));
+  }
+  if (!Array.isArray(resolved2.chain)) {
+    out.push(shape(entityId, "alias.resolved.chain must be an array.", modeId));
+  } else {
+    for (const step of resolved2.chain) validateChainStep(step, entityId, out, modeId);
+  }
+}
+function validateValue(value, entityId, modeId, out, expectedType) {
+  if (!isRecord(value)) {
+    out.push(shape(entityId, "A token value must be an object, not a bare primitive.", modeId));
+    return;
+  }
+  const { kind } = value;
+  if (typeof kind !== "string" || !SUPPORTED_VALUE_KINDS.includes(kind)) {
+    out.push(shape(entityId, `Value has an unrecognized or missing "kind" discriminant: ${JSON.stringify(kind)}.`, modeId));
+    return;
+  }
+  if (kind === "literal") {
+    validateTypedValueEnvelope(value.value, entityId, out, modeId, expectedType);
+  } else if (kind === "alias") {
+    if (!isRecord(value.reference)) {
+      out.push(shape(entityId, "An alias value must carry a reference object.", modeId));
+    } else {
+      validateAliasReference(value.reference, entityId, out, modeId);
+    }
+    if (!isRecord(value.resolved)) {
+      out.push(shape(entityId, "An alias value must carry a resolved object.", modeId));
+    } else {
+      validateAliasResolution(value.resolved, entityId, out, modeId, expectedType);
+    }
+  } else if (kind === "missing") {
+    if (!isNonEmptyString(value.reason)) {
+      out.push(shape(entityId, "A missing value must carry a non-empty reason.", modeId));
+    }
+  }
+}
+function validateIdentity(entity, entityId, kind, out) {
+  if (!isNonEmptyString(entity.id)) {
+    out.push(shape(entityId, `${kind}.id must be a non-empty string.`));
+  }
+  if (typeof entity.name !== "string") {
+    out.push(shape(entityId, `${kind}.name must be a string.`));
+  }
+  if (!isStringArray(entity.path) || entity.path.length === 0) {
+    out.push(shape(entityId, `${kind}.path must be a non-empty array of strings.`));
+  }
+  if (entity.suggested_code_name !== void 0 && typeof entity.suggested_code_name !== "string") {
+    out.push(shape(entityId, `${kind}.suggested_code_name must be a string when present.`));
+  }
+}
+function validatePublication(value, entityId, out) {
+  if (!isRecord(value) || typeof value.published !== "boolean" || typeof value.hidden_from_publishing !== "boolean") {
+    out.push(shape(
+      entityId,
+      "publication must state boolean published and hidden_from_publishing fields."
+    ));
+  }
+}
+function validateLifecycle(value, entityId, out) {
+  if (!isRecord(value)) {
+    out.push(shape(entityId, "lifecycle must be an object when present."));
+    return;
+  }
+  if (!["active", "deprecated", "archived"].includes(value.status)) {
+    out.push(shape(entityId, "lifecycle.status must be active, deprecated, or archived."));
+  }
+  if (!(value.replacement_id === null || typeof value.replacement_id === "string")) {
+    out.push(shape(entityId, "lifecycle.replacement_id must be a string or null."));
+  }
+}
+function validateSource(value, entityId, out) {
+  if (!isRecord(value)) {
+    out.push(shape(entityId, "source must be an object when present."));
+    return;
+  }
+  if (typeof value.remote !== "boolean") {
+    out.push(shape(entityId, "source.remote must be a boolean."));
+  }
+  for (const field of ["library_file_id", "library_name", "modified_at"]) {
+    if (!(value[field] === null || typeof value[field] === "string")) {
+      out.push(shape(entityId, `source.${field} must be a string or null.`));
+    }
+  }
+}
+function validateOptionalEntityMetadata(entity, entityId, out, includeSource = false, includeLifecycle = true) {
+  if (entity.publication !== void 0) validatePublication(entity.publication, entityId, out);
+  if (includeLifecycle && entity.lifecycle !== void 0) validateLifecycle(entity.lifecycle, entityId, out);
+  if (includeSource && entity.source !== void 0) validateSource(entity.source, entityId, out);
+}
+function validateCollection(collection, index, out) {
+  if (!isRecord(collection)) {
+    out.push(shape(`collections[${index}]`, "A collection must be an object."));
+    return;
+  }
+  const entityId = isNonEmptyString(collection.id) ? collection.id : `collections[${index}]`;
+  validateIdentity(collection, entityId, "collection", out);
+  if (!isNonEmptyString(collection.default_mode_id)) {
+    out.push(shape(entityId, "collection.default_mode_id must be a non-empty string."));
+  }
+  if (!Array.isArray(collection.modes)) {
+    out.push(shape(entityId, "collection.modes must be an array."));
+  } else {
+    collection.modes.forEach((mode, modeIndex) => {
+      if (!isRecord(mode)) {
+        out.push(shape(entityId, `collection.modes[${modeIndex}] must be an object.`));
+        return;
+      }
+      if (!isNonEmptyString(mode.id)) {
+        out.push(shape(entityId, `collection.modes[${modeIndex}].id must be a non-empty string.`));
+      }
+      if (typeof mode.name !== "string") {
+        out.push(shape(entityId, `collection.modes[${modeIndex}].name must be a string.`));
+      }
+      if (!isFiniteNumber(mode.order)) {
+        out.push(shape(entityId, `collection.modes[${modeIndex}].order must be a finite number.`));
+      }
+    });
+  }
+  validateOptionalEntityMetadata(collection, entityId, out, true, false);
+}
+function validateToken(token, index, out) {
+  if (!isRecord(token)) {
+    out.push(shape(`tokens[${index}]`, "A token must be an object."));
+    return;
+  }
+  const entityId = isNonEmptyString(token.id) ? token.id : `tokens[${index}]`;
+  if (!isNonEmptyString(token.id)) {
+    out.push(shape(entityId, "token.id must be a non-empty string."));
+  }
+  if (typeof token.collection_id !== "string" || token.collection_id.length === 0) {
+    out.push(shape(entityId, "token.collection_id must be a non-empty string."));
+  }
+  if (typeof token.name !== "string") {
+    out.push(shape(entityId, "token.name must be a string."));
+  }
+  if (!isStringArray(token.path) || token.path.length === 0) {
+    out.push(shape(entityId, "token.path must be a non-empty array of strings."));
+  }
+  if (token.suggested_code_name !== void 0 && typeof token.suggested_code_name !== "string") {
+    out.push(shape(entityId, "token.suggested_code_name must be a string when present."));
+  }
+  if (token.code_syntax !== void 0) {
+    if (!isRecord(token.code_syntax) || Object.values(token.code_syntax).some((v) => typeof v !== "string")) {
+      out.push(shape(entityId, "token.code_syntax must be an object of strings when present."));
+    }
+  }
+  let tokenType;
+  if (typeof token.type !== "string") {
+    out.push(shape(entityId, "token.type must be a string."));
+  } else if (!SUPPORTED_TOKEN_TYPES.includes(token.type)) {
+    out.push(shape(entityId, `token.type is not a recognized token type: ${JSON.stringify(token.type)}.`));
+  } else {
+    tokenType = token.type;
+  }
+  if (typeof token.description !== "string") {
+    out.push(shape(entityId, "token.description must be present and a string (an empty string is allowed)."));
+  }
+  if (!isStringArray(token.scopes)) {
+    out.push(shape(entityId, "token.scopes must be an array of strings."));
+  }
+  validateOptionalEntityMetadata(token, entityId, out);
+  if (!isRecord(token.values)) {
+    out.push(shape(entityId, "token.values must be an object keyed by mode id."));
+    return;
+  }
+  for (const [modeId, value] of Object.entries(token.values)) {
+    validateValue(value, entityId, modeId, out, tokenType);
+  }
+}
+function validateStyleProperty(property, entityId, propertyName, out) {
+  if (!isRecord(property)) {
+    out.push(shape(entityId, `typography.properties.${propertyName} must be an object.`));
+    return;
+  }
+  const { source } = property;
+  if (!isRecord(source)) {
+    out.push(shape(entityId, `typography.properties.${propertyName}.source must be an object.`));
+  } else if (source.kind === "alias") {
+    if (!(source.target_id === null || typeof source.target_id === "string")) {
+      out.push(shape(entityId, `typography.properties.${propertyName}.source.target_id must be a string or null.`));
+    }
+    if (!isStringArray(source.target_path)) {
+      out.push(shape(entityId, `typography.properties.${propertyName}.source.target_path must be an array of strings.`));
+    }
+  } else if (source.kind !== "literal") {
+    out.push(shape(entityId, `typography.properties.${propertyName}.source.kind must be literal or alias.`));
+  }
+  if (property.resolved !== null) {
+    validateTypedValueEnvelope(property.resolved, entityId, out);
+  }
+}
+var TYPOGRAPHY_STYLE_PROPERTIES = [
+  "font_family",
+  "font_weight",
+  "font_size",
+  "line_height",
+  "letter_spacing",
+  "paragraph_spacing",
+  "paragraph_indent"
+];
+function validateTypographyStyle(style, index, out) {
+  if (!isRecord(style)) {
+    out.push(shape(`styles.typography[${index}]`, "A typography style must be an object."));
+    return;
+  }
+  const entityId = isNonEmptyString(style.id) ? style.id : `styles.typography[${index}]`;
+  validateIdentity(style, entityId, "typography style", out);
+  if (typeof style.description !== "string") {
+    out.push(shape(entityId, "typography.description must be a string."));
+  }
+  if (!isRecord(style.properties)) {
+    out.push(shape(entityId, "typography.properties must be an object."));
+  } else {
+    for (const propertyName of TYPOGRAPHY_STYLE_PROPERTIES) {
+      validateStyleProperty(style.properties[propertyName], entityId, propertyName, out);
+    }
+    if (typeof style.properties.text_case !== "string") {
+      out.push(shape(entityId, "typography.properties.text_case must be a string."));
+    }
+    if (typeof style.properties.text_decoration !== "string") {
+      out.push(shape(entityId, "typography.properties.text_decoration must be a string."));
+    }
+  }
+  validateOptionalEntityMetadata(style, entityId, out, true);
+}
+var EFFECT_KINDS = ["drop_shadow", "inner_shadow", "layer_blur", "background_blur"];
+function validateEffect(effect, entityId, index, out) {
+  if (!isRecord(effect)) {
+    out.push(shape(entityId, `effects[${index}] must be an object.`));
+    return;
+  }
+  if (!EFFECT_KINDS.includes(effect.type)) {
+    out.push(shape(entityId, `effects[${index}].type is not a recognized effect kind.`));
+  }
+  if (typeof effect.visible !== "boolean") {
+    out.push(shape(entityId, `effects[${index}].visible must be a boolean.`));
+  }
+  if (effect.blend_mode !== void 0 && typeof effect.blend_mode !== "string") {
+    out.push(shape(entityId, `effects[${index}].blend_mode must be a string when present.`));
+  }
+  if (effect.color !== void 0) {
+    validateTypedValueEnvelope(effect.color, entityId, out, void 0, "color");
+  }
+  for (const field of ["offset_x", "offset_y", "blur", "spread"]) {
+    if (effect[field] !== void 0) {
+      validateTypedValueEnvelope(effect[field], entityId, out, void 0, "dimension");
+    }
+  }
+  if (effect.show_behind_node !== void 0 && typeof effect.show_behind_node !== "boolean") {
+    out.push(shape(entityId, `effects[${index}].show_behind_node must be a boolean when present.`));
+  }
+}
+function validateEffectStyle(style, index, out) {
+  if (!isRecord(style)) {
+    out.push(shape(`styles.effects[${index}]`, "An effect style must be an object."));
+    return;
+  }
+  const entityId = isNonEmptyString(style.id) ? style.id : `styles.effects[${index}]`;
+  validateIdentity(style, entityId, "effect style", out);
+  if (!(style.mode_id === null || typeof style.mode_id === "string")) {
+    out.push(shape(entityId, "effect style.mode_id must be a string or null."));
+  }
+  if (!Array.isArray(style.effects)) {
+    out.push(shape(entityId, "effect style.effects must be an array."));
+  } else {
+    style.effects.forEach((effect, effectIndex) => validateEffect(effect, entityId, effectIndex, out));
+  }
+  if (style.bindings !== void 0) {
+    if (!Array.isArray(style.bindings)) {
+      out.push(shape(entityId, "effect style.bindings must be an array when present."));
+    } else {
+      style.bindings.forEach((binding, bindingIndex) => {
+        if (!isRecord(binding) || !isNonEmptyString(binding.property) || !isNonEmptyString(binding.token_id)) {
+          out.push(shape(
+            entityId,
+            `effect style.bindings[${bindingIndex}] must carry non-empty property and token_id strings.`
+          ));
+        }
+      });
+    }
+  }
+  validateOptionalEntityMetadata(style, entityId, out, true);
+}
+var COMPLETENESS_VALUES = ["complete", "partial", "unavailable"];
+function validateRootSections(artifact, out) {
+  if (!isRecord(artifact.spec_layer)) {
+    out.push(shape(ROOT, "`spec_layer` must be an object."));
+  }
+  const completeness = artifact.completeness;
+  if (!isRecord(completeness) || !COMPLETENESS_VALUES.includes(completeness.collections) || !COMPLETENESS_VALUES.includes(completeness.styles) || !isStringArray(completeness.unavailable_sources)) {
+    out.push(shape(ROOT, "`completeness` must state collections/styles completeness and list unavailable sources."));
+  }
+  if (!Array.isArray(artifact.collections)) {
+    out.push(shape(ROOT, "`collections` must be an array."));
+  } else {
+    artifact.collections.forEach((collection, index) => validateCollection(collection, index, out));
+  }
+  if (!isRecord(artifact.styles) || !Array.isArray(artifact.styles.typography) || !Array.isArray(artifact.styles.effects)) {
+    out.push(shape(ROOT, "`styles` must be an object with `typography` and `effects` arrays."));
+  } else {
+    artifact.styles.typography.forEach((style, index) => validateTypographyStyle(style, index, out));
+    artifact.styles.effects.forEach((style, index) => validateEffectStyle(style, index, out));
+  }
+  if (!Array.isArray(artifact.diagnostics)) {
+    out.push(shape(ROOT, "`diagnostics` must be an array."));
+  }
+  if (!isRecord(artifact.statistics)) {
+    out.push(shape(ROOT, "`statistics` must be an object."));
+  }
+  if (artifact.guidelines !== void 0) {
+    const guidelines = artifact.guidelines;
+    if (!isRecord(guidelines) || guidelines.origin !== "generated" || !isRecord(guidelines.group_descriptions)) {
+      out.push(shape(
+        ROOT,
+        '`guidelines` must state origin "generated" and a group_descriptions object.'
+      ));
+    } else {
+      for (const [collectionName, folders] of Object.entries(guidelines.group_descriptions)) {
+        if (!isRecord(folders) || Object.values(folders).some((description) => typeof description !== "string")) {
+          out.push(shape(
+            ROOT,
+            `guidelines.group_descriptions[${JSON.stringify(collectionName)}] must map folder names to strings.`
+          ));
+        }
+      }
+    }
+  }
+}
+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/dtcg.ts
+function dtcgSegments(name) {
+  const segments = [];
+  const notes = [];
+  for (const raw of name.split("/")) {
+    const parts = raw.includes(".") ? raw.split(".") : [raw];
+    if (parts.length > 1) notes.push({ code: "segment_split", original: raw });
+    for (const part of parts) {
+      let out = part;
+      if (out === "") out = "_";
+      if (/[{}]/.test(out)) out = out.replace(/[{}]/g, "_");
+      if (out.startsWith("$")) out = `_${out}`;
+      if (out !== part) notes.push({ code: "name_escaped", original: part });
+      segments.push(out);
+    }
+  }
+  return { segments, notes };
+}
+var slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unnamed";
+var RESERVED_FILE_NAMES = [
+  "styles.typography.json",
+  "styles.effects.json",
+  "resolver.json",
+  "spec-layer.meta.json",
+  "report.json"
+];
+function fileNameFor(collection, mode, taken) {
+  const base = `${slug(collection.name)}.${slug(mode.name)}`;
+  let candidate = `${base}.json`;
+  let n = 1;
+  while (taken.has(candidate)) {
+    n += 1;
+    candidate = `${base}-${n}.json`;
+  }
+  taken.add(candidate);
+  return candidate;
+}
+function hexByte(n) {
+  return Math.round(n * 255).toString(16).padStart(2, "0");
+}
+function colorComponents(color) {
+  if (color.channels) return [color.channels[0], color.channels[1], color.channels[2]];
+  const at = (i) => canonicalNumber(parseInt(color.hex.slice(i, i + 2), 16) / 255);
+  return [at(1), at(3), at(5)];
+}
+function dtcgLiteral(value, scopes, style) {
+  switch (value.type) {
+    case "color": {
+      if (style === "legacy") {
+        const alpha = value.alpha === 1 ? "" : hexByte(value.alpha);
+        return { $type: "color", $value: `${value.hex}${alpha}` };
+      }
+      return {
+        $type: "color",
+        $value: {
+          colorSpace: "srgb",
+          components: colorComponents(value),
+          alpha: value.alpha,
+          hex: value.hex
+        }
+      };
+    }
+    case "dimension": {
+      if (value.unit !== "px" && value.unit !== "rem") {
+        return { omit: "unit_not_expressible", details: { unit: value.unit, number: value.number } };
+      }
+      return {
+        $type: "dimension",
+        $value: style === "legacy" ? `${value.number}${value.unit}` : { value: value.number, unit: value.unit }
+      };
+    }
+    case "duration":
+      return {
+        $type: "duration",
+        $value: style === "legacy" ? `${value.number}${value.unit}` : { value: value.number, unit: value.unit }
+      };
+    case "number":
+      return { $type: scopes.includes("FONT_WEIGHT") ? "fontWeight" : "number", $value: value.value };
+    case "cubic_bezier":
+      return { $type: "cubicBezier", $value: [...value.value] };
+    case "font_family":
+      return { $type: "fontFamily", $value: value.value };
+    case "string":
+    case "boolean":
+      return { omit: "type_not_expressible", details: { type: value.type } };
+    default: {
+      const exhaustive = value;
+      return exhaustive;
+    }
+  }
+}
+function setLeaf(tree, segments, leaf) {
+  let node = tree;
+  for (const seg of segments.slice(0, -1)) {
+    const next = node[seg];
+    if (typeof next !== "object" || next === null || Array.isArray(next)) node[seg] = {};
+    node = node[seg];
+  }
+  node[segments[segments.length - 1]] = leaf;
+}
+var KEY_ORDER = ["$type", "$value", "$description", "$deprecated", "$extensions"];
+function sortTree(value) {
+  if (Array.isArray(value)) return value.map(sortTree);
+  if (typeof value !== "object" || value === null) return value;
+  const rank = (k) => {
+    const i = KEY_ORDER.indexOf(k);
+    return i === -1 ? KEY_ORDER.length : i;
+  };
+  const keys = Object.keys(value).sort((a, b) => rank(a) - rank(b) || compareCodeUnits(a, b));
+  return Object.fromEntries(keys.map((k) => [k, sortTree(value[k])]));
+}
+function reportOnce(p, entry2) {
+  const key = JSON.stringify([entry2.code, entry2.path, entry2.mode ?? null, entry2.details]);
+  if (p.reportKeys.has(key)) return;
+  p.reportKeys.add(key);
+  p.report.push(entry2);
+}
+function indexPaths(p) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const token of p.artifact.tokens) {
+    const collection = p.collectionById.get(token.collection_id);
+    if (!collection) continue;
+    const head = dtcgSegments(collection.name);
+    const tail = dtcgSegments(token.name);
+    const segments = [...head.segments, ...tail.segments];
+    const path = segments.join(".");
+    p.segmentsById.set(token.id, segments);
+    for (const note of [...head.notes, ...tail.notes]) {
+      reportOnce(p, {
+        code: note.code,
+        severity: note.code === "segment_split" ? "info" : "warning",
+        path,
+        message: note.code === "segment_split" ? `The segment "${note.original}" contains "." and was split into nested groups.` : `The segment "${note.original}" contains a character DTCG forbids and was escaped.`,
+        details: { id: token.id, original: note.original }
+      });
+    }
+    owners.set(path, [...owners.get(path) ?? [], token]);
+  }
+  for (const [path, tokens] of owners) {
+    if (tokens.length === 1) {
+      p.pathById.set(tokens[0].id, path);
+      continue;
+    }
+    for (const token of tokens) {
+      p.omittedIds.add(token.id);
+      p.collidedIds.add(token.id);
+      reportOnce(p, {
+        code: "path_collision",
+        severity: "error",
+        path,
+        message: `${tokens.length} tokens share this DTCG path after escaping; all were omitted.`,
+        details: { id: token.id, ids: tokens.map((t) => t.id) }
+      });
+    }
+  }
+}
+function modeName(collection, modeId) {
+  return collection.modes.find((m) => m.id === modeId)?.name ?? modeId;
+}
+function unitOverrideFor(p, token, collection) {
+  const units = p.options.units;
+  if (!units) return void 0;
+  for (const key of Object.keys(units).sort(compareCodeUnits)) {
+    const slash = key.indexOf("/");
+    if (slash === -1 || key.slice(0, slash) !== collection.name) continue;
+    const glob = key.slice(slash + 1);
+    const escaped = glob.split("*").map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*");
+    if (new RegExp(`^${escaped}$`).test(token.name)) return units[key];
+  }
+  return void 0;
+}
+var STATED_NUMBER_SCOPES = ["FONT_WEIGHT", "OPACITY"];
+function projectedLiteral(p, token, resolved2, onOverrideConflict) {
+  const collection = p.collectionById.get(token.collection_id);
+  const override = collection ? unitOverrideFor(p, token, collection) : void 0;
+  let literal = resolved2;
+  if (override !== void 0 && literal.type === "number") {
+    if (token.scopes.some((s) => STATED_NUMBER_SCOPES.includes(s))) onOverrideConflict?.(override);
+    else literal = { type: "dimension", number: literal.value, unit: override };
+  }
+  return dtcgLiteral(literal, token.scopes, p.options.values);
+}
+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);
+}
+function modeLabels(collection) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const m of collection.modes) counts.set(m.name, (counts.get(m.name) ?? 0) + 1);
+  return new Map(collection.modes.map((m) => [m.id, counts.get(m.name) === 1 ? m.name : `${m.name} [${m.id}]`]));
+}
+function collectionLabels(collections) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const c of collections) counts.set(c.name, (counts.get(c.name) ?? 0) + 1);
+  return new Map(collections.map(
+    (c) => [c.id, counts.get(c.name) === 1 ? c.name : `${c.name} [${c.id}]`]
+  ));
+}
+function modeLabelOf(p, collection, modeId) {
+  return p.modeLabelsById.get(collection.id)?.get(modeId) ?? modeId;
+}
+var collectionLabelOf = (p, collection) => p.collectionLabelById.get(collection.id) ?? collection.name;
+function reportCollectionNameCollisions(p) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const collection of p.artifact.collections) {
+    owners.set(collection.name, [...owners.get(collection.name) ?? [], collection]);
+  }
+  for (const [name, collections] of owners) {
+    if (collections.length < 2) continue;
+    for (const collection of collections) {
+      reportOnce(p, {
+        code: "collection_name_collision",
+        severity: "warning",
+        path: collectionLabelOf(p, collection),
+        message: `${collections.length} collections are named "${name}"; the resolver labels each one by its id.`,
+        details: { id: collection.id, ids: collections.map((c) => c.id) }
+      });
+    }
+  }
+}
+function asJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function metaEntry(p, token, collection) {
+  const labels = p.modeLabelsById.get(collection.id) ?? modeLabels(collection);
+  const omitted = p.omittedIds.has(token.id);
+  const plain = (v) => {
+    if (v.kind === "literal" && (v.value.type === "boolean" || v.value.type === "string" || v.value.type === "number" || v.value.type === "font_family")) return v.value.value;
+    return asJson(v);
+  };
+  return {
+    id: token.id,
+    collection_id: token.collection_id,
+    type: token.type,
+    scopes: [...token.scopes],
+    ...token.code_syntax ? { code_syntax: token.code_syntax } : {},
+    ...token.publication ? { publication: token.publication } : {},
+    ...omitted ? {
+      omitted: true,
+      values: Object.fromEntries(Object.entries(token.values).map(([modeId, v]) => [labels.get(modeId) ?? modeId, plain(v)]))
+    } : {}
+  };
+}
+function reportDuplicateCodeSyntax(p) {
+  const owners = /* @__PURE__ */ new Map();
+  for (const token of p.artifact.tokens) {
+    for (const [platform, identifier] of Object.entries(token.code_syntax ?? {})) {
+      const key = JSON.stringify([platform, identifier]);
+      owners.set(key, [...owners.get(key) ?? [], token]);
+    }
+  }
+  for (const [key, tokens] of owners) {
+    if (tokens.length < 2) continue;
+    const [platform, identifier] = JSON.parse(key);
+    for (const token of tokens) {
+      reportOnce(p, {
+        code: "duplicate_code_syntax",
+        severity: "warning",
+        path: p.pathById.get(token.id) ?? p.segmentsById.get(token.id)?.join(".") ?? token.name,
+        message: `${tokens.length} tokens declare the ${platform} identifier "${identifier}".`,
+        details: { id: token.id, platform, identifier, ids: tokens.map((t) => t.id) }
+      });
+    }
+  }
+}
+var SPEC_LAYER_EXT = "com.spec-layer";
+function reportBindingDropped(p, path, property, targetId) {
+  reportOnce(p, {
+    code: "binding_dropped",
+    severity: "warning",
+    path,
+    message: `The ${property} property is bound to a token this export does not carry; the resolved literal is written instead.`,
+    details: {
+      property,
+      target_id: targetId,
+      reason: p.tokenIds.has(targetId) ? "target_omitted" : "target_unavailable"
+    }
+  });
+}
+function styleMember(p, property, scopes, path, name) {
+  if (property.source.kind === "alias" && property.source.target_id !== null) {
+    const targetId = property.source.target_id;
+    const target = p.omittedIds.has(targetId) ? void 0 : p.pathById.get(targetId);
+    if (target !== void 0) return { value: `{${target}}` };
+    reportBindingDropped(p, path, name, targetId);
+  }
+  if (property.resolved === null) {
+    reportOnce(p, {
+      code: "value_omitted",
+      severity: "warning",
+      path,
+      message: `The ${name} property has no resolved value and was omitted.`,
+      details: { property: name, reason: "source_unavailable" }
+    });
+    return null;
+  }
+  const converted = dtcgLiteral(property.resolved, scopes, p.options.values);
+  if ("omit" in converted) {
+    if (converted.omit === "unit_not_expressible") {
+      reportOnce(p, {
+        code: "unit_not_expressible",
+        severity: "info",
+        path,
+        message: `The ${name} unit is not a DTCG dimension unit; the value is kept under $extensions.`,
+        details: { property: name, ...converted.details }
+      });
+      const d = property.resolved;
+      return { extension: { value: d.number, unit: d.unit } };
+    }
+    reportOnce(p, {
+      code: "type_not_expressible",
+      severity: "warning",
+      path,
+      message: `The ${name} property has a type DTCG cannot state and was omitted.`,
+      details: { property: name, ...converted.details }
+    });
+    return null;
+  }
+  return { value: converted.$value };
+}
+var TYPOGRAPHY_MEMBERS = [
+  ["font_family", "fontFamily", []],
+  ["font_size", "fontSize", []],
+  ["font_weight", "fontWeight", ["FONT_WEIGHT"]],
+  ["line_height", "lineHeight", []],
+  ["letter_spacing", "letterSpacing", []]
+];
+var TYPOGRAPHY_EXTENSION_MEMBERS = [
+  ["paragraph_spacing", "paragraphSpacing"],
+  ["paragraph_indent", "paragraphIndent"]
+];
+function typographyLeaf(p, style, path) {
+  const value = {};
+  const ext = {};
+  for (const [key, name, scopes] of TYPOGRAPHY_MEMBERS) {
+    const property = style.properties[key];
+    if (key === "line_height" && property.resolved?.type === "dimension") {
+      const boundTo = property.source.kind === "alias" ? property.source.target_id : null;
+      let targetExported = false;
+      if (property.resolved.unit === "%" && boundTo !== null) {
+        targetExported = !p.omittedIds.has(boundTo) && p.pathById.get(boundTo) !== void 0;
+        if (!targetExported) reportBindingDropped(p, path, name, boundTo);
+      }
+      if (property.resolved.unit === "%" && !targetExported) {
+        value[name] = canonicalNumber(property.resolved.number / 100);
+        continue;
+      }
+      reportOnce(p, {
+        code: "unit_not_expressible",
+        severity: "info",
+        path,
+        message: "DTCG line height is a unitless multiplier of the font size; the measured value is kept under $extensions.",
+        // The binding is replaced by a literal here, so the entry names the
+        // target it stood for; without it a consumer cannot tell this value
+        // was bound at all.
+        details: {
+          property: name,
+          unit: property.resolved.unit,
+          number: property.resolved.number,
+          ...boundTo !== null ? { target_id: boundTo } : {}
+        }
+      });
+      ext[name] = { value: property.resolved.number, unit: property.resolved.unit };
+      continue;
+    }
+    const member = styleMember(p, property, scopes, path, name);
+    if (member === null) continue;
+    if ("value" in member) value[name] = member.value;
+    else ext[name] = member.extension;
+  }
+  for (const [key, name] of TYPOGRAPHY_EXTENSION_MEMBERS) {
+    const member = styleMember(p, style.properties[key], [], path, name);
+    if (member === null) continue;
+    ext[name] = "value" in member ? member.value : member.extension;
+  }
+  ext.textCase = style.properties.text_case;
+  ext.textDecoration = style.properties.text_decoration;
+  return {
+    $type: "typography",
+    $value: value,
+    ...style.description.length > 0 ? { $description: style.description } : {},
+    $extensions: { [SPEC_LAYER_EXT]: ext }
+  };
+}
+var SHADOW_FIELDS = [
+  ["color", "color"],
+  ["offset_x", "offsetX"],
+  ["offset_y", "offsetY"],
+  ["blur", "blur"],
+  ["spread", "spread"]
+];
+function effectLeaf(p, style, path) {
+  const bindings = new Map((style.bindings ?? []).map((b) => [b.property, b.token_id]));
+  const shadows = [];
+  const layers = [];
+  style.effects.forEach((effect, index) => {
+    const isShadow = effect.type === "drop_shadow" || effect.type === "inner_shadow";
+    const layer = { index, type: effect.type, visible: effect.visible };
+    if (effect.blend_mode !== void 0) layer.blend_mode = effect.blend_mode;
+    if (!isShadow && effect.blur) {
+      const b = dtcgLiteral(effect.blur, [], p.options.values);
+      if (!("omit" in b)) layer.blur = b.$value;
+    }
+    layers.push(layer);
+    if (!isShadow || !effect.visible) return;
+    const shadow = {};
+    for (const [field, name] of SHADOW_FIELDS) {
+      const boundId = bindings.get(`effects[${index}].${field}`);
+      const boundPath = boundId !== void 0 && !p.omittedIds.has(boundId) ? p.pathById.get(boundId) : void 0;
+      if (boundPath !== void 0) {
+        shadow[name] = `{${boundPath}}`;
+        continue;
+      }
+      if (boundId !== void 0) {
+        reportBindingDropped(p, path, `effects[${index}].${field}`, boundId);
+      }
+      const raw = effect[field];
+      if (raw === void 0) continue;
+      const converted = dtcgLiteral(raw, [], p.options.values);
+      if (!("omit" in converted)) shadow[name] = converted.$value;
+    }
+    shadow.inset = effect.type === "inner_shadow";
+    shadows.push(shadow);
+  });
+  if (shadows.length === 0) {
+    reportOnce(p, {
+      code: "effect_not_expressible",
+      severity: "warning",
+      path,
+      message: "The style has no visible shadow; DTCG has no blur type, so it is kept only under $extensions.",
+      details: { id: style.id }
+    });
+  }
+  return {
+    $type: "shadow",
+    $value: shadows,
+    $extensions: { [SPEC_LAYER_EXT]: { layers } }
+  };
+}
+function styleFiles(p) {
+  const files = {};
+  const build = (styles, root, file, leafOf) => {
+    if (styles.length === 0) return;
+    const tree = {};
+    const seen = /* @__PURE__ */ new Map();
+    for (const style of styles) {
+      const segments = [root, ...dtcgSegments(style.name).segments];
+      const path = segments.join(".");
+      const other = seen.get(path);
+      if (other !== void 0) {
+        reportOnce(p, {
+          code: "path_collision",
+          severity: "error",
+          path,
+          message: "Two styles share this DTCG path after escaping; the later one was omitted.",
+          details: { id: style.id, ids: [other, style.id] }
+        });
+        continue;
+      }
+      seen.set(path, style.id);
+      setLeaf(tree, segments, leafOf(style, path));
+    }
+    files[file] = sortTree(tree);
+  };
+  build(
+    p.artifact.styles.typography,
+    "Typography styles",
+    "styles.typography.json",
+    (s, path) => typographyLeaf(p, s, path)
+  );
+  build(
+    p.artifact.styles.effects,
+    "Effect styles",
+    "styles.effects.json",
+    (s, path) => effectLeaf(p, s, path)
+  );
+  return files;
+}
+var pointer = (s) => s.replace(/~/g, "~0").replace(/\//g, "~1");
+var STYLE_ROOTS = {
+  "styles.typography.json": "Typography styles",
+  "styles.effects.json": "Effect styles"
+};
+function buildResolver(p, plans, styleFileNames) {
+  const sets = {};
+  const modifiers = {};
+  const order = [];
+  for (const collection of p.artifact.collections) {
+    const own = plans.filter((f) => f.collection.id === collection.id);
+    if (own.length === 0) continue;
+    const labels = p.modeLabelsById.get(collection.id) ?? modeLabels(collection);
+    const label = collectionLabelOf(p, collection);
+    if (own.length === 1) {
+      sets[label] = { sources: [{ $ref: own[0].file }] };
+      order.push({ $ref: `#/sets/${pointer(label)}` });
+      continue;
+    }
+    const contexts = {};
+    for (const plan of own) contexts[labels.get(plan.modeId) ?? plan.modeId] = [{ $ref: plan.file }];
+    const def = labels.get(collection.default_mode_id);
+    modifiers[label] = { contexts, ...def !== void 0 ? { default: def } : {} };
+    order.push({ $ref: `#/modifiers/${pointer(label)}` });
+  }
+  for (const file of styleFileNames) {
+    const root = STYLE_ROOTS[file];
+    sets[root] = { sources: [{ $ref: file }] };
+    order.push({ $ref: `#/sets/${pointer(root)}` });
+  }
+  const fileName = p.artifact.spec_layer.source.file_name;
+  return {
+    version: "2025.10",
+    ...typeof fileName === "string" && fileName.length > 0 ? { name: fileName } : {},
+    sets,
+    modifiers,
+    resolutionOrder: order
+  };
+}
+function annotateGroups(p, tree, collection) {
+  const groups = p.artifact.guidelines?.group_descriptions[collection.name];
+  if (!groups) return;
+  const head = dtcgSegments(collection.name).segments;
+  folders: for (const [folder, text] of Object.entries(groups)) {
+    if (text.length === 0) continue;
+    let node = tree;
+    for (const seg of [...head, ...dtcgSegments(folder).segments]) {
+      if (typeof node !== "object" || node === null || Array.isArray(node)) continue folders;
+      node = node[seg];
+    }
+    if (typeof node === "object" && node !== null && !Array.isArray(node) && !("$value" in node)) {
+      node.$description = text;
+    }
+  }
+}
+function foundationDtcg(artifact, options = {}) {
+  const p = {
+    artifact,
+    options: { values: options.values ?? "standard", ...options.units ? { units: options.units } : {} },
+    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])),
+    collectionLabelById: collectionLabels(artifact.collections),
+    modeLabelsById: new Map(artifact.collections.map((c) => [c.id, modeLabels(c)])),
+    pathById: /* @__PURE__ */ new Map(),
+    segmentsById: /* @__PURE__ */ new Map(),
+    omittedIds: /* @__PURE__ */ new Set(),
+    collidedIds: /* @__PURE__ */ new Set(),
+    report: [],
+    reportKeys: /* @__PURE__ */ new Set()
+  };
+  indexPaths(p);
+  omitInexpressibleTypes(p);
+  reportDuplicateCodeSyntax(p);
+  reportCollectionNameCollisions(p);
+  const files = {};
+  const plans = [];
+  const taken = new Set(RESERVED_FILE_NAMES);
+  for (const collection of artifact.collections) {
+    for (const mode of collection.modes) {
+      const tree = {};
+      for (const token of artifact.tokens) {
+        if (token.collection_id !== collection.id || p.omittedIds.has(token.id)) continue;
+        const leaf = tokenLeaf(p, token, collection, mode.id);
+        if (leaf) setLeaf(tree, p.segmentsById.get(token.id) ?? [], leaf);
+      }
+      annotateGroups(p, tree, collection);
+      const file = fileNameFor(collection, mode, taken);
+      plans.push({ collection, modeId: mode.id, file });
+      files[file] = sortTree(tree);
+    }
+  }
+  const styles = styleFiles(p);
+  Object.assign(files, styles);
+  const resolver = buildResolver(p, plans, Object.keys(styles).sort(compareCodeUnits));
+  p.report.sort((a, b) => compareCodeUnits(a.path, b.path) || compareCodeUnits(a.code, b.code) || compareCodeUnits(a.mode ?? "", b.mode ?? ""));
+  const meta = {};
+  for (const token of artifact.tokens) {
+    const collection = p.collectionById.get(token.collection_id);
+    if (!collection) continue;
+    const path = p.pathById.get(token.id) ?? p.segmentsById.get(token.id)?.join(".") ?? token.name;
+    meta[p.collidedIds.has(token.id) ? `${path} [${token.id}]` : path] = metaEntry(p, token, collection);
+  }
+  const sortedMeta = Object.fromEntries(Object.entries(meta).sort(([a], [b]) => compareCodeUnits(a, b)));
+  return { files, resolver, meta: sortedMeta, report: p.report };
+}
+function omitInexpressibleTypes(p) {
+  for (const token of p.artifact.tokens) {
+    if (token.type !== "string" && token.type !== "boolean") continue;
+    p.omittedIds.add(token.id);
+    reportOnce(p, {
+      code: "type_not_expressible",
+      severity: "warning",
+      path: p.pathById.get(token.id) ?? p.segmentsById.get(token.id)?.join(".") ?? token.name,
+      message: `DTCG has no ${token.type} type; the token was omitted.`,
+      details: { id: token.id, type: token.type }
+    });
+  }
+}
+function tokenLeaf(p, token, collection, modeId) {
+  const value = token.values[modeId];
+  const path = p.pathById.get(token.id) ?? "";
+  const mode = modeLabelOf(p, collection, modeId);
+  const description = token.description.length > 0 ? { $description: token.description } : {};
+  if (value === void 0 || value.kind === "missing") {
+    reportOnce(p, {
+      code: "value_omitted",
+      severity: "warning",
+      path,
+      mode,
+      message: "The token has no value for this mode.",
+      details: { id: token.id, reason: value?.reason ?? "no_value_for_mode" }
+    });
+    return null;
+  }
+  if (value.kind === "alias") {
+    if (value.resolved.status === "unresolved") {
+      reportOnce(p, {
+        code: "value_omitted",
+        severity: "warning",
+        path,
+        mode,
+        message: `The alias could not be resolved (${value.resolved.reason}); no value was written.`,
+        details: {
+          id: token.id,
+          reason: value.resolved.reason,
+          target_path: value.reference.target_path.join("/"),
+          ...value.reference.target_id !== null ? { target_id: value.reference.target_id } : {},
+          ...value.reference.source_library_name ? { source_library_name: value.reference.source_library_name } : {}
+        }
+      });
+      return null;
+    }
+    const targetId = value.reference.target_id;
+    const targetPath = targetId !== null && !p.omittedIds.has(targetId) ? p.pathById.get(targetId) : void 0;
+    if (targetPath === void 0) {
+      reportOnce(p, {
+        code: "value_omitted",
+        severity: "warning",
+        path,
+        mode,
+        message: "The alias target was itself omitted from the DTCG output.",
+        details: {
+          id: token.id,
+          reason: "target_omitted",
+          target_path: value.reference.target_path.join("/"),
+          ...targetId !== null ? { target_id: targetId } : {},
+          ...value.reference.source_library_name ? { source_library_name: value.reference.source_library_name } : {}
+        }
+      });
+      return null;
+    }
+    const target = targetId !== null ? p.tokenById.get(targetId) : void 0;
+    const hop = value.resolved.chain[0];
+    if (target && hop && target.collection_id !== token.collection_id) {
+      const targetCollection = p.collectionById.get(target.collection_id);
+      if (targetCollection !== void 0 && targetCollection.modes.length > 1 && modeName(targetCollection, hop.mode_id) !== modeName(collection, modeId)) {
+        const hopMode = modeLabelOf(p, targetCollection, hop.mode_id);
+        reportOnce(p, {
+          code: "mode_selection_not_expressible",
+          severity: "info",
+          path,
+          mode,
+          message: `Figma resolved this alias through the target's "${hopMode}" mode; DTCG resolves it by the consumer's context.`,
+          details: {
+            id: token.id,
+            target_id: targetId ?? "",
+            target_mode: hopMode,
+            resolved: asJson(value.resolved.value)
+          }
+        });
+      }
+    }
+    const typed = aliasLeafType(p, token, value.resolved.chain, value.resolved.value);
+    if ("omit" in typed) {
+      reportOnce(p, {
+        code: typed.omit,
+        severity: "warning",
+        path,
+        mode,
+        message: "The alias resolves to a value DTCG cannot state; the value was omitted.",
+        details: { id: token.id, ...typed.details }
+      });
+      return null;
+    }
+    return { $type: typed.$type, $value: `{${targetPath}}`, ...description };
+  }
+  const converted = 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] }
+    });
+  });
+  if ("omit" in converted) {
+    reportOnce(p, {
+      code: converted.omit,
+      severity: "warning",
+      path,
+      mode,
+      message: converted.omit === "type_not_expressible" ? `DTCG has no ${String(converted.details.type)} type; the value was omitted.` : `DTCG dimensions take px or rem; a ${String(converted.details.unit)} value was omitted.`,
+      details: { id: token.id, ...converted.details }
+    });
+    return null;
+  }
+  return { $type: converted.$type, $value: converted.$value, ...description };
+}
+function dtcgExportFiles(out) {
+  const text = (v) => `${JSON.stringify(v, null, 2)}
+`;
+  const files = {};
+  for (const name of Object.keys(out.files).sort(compareCodeUnits)) files[name] = text(out.files[name]);
+  files["resolver.json"] = text(out.resolver);
+  files["spec-layer.meta.json"] = text(out.meta);
+  files["report.json"] = text(out.report);
+  return files;
+}
+
 // ../extractor/src/v5/componentContext.ts
 var import_js_sha2563 = __toESM(require_sha256(), 1);
 
@@ -748,14 +2045,14 @@ var LibraryBundleError = class extends Error {
     this.code = code;
   }
 };
-var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
 function hasContentHash(artifact) {
-  if (!isRecord(artifact) || !isRecord(artifact.spec_layer)) return false;
+  if (!isRecord2(artifact) || !isRecord2(artifact.spec_layer)) return false;
   const exp = artifact.spec_layer.export;
-  return isRecord(exp) && typeof exp.content_hash === "string";
+  return isRecord2(exp) && typeof exp.content_hash === "string";
 }
 function entry(v, where) {
-  if (!isRecord(v) || typeof v.name !== "string" || typeof v.ai !== "string" || !hasContentHash(v.artifact)) {
+  if (!isRecord2(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 };
@@ -772,7 +2069,7 @@ function parseLibraryBundle(input) {
       throw new LibraryBundleError("not_json", "This is not valid JSON.");
     }
   }
-  if (!isRecord(parsed) || parsed.schema !== LIBRARY_BUNDLE_SCHEMA) {
+  if (!isRecord2(parsed) || parsed.schema !== LIBRARY_BUNDLE_SCHEMA) {
     throw new LibraryBundleError("not_bundle", "This is not a Spec Layer library bundle.");
   }
   if (!supportedVersion(parsed.version)) {
@@ -788,7 +2085,7 @@ function parseLibraryBundle(input) {
   const foundationRaw = parsed.foundation ?? null;
   let foundation = null;
   if (foundationRaw !== null) {
-    if (!isRecord(foundationRaw) || typeof foundationRaw.ai !== "string" || !hasContentHash(foundationRaw.artifact)) {
+    if (!isRecord2(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 };
@@ -824,8 +2121,41 @@ function parseBundle(raw) {
 }
 
 // src/config.ts
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+
+// src/credentials.ts
+import { readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
 import { join } from "node:path";
+var CREDENTIALS_NAME = "speclayer.local.json";
+var unreadable = () => new Error(
+  `${CREDENTIALS_NAME} cannot be read. Delete it, then run the setup command from the plugin's Library screen.`
+);
+function readCredentials(cwd) {
+  const path = join(cwd, CREDENTIALS_NAME);
+  if (!existsSync(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    throw unreadable();
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw unreadable();
+  const record = parsed;
+  if (typeof record.libraryId !== "string" || typeof record.key !== "string") throw unreadable();
+  return { libraryId: record.libraryId, key: record.key };
+}
+function writeCredentials(cwd, stored) {
+  const path = join(cwd, CREDENTIALS_NAME);
+  const replaced = existsSync(path);
+  const body = { libraryId: stored.libraryId, key: stored.key };
+  writeFileSync(path, `${JSON.stringify(body, null, 2)}
+`, { mode: 384 });
+  chmodSync(path, 384);
+  return { replaced };
+}
+
+// src/config.ts
 var DEFAULT_API = "https://api.spec-layer.com";
 var DEFAULT_OUT_DIR = ".speclayer";
 var CONFIG_NAME = "speclayer.json";
@@ -842,12 +2172,29 @@ function parseInclude(value) {
     components: record.components === void 0 ? null : record.components
   };
 }
+function parseDtcg(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalidConfig();
+  const record = value;
+  const out = {};
+  if (record.values !== void 0) {
+    if (record.values !== "standard" && record.values !== "legacy") throw invalidConfig();
+    out.values = record.values;
+  }
+  if (record.units !== void 0) {
+    if (typeof record.units !== "object" || record.units === null || Array.isArray(record.units)) throw invalidConfig();
+    for (const unit of Object.values(record.units)) {
+      if (unit !== "px" && unit !== "rem") throw invalidConfig();
+    }
+    out.units = record.units;
+  }
+  return out;
+}
 function readConfig(cwd) {
-  const path = join(cwd, CONFIG_NAME);
-  if (!existsSync(path)) return null;
+  const path = join2(cwd, CONFIG_NAME);
+  if (!existsSync2(path)) return null;
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync(path, "utf8"));
+    parsed = JSON.parse(readFileSync2(path, "utf8"));
   } catch {
     throw invalidConfig();
   }
@@ -856,29 +2203,43 @@ function readConfig(cwd) {
   return {
     ...typeof record.libraryId === "string" ? { libraryId: record.libraryId } : {},
     ...typeof record.outDir === "string" ? { outDir: record.outDir } : {},
-    ...record.include !== void 0 ? { include: parseInclude(record.include) } : {}
+    ...record.include !== void 0 ? { include: parseInclude(record.include) } : {},
+    ...record.dtcg !== void 0 ? { dtcg: parseDtcg(record.dtcg) } : {}
   };
 }
 function writeConfig(cwd, config) {
   const body = {
     libraryId: config.libraryId,
     outDir: config.outDir,
-    ...config.include ? { include: config.include } : {}
+    ...config.include ? { include: config.include } : {},
+    ...config.dtcg ? { dtcg: config.dtcg } : {}
   };
-  writeFileSync(join(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
+  writeFileSync2(join2(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
 `);
 }
 function resolveOptions(cwd, flags, env, manifestLibraryId) {
   const config = readConfig(cwd);
   const outDir = flags.out ?? config?.outDir ?? DEFAULT_OUT_DIR;
-  const libraryId = flags.id ?? config?.libraryId ?? manifestLibraryId(join(cwd, outDir));
+  const libraryId = flags.id ?? config?.libraryId ?? manifestLibraryId(join2(cwd, outDir));
+  const supplied = flags.key || env.SPEC_LAYER_KEY || null;
+  let storedKey = null;
+  let storedKeyFor;
+  if (!supplied) {
+    const stored = readCredentials(cwd);
+    if (stored) {
+      if (libraryId && stored.libraryId === libraryId) storedKey = stored.key || null;
+      else storedKeyFor = stored.libraryId;
+    }
+  }
   return {
     libraryId,
     outDir,
     // A trailing slash would build "//v1/..." paths the proxy router 404s on.
     api: (flags.api ?? env.SPEC_LAYER_API ?? DEFAULT_API).replace(/\/+$/, ""),
-    key: flags.key ?? env.SPEC_LAYER_KEY ?? null,
-    ...config?.include ? { include: config.include } : {}
+    key: supplied ?? storedKey,
+    ...config?.include ? { include: config.include } : {},
+    ...config?.dtcg ? { dtcg: config.dtcg } : {},
+    ...storedKeyFor ? { storedKeyFor } : {}
   };
 }
 
@@ -899,7 +2260,10 @@ async function fetchBundle(opts) {
   }
   if (res.status === 304) return { kind: "not_modified" };
   if (res.status === 401) {
-    return { kind: "error", message: "Key was rotated or revoked. Ask the publisher for the current key." };
+    return {
+      kind: "error",
+      message: "Key was rotated or revoked. Run the setup command from the plugin's Library screen to store the current key."
+    };
   }
   if (res.status === 404) return { kind: "error", message: "Library not found. It may have been unpublished." };
   if (!res.ok) return { kind: "error", message: `Request failed with HTTP ${res.status}.` };
@@ -913,8 +2277,8 @@ async function fetchBundle(opts) {
 }
 
 // src/files.ts
-import { mkdirSync, writeFileSync as writeFileSync2, readFileSync as readFileSync2, readdirSync, rmSync, renameSync, existsSync as existsSync2 } from "node:fs";
-import { join as join2, dirname, relative, resolve, isAbsolute } from "node:path";
+import { mkdirSync, writeFileSync as writeFileSync3, readFileSync as readFileSync3, readdirSync, rmSync, renameSync, existsSync as existsSync3 } from "node:fs";
+import { join as join3, dirname, relative, resolve, isAbsolute } from "node:path";
 
 // src/selection.ts
 var DEFAULT_SELECTION = { foundation: true, components: null };
@@ -949,23 +2313,23 @@ Available: ${available || "none"}.`
 
 // src/files.ts
 function slugify(name) {
-  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-  return slug || "component";
+  const slug2 = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return slug2 || "component";
 }
 function readManifest(outDir) {
-  const path = join2(outDir, "manifest.json");
-  if (!existsSync2(path)) return null;
+  const path = join3(outDir, "manifest.json");
+  if (!existsSync3(path)) return null;
   try {
-    return JSON.parse(readFileSync2(path, "utf8"));
+    return JSON.parse(readFileSync3(path, "utf8"));
   } catch {
     return null;
   }
 }
 function readLocalBundle(outDir) {
-  const path = join2(outDir, "bundle.json");
-  if (!existsSync2(path)) return null;
+  const path = join3(outDir, "bundle.json");
+  if (!existsSync3(path)) return null;
   try {
-    return parseBundle(readFileSync2(path, "utf8"));
+    return parseBundle(readFileSync3(path, "utf8"));
   } catch {
     throw new Error(`${path} could not be read as a library bundle. Run spec-layer pull again.`);
   }
@@ -975,20 +2339,20 @@ function componentSlugs(bundle) {
   const nextSuffix = /* @__PURE__ */ new Map();
   return bundle.components.map((component) => {
     const base = slugify(component.name);
-    let slug = base;
-    if (usedSlugs.has(slug)) {
+    let slug2 = base;
+    if (usedSlugs.has(slug2)) {
       let n = (nextSuffix.get(base) ?? 1) + 1;
-      slug = `${base}-${n}`;
-      while (usedSlugs.has(slug)) {
+      slug2 = `${base}-${n}`;
+      while (usedSlugs.has(slug2)) {
         n += 1;
-        slug = `${base}-${n}`;
+        slug2 = `${base}-${n}`;
       }
       nextSuffix.set(base, n);
     } else {
       nextSuffix.set(base, 1);
     }
-    usedSlugs.add(slug);
-    return slug;
+    usedSlugs.add(slug2);
+    return slug2;
   });
 }
 function assertReplaceable(outDir, cwd) {
@@ -996,7 +2360,7 @@ function assertReplaceable(outDir, cwd) {
   if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
     throw new Error('The output directory must sit inside the current directory, not be "." or a parent of it.');
   }
-  if (existsSync2(outDir) && !existsSync2(join2(outDir, "manifest.json")) && readdirSync(outDir).length > 0) {
+  if (existsSync3(outDir) && !existsSync3(join3(outDir, "manifest.json")) && readdirSync(outDir).length > 0) {
     throw new Error(`${outDir} exists and was not written by spec-layer pull. Choose an empty or new directory.`);
   }
 }
@@ -1009,17 +2373,25 @@ function writeBundleFiles(opts) {
   rmSync(staging, { recursive: true, force: true });
   const written = [];
   const put = (rel, content) => {
-    const path = join2(staging, rel);
+    const path = join3(staging, rel);
     mkdirSync(dirname(path), { recursive: true });
-    writeFileSync2(path, content);
+    writeFileSync3(path, content);
     written.push(rel);
   };
   try {
     put("bundle.json", opts.raw);
     const artifacts = [];
     if (opts.bundle.foundation) {
-      const aiPath = selection.foundation ? "ai/foundation.yaml" : null;
-      if (aiPath) put(aiPath, opts.bundle.foundation.ai);
+      let aiPath = null;
+      if (selection.foundation) {
+        const artifact = opts.bundle.foundation.artifact;
+        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 files = dtcgExportFiles(foundationDtcg(artifact, opts.dtcg ?? {}));
+        for (const [name, text] of Object.entries(files)) put(`tokens/${name}`, text);
+        aiPath = "tokens/resolver.json";
+      }
       artifacts.push({
         kind: "foundation",
         name: "foundation",
@@ -1044,7 +2416,8 @@ function writeBundleFiles(opts) {
       pluginVersion: opts.bundle.pluginVersion,
       extractorVersion: opts.bundle.extractorVersion,
       selection,
-      artifacts
+      artifacts,
+      ...opts.dtcg && Object.keys(opts.dtcg).length > 0 ? { dtcg: opts.dtcg } : {}
     };
     put("manifest.json", `${JSON.stringify(manifest, null, 2)}
 `);
@@ -1057,6 +2430,60 @@ function writeBundleFiles(opts) {
   return written;
 }
 
+// src/gitignore.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync4 } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join as join4, dirname as dirname2, resolve as resolve2 } from "node:path";
+var COMMENT = "# Spec Layer pull key, not for committing";
+function git(cwd, args) {
+  const res = spawnSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" });
+  if (res.error || res.status === null) return { ranGit: false };
+  return { ranGit: true, status: res.status, stdout: res.stdout ?? "" };
+}
+function insideWorkTreeWithoutGit(cwd) {
+  let dir = resolve2(cwd);
+  for (; ; ) {
+    if (existsSync4(join4(dir, ".git"))) return true;
+    const parent = dirname2(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+function hasEntryLine(body, fileName) {
+  return body.split("\n").some((line) => line.trim() === fileName);
+}
+function ensureIgnored(cwd, fileName) {
+  const inWorkTree = git(cwd, ["rev-parse", "--is-inside-work-tree"]);
+  if (!inWorkTree.ranGit) {
+    return insideWorkTreeWithoutGit(cwd) ? { kind: "no-git", line: fileName } : { kind: "not-a-repo" };
+  }
+  if (inWorkTree.status !== 0 || inWorkTree.stdout.trim() !== "true") return { kind: "not-a-repo" };
+  const checkIgnore = git(cwd, ["check-ignore", "-q", fileName]);
+  if (checkIgnore.ranGit && checkIgnore.status === 0) return { kind: "already" };
+  const path = join4(cwd, ".gitignore");
+  const existed = existsSync4(path);
+  try {
+    if (!existed) {
+      writeFileSync4(path, `${COMMENT}
+${fileName}
+`);
+    } else {
+      const body = readFileSync4(path, "utf8");
+      if (!hasEntryLine(body, fileName)) {
+        const lead = body.length === 0 || body.endsWith("\n") ? "" : "\n";
+        writeFileSync4(path, `${body}${lead}${COMMENT}
+${fileName}
+`);
+      }
+    }
+  } catch {
+    return { kind: "refused", line: fileName };
+  }
+  const recheck = git(cwd, ["check-ignore", "-q", fileName]);
+  if (!recheck.ranGit || recheck.status !== 0) return { kind: "still-not-ignored", line: fileName };
+  return existed ? { kind: "added" } : { kind: "created" };
+}
+
 // src/commands.ts
 var NO_LOCAL_PULL = "No local pull found. Run spec-layer pull.";
 function manifestReader() {
@@ -1066,9 +2493,17 @@ function manifestReader() {
     return cache.get(outDir) ?? null;
   };
 }
-function sameSelection(a, b) {
-  const key = (s) => JSON.stringify([s.foundation, s.components === null ? null : [...new Set(s.components.map(slugify))].sort()]);
-  return key(a) === key(b);
+function sameOutput(a, b) {
+  const selectionKey = (s) => JSON.stringify([s.foundation, s.components === null ? null : [...new Set(s.components.map(slugify))].sort()]);
+  const dtcgKey = (d) => JSON.stringify(sortKeys(d ?? {}));
+  return selectionKey(a.selection) === selectionKey(b.selection) && dtcgKey(a.dtcg) === dtcgKey(b.dtcg);
+}
+function sortKeys(value) {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((k) => [k, sortKeys(value[k])]));
+  }
+  return value;
 }
 var errorText = (err) => err instanceof Error ? err.message : String(err);
 function runInit(cwd, flags, io2) {
@@ -1086,7 +2521,7 @@ function runInit(cwd, flags, io2) {
   const outDir = flags.out ?? DEFAULT_OUT_DIR;
   writeConfig(cwd, { libraryId: flags.id, outDir, ...include ? { include } : {} });
   io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}).`);
-  io2.out("The pull key is never stored here. Set SPEC_LAYER_KEY in your environment or pass --key.");
+  io2.out(`The pull key is not stored here. Run spec-layer setup to store it in ${CREDENTIALS_NAME}, or set SPEC_LAYER_KEY.`);
   return 0;
 }
 function resolved(cwd, flags, env, io2, manifestAt) {
@@ -1098,18 +2533,18 @@ function resolved(cwd, flags, env, io2, manifestAt) {
     return null;
   }
   if (!opts.libraryId) {
-    io2.err("No library id. Pass --id lib_..., or run spec-layer init first.");
+    io2.err(opts.storedKeyFor ? `No library id. ${CREDENTIALS_NAME} holds a key for library ${opts.storedKeyFor}. Pass --id ${opts.storedKeyFor}, or run spec-layer init first.` : "No library id. Pass --id lib_..., or run spec-layer init first.");
     return null;
   }
   if (!opts.key) {
-    io2.err("No pull key. Set SPEC_LAYER_KEY or pass --key.");
+    io2.err(opts.storedKeyFor ? `The key in ${CREDENTIALS_NAME} was issued for library ${opts.storedKeyFor}, not ${opts.libraryId}. Run the setup command from the plugin's Library screen.` : "No pull key. Run the setup command from the plugin's Library screen, or set SPEC_LAYER_KEY.");
     return null;
   }
   return opts;
 }
 function resolvedOutDir(cwd, flags, io2) {
   try {
-    return join3(cwd, flags.out ?? readConfig(cwd)?.outDir ?? DEFAULT_OUT_DIR);
+    return join5(cwd, flags.out ?? readConfig(cwd)?.outDir ?? DEFAULT_OUT_DIR);
   } catch (err) {
     io2.err(errorText(err));
     return null;
@@ -1122,6 +2557,78 @@ function describePull(bundle, selection, selected) {
   if (!bundle.foundation) return components;
   return selection.foundation ? `foundation + ${components}` : `${components}, no foundation`;
 }
+async function runSetup(cwd, flags, env, io2, fetcher) {
+  if (!flags.id) {
+    io2.err("spec-layer setup needs --id lib_... (shown in the plugin after publishing).");
+    return 1;
+  }
+  const key = flags.key ?? env.SPEC_LAYER_KEY;
+  if (!key) {
+    io2.err("spec-layer setup needs --key sl_..., or SPEC_LAYER_KEY in the environment.");
+    return 1;
+  }
+  let include;
+  try {
+    include = selectionFromFlags(flags);
+  } catch (err) {
+    io2.err(errorText(err));
+    return 1;
+  }
+  let existing = null;
+  try {
+    existing = readConfig(cwd);
+  } catch {
+    existing = null;
+  }
+  const outDir = flags.out ?? existing?.outDir ?? DEFAULT_OUT_DIR;
+  const keptInclude = include ?? existing?.include ?? null;
+  const keptDtcg = existing?.dtcg ?? null;
+  writeConfig(cwd, {
+    libraryId: flags.id,
+    outDir,
+    ...keptInclude ? { include: keptInclude } : {},
+    ...keptDtcg ? { dtcg: keptDtcg } : {}
+  });
+  io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}).`);
+  const ignored = ensureIgnored(cwd, CREDENTIALS_NAME);
+  switch (ignored.kind) {
+    case "refused":
+      io2.err(`Could not add ${CREDENTIALS_NAME} to .gitignore, so the key was not written.`);
+      io2.err(`Add this line to .gitignore, then run the command again:
+${ignored.line}`);
+      return 1;
+    case "no-git":
+      io2.err(`Could not run git, so it could not confirm ${CREDENTIALS_NAME} would be ignored. The key was not written.`);
+      io2.err(`Add this line to .gitignore, then run the command again:
+${ignored.line}`);
+      return 1;
+    case "still-not-ignored":
+      io2.err(`${ignored.line} is listed in .gitignore, but git still does not ignore it, so the key was not written.`);
+      io2.err(`The most likely reason is that ${ignored.line} is already tracked. Run this, then run the command again:
+git rm --cached ${ignored.line}`);
+      return 1;
+    case "created":
+      io2.out(`Created .gitignore with ${CREDENTIALS_NAME}.`);
+      break;
+    case "added":
+      io2.out(`Added ${CREDENTIALS_NAME} to .gitignore.`);
+      break;
+    case "already":
+      io2.out(`${CREDENTIALS_NAME} is already ignored by git.`);
+      break;
+    case "not-a-repo":
+      io2.out("Not a git repository, so .gitignore was left alone.");
+      break;
+    default: {
+      const exhaustive = ignored;
+      void exhaustive;
+      return 1;
+    }
+  }
+  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}.`);
+  return runPull(cwd, { ...flags, key }, env, io2, fetcher);
+}
 async function runPull(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
   const opts = resolved(cwd, flags, env, io2, manifestAt);
@@ -1133,8 +2640,11 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     io2.err(errorText(err));
     return 1;
   }
-  const manifest = manifestAt(join3(cwd, opts.outDir));
-  const etag = manifest && sameSelection(manifest.selection ?? DEFAULT_SELECTION, selection) ? manifest.bundleHash : void 0;
+  const manifest = manifestAt(join5(cwd, opts.outDir));
+  const etag = manifest && sameOutput(
+    { selection: manifest.selection ?? DEFAULT_SELECTION, dtcg: manifest.dtcg },
+    { selection, dtcg: opts.dtcg }
+  ) ? manifest.bundleHash : void 0;
   const result = await fetchBundle({
     api: opts.api,
     libraryId: opts.libraryId,
@@ -1155,14 +2665,15 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     const bundle = parseBundle(result.raw);
     const selected = selectComponents(bundle, selection);
     written = writeBundleFiles({
-      outDir: join3(cwd, opts.outDir),
+      outDir: join5(cwd, opts.outDir),
       cwd,
       raw: result.raw,
       bundle,
       selection,
       libraryId: opts.libraryId,
       publishedAt: result.publishedAt,
-      bundleHash: result.bundleHash
+      bundleHash: result.bundleHash,
+      dtcg: opts.dtcg
     });
     io2.out(
       `Pulled ${bundle.fileName ?? opts.libraryId}: ${describePull(bundle, selection, selected)} (published ${result.publishedAt}).`
@@ -1178,7 +2689,7 @@ async function runStatus(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
   const opts = resolved(cwd, flags, env, io2, manifestAt);
   if (!opts) return 1;
-  const manifest = manifestAt(join3(cwd, opts.outDir));
+  const manifest = manifestAt(join5(cwd, opts.outDir));
   if (!manifest) {
     io2.err(NO_LOCAL_PULL);
     return 2;
@@ -1269,21 +2780,23 @@ Available: ${available || "none"}.`);
 var USAGE = `spec-layer <command>
 
 Commands:
+  setup   --id lib_... --key sl_... [--out DIR] [selection]
+                                                 store the key, then pull
   init    --id lib_... [--out DIR] [selection]   write speclayer.json
   pull    [--id lib_...] [--key sl_...] [selection]
-                                                 fetch the library into DIR (default .speclayer)
+                                                 fetch the library into DIR (default .speclayer); the foundation lands as DTCG under DIR/tokens/
   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's AI YAML (or canonical JSON)
+                                                 print one artifact (foundation: the DTCG document; component: its AI YAML; --canonical for JSON)
 
-Selection (pull and init; flags replace the include block in speclayer.json):
+Selection (setup, pull and init; flags replace the include block in speclayer.json):
   --only foundation | components   write just the foundation, or just components
   --component NAME                 write only this component (repeatable, matched by slug)
 
 Options:
   --api URL   override the API origin (default https://api.spec-layer.com)
-The pull key comes from --key or the SPEC_LAYER_KEY environment variable.`;
+The pull key comes from --key, SPEC_LAYER_KEY, or speclayer.local.json written by setup.`;
 var io = {
   out: (l) => console.log(l),
   err: (l) => console.error(l),
@@ -1314,6 +2827,7 @@ async function main() {
   const command = positionals[0];
   const cwd = process.cwd();
   try {
+    if (command === "setup") return await runSetup(cwd, values, process.env, io);
     if (command === "init") return runInit(cwd, values, io);
     if (command === "pull") return await runPull(cwd, values, process.env, io);
     if (command === "status") return await runStatus(cwd, values, process.env, io);
@@ -1326,6 +2840,10 @@ async function main() {
     return 1;
   }
 }
+process.stdout.on("error", (err) => {
+  if (err.code === "EPIPE") process.exit(process.exitCode ?? 0);
+  throw err;
+});
 process.exitCode = await main();
 /*! Bundled license information: