spec-layer 0.3.0 → 0.5.0

package/dist/cli.js

@@ -262,7 +262,7 @@ var require_sha256 = __commonJS({
           }
           notString = true;
         }
-        var code, index = 0, i, length = message.length, blocks2 = this.blocks;
+        var code2, index = 0, i, length = message.length, blocks2 = this.blocks;
         while (index < length) {
           if (this.hashed) {
             this.hashed = false;
@@ -275,22 +275,22 @@ var require_sha256 = __commonJS({
             }
           } else {
             for (i = this.start; index < length && i < 64; ++index) {
-              code = message.charCodeAt(index);
-              if (code < 128) {
-                blocks2[i >>> 2] |= code << SHIFT[i++ & 3];
-              } else if (code < 2048) {
-                blocks2[i >>> 2] |= (192 | code >>> 6) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code & 63) << SHIFT[i++ & 3];
-              } else if (code < 55296 || code >= 57344) {
-                blocks2[i >>> 2] |= (224 | code >>> 12) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code >>> 6 & 63) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code & 63) << SHIFT[i++ & 3];
+              code2 = message.charCodeAt(index);
+              if (code2 < 128) {
+                blocks2[i >>> 2] |= code2 << SHIFT[i++ & 3];
+              } else if (code2 < 2048) {
+                blocks2[i >>> 2] |= (192 | code2 >>> 6) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code2 & 63) << SHIFT[i++ & 3];
+              } else if (code2 < 55296 || code2 >= 57344) {
+                blocks2[i >>> 2] |= (224 | code2 >>> 12) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code2 >>> 6 & 63) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code2 & 63) << SHIFT[i++ & 3];
               } else {
-                code = 65536 + ((code & 1023) << 10 | message.charCodeAt(++index) & 1023);
-                blocks2[i >>> 2] |= (240 | code >>> 18) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code >>> 12 & 63) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code >>> 6 & 63) << SHIFT[i++ & 3];
-                blocks2[i >>> 2] |= (128 | code & 63) << SHIFT[i++ & 3];
+                code2 = 65536 + ((code2 & 1023) << 10 | message.charCodeAt(++index) & 1023);
+                blocks2[i >>> 2] |= (240 | code2 >>> 18) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code2 >>> 12 & 63) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code2 >>> 6 & 63) << SHIFT[i++ & 3];
+                blocks2[i >>> 2] |= (128 | code2 & 63) << SHIFT[i++ & 3];
               }
             }
           }
@@ -472,24 +472,24 @@ var require_sha256 = __commonJS({
       function HmacSha256(key, is224, sharedMemory) {
         var i, type = typeof key;
         if (type === "string") {
-          var bytes = [], length = key.length, index = 0, code;
+          var bytes = [], length = key.length, index = 0, code2;
           for (i = 0; i < length; ++i) {
-            code = key.charCodeAt(i);
-            if (code < 128) {
-              bytes[index++] = code;
-            } else if (code < 2048) {
-              bytes[index++] = 192 | code >>> 6;
-              bytes[index++] = 128 | code & 63;
-            } else if (code < 55296 || code >= 57344) {
-              bytes[index++] = 224 | code >>> 12;
-              bytes[index++] = 128 | code >>> 6 & 63;
-              bytes[index++] = 128 | code & 63;
+            code2 = key.charCodeAt(i);
+            if (code2 < 128) {
+              bytes[index++] = code2;
+            } else if (code2 < 2048) {
+              bytes[index++] = 192 | code2 >>> 6;
+              bytes[index++] = 128 | code2 & 63;
+            } else if (code2 < 55296 || code2 >= 57344) {
+              bytes[index++] = 224 | code2 >>> 12;
+              bytes[index++] = 128 | code2 >>> 6 & 63;
+              bytes[index++] = 128 | code2 & 63;
             } else {
-              code = 65536 + ((code & 1023) << 10 | key.charCodeAt(++i) & 1023);
-              bytes[index++] = 240 | code >>> 18;
-              bytes[index++] = 128 | code >>> 12 & 63;
-              bytes[index++] = 128 | code >>> 6 & 63;
-              bytes[index++] = 128 | code & 63;
+              code2 = 65536 + ((code2 & 1023) << 10 | key.charCodeAt(++i) & 1023);
+              bytes[index++] = 240 | code2 >>> 18;
+              bytes[index++] = 128 | code2 >>> 12 & 63;
+              bytes[index++] = 128 | code2 >>> 6 & 63;
+              bytes[index++] = 128 | code2 & 63;
             }
           }
           key = bytes;
@@ -559,7 +559,7 @@ var require_sha256 = __commonJS({
 import { parseArgs } from "node:util";
 
 // src/commands.ts
-import { join as join5 } from "node:path";
+import { join as join7 } 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(code2, fields) {
+  return {
+    code: code2,
+    severity: DEFAULT_SEVERITY[code2],
+    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,29 +798,1261 @@ 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);
 
 // ../extractor/src/libraryBundle.ts
 var LIBRARY_BUNDLE_SCHEMA = "spec-layer-library-bundle";
 var LibraryBundleError = class extends Error {
-  constructor(code, message) {
+  constructor(code2, message) {
     super(message);
     this.name = "LibraryBundleError";
-    this.code = code;
+    this.code = code2;
   }
 };
-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 };
@@ -875,6 +2172,23 @@ 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 = join2(cwd, CONFIG_NAME);
   if (!existsSync2(path)) return null;
@@ -889,14 +2203,16 @@ 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 } : {}
   };
   writeFileSync2(join2(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
 `);
@@ -922,6 +2238,7 @@ function resolveOptions(cwd, flags, env, manifestLibraryId) {
     api: (flags.api ?? env.SPEC_LAYER_API ?? DEFAULT_API).replace(/\/+$/, ""),
     key: supplied ?? storedKey,
     ...config?.include ? { include: config.include } : {},
+    ...config?.dtcg ? { dtcg: config.dtcg } : {},
     ...storedKeyFor ? { storedKeyFor } : {}
   };
 }
@@ -996,8 +2313,8 @@ 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 = join3(outDir, "manifest.json");
@@ -1022,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) {
@@ -1065,8 +2382,16 @@ function writeBundleFiles(opts) {
     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",
@@ -1091,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)}
 `);
@@ -1158,6 +2484,619 @@ ${fileName}
   return existed ? { kind: "added" } : { kind: "created" };
 }
 
+// src/detect.ts
+import { existsSync as existsSync5, readdirSync as readdirSync2, readFileSync as readFileSync5 } from "node:fs";
+import { join as join5 } from "node:path";
+var CODE_SYNTAX_KEY = {
+  web: "WEB",
+  ios: "iOS",
+  android: "ANDROID",
+  flutter: null
+};
+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 = join5(cwd, "package.json");
+  if (!existsSync5(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync5(path, "utf8"));
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) return null;
+  const record = parsed;
+  const deps = {};
+  for (const field of ["dependencies", "devDependencies", "peerDependencies"]) {
+    const block = record[field];
+    if (typeof block !== "object" || block === null) continue;
+    for (const [name, range] of Object.entries(block)) {
+      if (typeof range === "string") deps[name] = range;
+    }
+  }
+  return { deps };
+}
+function majorOf(range) {
+  const m = /^[\^~>=<\s]*v?(\d+)/.exec(range.trim());
+  return m ? Number(m[1]) : null;
+}
+var DEP_SIGNALS = [
+  { dep: "react", platform: "web", framework: "react" },
+  { dep: "next", platform: "web", framework: "next" },
+  { dep: "vue", platform: "web", framework: "vue" },
+  { dep: "nuxt", platform: "web", framework: "nuxt" },
+  { dep: "svelte", platform: "web", framework: "svelte" },
+  { dep: "@sveltejs/kit", platform: "web", framework: "sveltekit" },
+  { dep: "@angular/core", platform: "web", framework: "angular" },
+  { dep: "solid-js", platform: "web", framework: "solid" },
+  { dep: "lit", platform: "web", framework: "lit" },
+  { dep: "astro", platform: "web", framework: "astro" },
+  { dep: "react-native", platform: "ios", framework: "react-native" },
+  { dep: "expo", platform: "ios", framework: "expo" },
+  { dep: "tailwindcss", platform: "web", tokenTool: "tailwind" },
+  { dep: "styled-components", platform: "web", framework: "styled-components" },
+  { dep: "@emotion/react", platform: "web", framework: "emotion" },
+  { dep: "sass", platform: "web", framework: "sass" },
+  { dep: "@vanilla-extract/css", platform: "web", framework: "vanilla-extract" },
+  { dep: "@stitches/react", platform: "web", framework: "stitches" },
+  { dep: "@pandacss/dev", platform: "web", framework: "panda" },
+  { dep: "style-dictionary", tokenTool: "style-dictionary" },
+  { dep: "@tokens-studio/sd-transforms", tokenTool: "tokens-studio" },
+  { dep: "typescript", language: "typescript" }
+];
+var FILE_SIGNALS = [
+  { test: (n) => n === "Package.swift", signal: "Swift package", platform: "ios", language: "swift" },
+  { test: (n) => n.endsWith(".xcodeproj") || n.endsWith(".xcworkspace"), signal: "Xcode project", platform: "ios", language: "swift" },
+  { test: (n) => n === "Podfile", signal: "CocoaPods", platform: "ios" },
+  { test: (n) => /^build\.gradle(\.kts)?$/.test(n) || /^settings\.gradle(\.kts)?$/.test(n), signal: "Gradle build", platform: "android", language: "kotlin" },
+  { test: (n) => n === "AndroidManifest.xml", signal: "Android manifest", platform: "android" },
+  { test: (n) => n === "pubspec.yaml", signal: "Flutter or Dart package", platform: "flutter", language: "dart" },
+  { test: (n) => n === "tsconfig.json", signal: "TypeScript config", language: "typescript" },
+  { test: (n) => n === "package.json", signal: "npm package", language: "javascript" },
+  { test: (n) => n === "deno.json" || n === "deno.jsonc", signal: "Deno config", language: "typescript" },
+  { test: (n) => n === "Cargo.toml", signal: "Cargo manifest", language: "rust" },
+  { test: (n) => n === "go.mod", signal: "Go module", language: "go" },
+  { test: (n) => n === "pyproject.toml" || n === "requirements.txt", signal: "Python project", language: "python" },
+  { test: (n) => n === "Gemfile", signal: "Ruby bundle", language: "ruby" },
+  { test: (n) => n === "composer.json", signal: "Composer package", language: "php" },
+  { test: (n) => n.endsWith(".csproj") || n.endsWith(".sln"), signal: ".NET project", language: "csharp" },
+  { test: (n) => n === "pom.xml", signal: "Maven build", language: "java" },
+  { test: (n) => /^tailwind\.config\.(js|cjs|mjs|ts)$/.test(n), signal: "Tailwind config", platform: "web", tokenTool: "tailwind" },
+  { test: (n) => /^(style-dictionary\.config|sd\.config)\.(js|cjs|mjs|ts|json)$/.test(n), signal: "Style Dictionary config", tokenTool: "style-dictionary" },
+  { test: (n) => n === "index.html" || n === "vite.config.ts" || n === "vite.config.js", signal: "web entry", platform: "web" },
+  { test: (n) => n === "CLAUDE.md" || n === ".claude", signal: "Claude Code", agent: "claude" },
+  { test: (n) => n === ".cursor" || n === ".cursorrules", signal: "Cursor", agent: "cursor" },
+  { test: (n) => n === ".windsurf" || n === ".windsurfrules", signal: "Windsurf", agent: "windsurf" },
+  { test: (n) => n === "GEMINI.md", signal: "Gemini CLI", agent: "gemini" },
+  { test: (n) => n === "AGENTS.md", signal: "AGENTS.md", agent: "agents-md" }
+];
+function detectRepo(cwd) {
+  const platforms = [];
+  const languages = [];
+  const frameworks = [];
+  const tokenTools = [];
+  const agents = [];
+  const evidence = [];
+  let styleDictionaryMajor = null;
+  let names = [];
+  try {
+    names = readdirSync2(cwd).sort();
+  } catch {
+    names = [];
+  }
+  for (const name of names) {
+    for (const rule of FILE_SIGNALS) {
+      if (!rule.test(name)) continue;
+      evidence.push({ signal: rule.signal, file: name });
+      if (rule.platform) platforms.push(rule.platform);
+      if (rule.language) languages.push(rule.language);
+      if (rule.framework) frameworks.push(rule.framework);
+      if (rule.tokenTool) tokenTools.push(rule.tokenTool);
+      if (rule.agent) agents.push(rule.agent);
+    }
+  }
+  if (existsSync5(join5(cwd, ".github", "copilot-instructions.md")) || existsSync5(join5(cwd, ".github", "instructions"))) {
+    evidence.push({ signal: "GitHub Copilot", file: ".github/copilot-instructions.md" });
+    agents.push("copilot");
+  }
+  const pkg = readPackageJson(cwd);
+  if (pkg) {
+    for (const rule of DEP_SIGNALS) {
+      const range = pkg.deps[rule.dep];
+      if (range === void 0) continue;
+      evidence.push({ signal: `${rule.dep} dependency`, file: "package.json" });
+      if (rule.platform) platforms.push(rule.platform);
+      if (rule.framework) frameworks.push(rule.framework);
+      if (rule.tokenTool) tokenTools.push(rule.tokenTool);
+      if (rule.language) languages.push(rule.language);
+      if (rule.dep === "style-dictionary") styleDictionaryMajor = majorOf(range);
+    }
+    if (pkg.deps["react-native"] !== void 0 || pkg.deps.expo !== void 0) platforms.push("android");
+  }
+  const order = (p) => PLATFORMS.indexOf(p);
+  const hostOrder = (a) => AGENT_HOSTS.indexOf(a);
+  return {
+    platforms: uniq(platforms).sort((a, b) => order(a) - order(b)),
+    languages: uniq(languages).sort(),
+    frameworks: uniq(frameworks).sort(),
+    tokenTools: uniq(tokenTools).sort(),
+    agents: uniq(agents).sort((a, b) => hostOrder(a) - hostOrder(b)),
+    styleDictionaryMajor,
+    evidence
+  };
+}
+function isPlatform(value) {
+  return PLATFORMS.includes(value);
+}
+function isAgentHost(value) {
+  return AGENT_HOSTS.includes(value);
+}
+
+// src/skill.ts
+import { existsSync as existsSync6, mkdirSync as mkdirSync2, readdirSync as readdirSync3, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "node:fs";
+import { dirname as dirname3, join as join6 } 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 TOOLS = [
+  {
+    name: "setup",
+    usage: "spec-layer setup --id lib_... --key sl_... [--out DIR] [--only foundation|components] [--component NAME]...",
+    summary: "Records the library id, stores the pull key in a gitignored speclayer.local.json, then pulls.",
+    when: "Once, with the command the plugin's Publish screen hands out. Re-run it after the key is rotated.",
+    network: true,
+    needsKey: true,
+    writes: ["speclayer.json", "speclayer.local.json", ".gitignore (one line, when inside a git repo)", "<outDir>/"],
+    exits: OK_OR_ERROR
+  },
+  {
+    name: "init",
+    usage: "spec-layer init --id lib_... [--out DIR] [--only foundation|components] [--component NAME]...",
+    summary: "Writes speclayer.json so later commands need no flags. Stores no key and reaches no server.",
+    when: "A repo that supplies the key from SPEC_LAYER_KEY instead of a stored file.",
+    network: false,
+    needsKey: false,
+    writes: ["speclayer.json"],
+    exits: { "0": "success", "1": "usage error" }
+  },
+  {
+    name: "pull",
+    usage: "spec-layer pull [--id lib_...] [--key sl_...] [--out DIR] [--only foundation|components] [--component NAME]...",
+    summary: "Fetches the published library and writes it under the output directory (default .speclayer/).",
+    when: "After setup, whenever status says the local copy is behind, or after changing the include or dtcg block.",
+    network: true,
+    needsKey: true,
+    writes: ["<outDir>/"],
+    exits: OK_OR_ERROR
+  },
+  {
+    name: "status",
+    usage: "spec-layer status [--id lib_...] [--key sl_...] [--out DIR]",
+    summary: "Checks whether the local pull is current without writing anything.",
+    when: "Before reading the pulled files, or in CI; exit 2 means run pull.",
+    network: true,
+    needsKey: true,
+    writes: [],
+    exits: { "0": "up to date", "1": "usage error, bad key or id, or a network or server failure", "2": "behind, or no local pull yet" }
+  },
+  {
+    name: "list",
+    usage: "spec-layer list [--out DIR]",
+    summary: 'Lists every artifact in the last pull with its file path, or "not written" when the selection skipped it.',
+    when: "To learn which components the library documents and where each file is.",
+    network: false,
+    needsKey: false,
+    writes: [],
+    exits: LOCAL_ONLY
+  },
+  {
+    name: "show",
+    usage: "spec-layer show foundation | component NAME [--canonical] [--out DIR]",
+    summary: "Prints one artifact to stdout: the Foundation DTCG document, or one component's AI YAML; --canonical prints the v5 JSON.",
+    when: "To read one component or the token document without opening files; it pipes cleanly.",
+    network: false,
+    needsKey: false,
+    writes: [],
+    exits: LOCAL_ONLY
+  },
+  {
+    name: "tools",
+    usage: "spec-layer tools [--json]",
+    summary: "Prints this list of commands, with what each reaches and writes.",
+    when: "A coding agent deciding which command to run; --json is stable for machines.",
+    network: false,
+    needsKey: false,
+    writes: [],
+    exits: { "0": "success" }
+  },
+  {
+    name: "skill",
+    usage: "spec-layer skill [--install] [--agent claude|cursor|copilot|windsurf|gemini|agents-md]... [--platform web|ios|android|flutter] [--json] [--out DIR]",
+    summary: "Prints a guide for a coding agent, adapted to this repository's stack and to the last pull; --install writes it where the agent reads instructions.",
+    when: "Right after setup, and again after a pull that adds components or after the codebase changes stack.",
+    network: false,
+    needsKey: false,
+    writes: ["agent instruction files (only with --install; each path is printed)"],
+    exits: { "0": "success", "1": "usage error, or a file could not be written" }
+  }
+];
+var GLOBAL_FLAGS = [
+  { flag: "--api URL", summary: "Override the API origin (default https://api.spec-layer.com). Also SPEC_LAYER_API." },
+  { flag: "--out DIR", summary: "Output directory (default .speclayer, or the outDir in speclayer.json)." }
+];
+var KEY_RESOLUTION = "The pull key resolves from --key, then SPEC_LAYER_KEY, then speclayer.local.json written by setup. No command ever prints it.";
+function toolsText() {
+  const lines = ["spec-layer commands", ""];
+  for (const tool of TOOLS) {
+    lines.push(tool.usage);
+    lines.push(`  ${tool.summary}`);
+    lines.push(`  When: ${tool.when}`);
+    lines.push(`  Network: ${tool.network ? "yes" : "no"}. Key: ${tool.needsKey ? "required" : "not needed"}. Writes: ${tool.writes.length ? tool.writes.join(", ") : "nothing"}.`);
+    lines.push(`  Exits: ${Object.entries(tool.exits).map(([code2, meaning]) => `${code2} ${meaning}`).join("; ")}.`);
+    lines.push("");
+  }
+  lines.push("Flags every command accepts where they apply:");
+  for (const f of GLOBAL_FLAGS) lines.push(`  ${f.flag}  ${f.summary}`);
+  lines.push("");
+  lines.push(KEY_RESOLUTION);
+  return lines.join("\n");
+}
+function toolsJson(version) {
+  return `${JSON.stringify({
+    cli: "spec-layer",
+    version,
+    tools: TOOLS.map((t) => ({ ...t })),
+    flags: GLOBAL_FLAGS,
+    key_resolution: KEY_RESOLUTION
+  }, null, 2)}
+`;
+}
+
+// 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;
+  const record = tree;
+  if (record.$type === "number" && "$value" in record) return 1;
+  let n = 0;
+  for (const [key, value] of Object.entries(record)) {
+    if (key.startsWith("$")) continue;
+    n += countNumberTokens(value);
+  }
+  return n;
+}
+function readJson(path) {
+  if (!existsSync6(path)) return null;
+  try {
+    return JSON.parse(readFileSync6(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function summarizePull(cwd, outDir, manifest) {
+  if (!manifest) return null;
+  const absOut = join6(cwd, outDir);
+  const components = manifest.artifacts.filter((a) => a.kind === "component").map((a) => ({ name: a.name, path: a.aiPath ? `${outDir}/${a.aiPath}` : null }));
+  const foundationEntry = manifest.artifacts.find((a) => a.kind === "foundation") ?? null;
+  let foundation = null;
+  if (foundationEntry) {
+    const tokensDir = join6(absOut, "tokens");
+    const resolver = readJson(join6(tokensDir, "resolver.json"));
+    const report = readJson(join6(tokensDir, "report.json"));
+    let tokenFiles = [];
+    try {
+      tokenFiles = readdirSync3(tokensDir).filter((f) => f.endsWith(".json") && !RESERVED.has(f)).sort();
+    } catch {
+      tokenFiles = [];
+    }
+    let unitlessNumbers = 0;
+    for (const file of tokenFiles) {
+      if (file.startsWith("styles.")) continue;
+      unitlessNumbers += countNumberTokens(readJson(join6(tokensDir, file)));
+    }
+    const reportCounts = {};
+    if (Array.isArray(report)) {
+      for (const entry2 of report) {
+        if (typeof entry2?.code === "string") reportCounts[entry2.code] = (reportCounts[entry2.code] ?? 0) + 1;
+      }
+    }
+    foundation = {
+      written: foundationEntry.aiPath !== null && resolver !== null,
+      sets: resolver ? Object.keys(resolver.sets ?? {}) : [],
+      modifiers: resolver ? Object.entries(resolver.modifiers ?? {}).map(([name, m]) => ({
+        name,
+        contexts: Object.keys(m.contexts ?? {}),
+        default: m.default ?? null
+      })) : [],
+      tokenFiles,
+      unitlessNumbers,
+      reportCounts
+    };
+  }
+  return {
+    outDir,
+    libraryId: manifest.libraryId,
+    publishedAt: manifest.publishedAt,
+    pluginVersion: manifest.pluginVersion,
+    components,
+    foundation
+  };
+}
+var code = (s) => `\`${s}\``;
+function stackSection(input) {
+  const { profile, platforms, platformSource, pull } = input;
+  const lines = ["## This codebase", ""];
+  if (profile.evidence.length === 0) {
+    lines.push(
+      "Nothing at the root of this directory identified a language, framework, or platform. "
+    );
+  } else {
+    lines.push("Detected from the repository root (the file that carries each signal is named, and nothing deeper was read):", "");
+    for (const e of profile.evidence) lines.push(`- ${e.signal} (${code(e.file)})`);
+    lines.push("");
+    const facts = [];
+    if (profile.languages.length) facts.push(`Languages: ${profile.languages.join(", ")}.`);
+    if (profile.frameworks.length) facts.push(`Frameworks: ${profile.frameworks.join(", ")}.`);
+    if (profile.tokenTools.length) facts.push(`Token tooling: ${profile.tokenTools.join(", ")}.`);
+    if (facts.length) lines.push(facts.join(" "), "");
+  }
+  if (platformSource === "none") {
+    lines.push(
+      `No target platform was detected, so the token advice below is generic. Re-run ${code("spec-layer skill --platform web|ios|android|flutter")} to write it for a platform, or pass ` + code("--install") + " with the same flag to update the installed copy.",
+      ""
+    );
+  } else {
+    const label = platformSource === "flag" ? "chosen with --platform" : "detected";
+    lines.push(`Target platform${platforms.length > 1 ? "s" : ""} (${label}): ${platforms.join(", ")}.`, "");
+  }
+  for (const platform of platforms) {
+    const key = CODE_SYNTAX_KEY[platform];
+    const tokensDir = `${input.outDir}/tokens/`;
+    if (platform === "web") {
+      lines.push("### Web", "");
+      lines.push(
+        `Token identifiers for code live in ${code(`${tokensDir}spec-layer.meta.json`)} under each token's ${code("code_syntax.WEB")}, when the designer declared one in Figma. Use that identifier as the CSS custom property or theme key. When a token has no WEB entry, derive nothing: use the DTCG path as it appears in the token file (for example ${code("{Collection.group.name}")}) and say in your change that the code name is not declared in Figma.`
+      );
+      lines.push("");
+      if (profile.tokenTools.includes("tailwind")) {
+        lines.push(
+          `Tailwind is present (${code("tailwindcss")}). Map DTCG ${code("color")} tokens to the theme's color scale and ${code("dimension")} tokens to spacing, radius, or font size by the collection and group they sit in. Keep the mapping in one place and reference token paths, not copied values, so a republish moves the code with it.`,
+          ""
+        );
+      }
+      if (profile.tokenTools.includes("style-dictionary")) {
+        const major = profile.styleDictionaryMajor;
+        lines.push(
+          `Style Dictionary is present${major !== null ? ` (major version ${major} in package.json)` : ""}. Point it at ${code(tokensDir)} and load the files ${code("resolver.json")} names for the mode you build. Exclude ${code("spec-layer.meta.json")} and ${code("report.json")} from token globs; they are not token files.`
+        );
+        if (major !== null && major < 5) {
+          lines.push(
+            "",
+            `Style Dictionary ${major} reads the string value forms, not the 2025.10 object forms. Set ${code('"dtcg": { "values": "legacy" }')} in ${code("speclayer.json")} and run ${code("spec-layer pull")}; the change re-projects tokens/ without a republish.`
+          );
+        }
+        lines.push("");
+      }
+    } else if (platform === "ios") {
+      lines.push("### iOS", "");
+      lines.push(
+        `Token identifiers for code live in ${code(`${tokensDir}spec-layer.meta.json`)} under each token's ${code(`code_syntax.${key}`)}, when the designer declared one in Figma. Use that as the Swift symbol. Colors arrive as hex strings or DTCG color objects with RGBA components; dimensions carry an explicit px or rem unit. A modifier with more than one context (for example a light and a dark mode) maps to a color-scheme-dependent value; a set without modes is a constant. Do not invent a dark variant for a collection that has one mode.`,
+        ""
+      );
+    } else if (platform === "android") {
+      lines.push("### Android", "");
+      lines.push(
+        `Token identifiers for code live in ${code(`${tokensDir}spec-layer.meta.json`)} under each token's ${code(`code_syntax.${key}`)}, when the designer declared one in Figma. Use that as the Kotlin or resource name. Dimensions carry an explicit px or rem unit and no density assumption; a value is only dp when your own convention says so, and that convention belongs in your code, not in the token file. Modes map to resource qualifiers or a Compose theme switch.`,
+        ""
+      );
+    } else {
+      lines.push("### Flutter", "");
+      lines.push(
+        `Figma declares no code syntax for Flutter, so no identifier is provided for Dart. Name symbols after the DTCG path (for example ${code("Collection.group.name")} becomes a nested class or a camelCase constant) and keep the path in a comment so the source token stays traceable. Modes map to theme variants.`,
+        ""
+      );
+    }
+  }
+  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) {
+  const { pull, outDir } = input;
+  const lines = ["## What is on disk", ""];
+  if (!pull) {
+    lines.push(
+      `No pull has been made in this directory yet, so nothing under ${code(outDir + "/")} can be described. Run ${code("npx spec-layer pull")} (or the setup command from the plugin if there is no ${code("speclayer.json")}), then ${code("npx spec-layer skill --install")} again to list the components and token collections here.`,
+      ""
+    );
+    return lines;
+  }
+  lines.push(
+    `Library ${code(pull.libraryId)}, published ${pull.publishedAt}${pull.pluginVersion ? ` by plugin ${pull.pluginVersion}` : ""}. Run ${code("npx spec-layer status")} first; exit code 2 means a newer publish exists and ${code("npx spec-layer pull")} fetches it.`,
+    ""
+  );
+  lines.push(`- ${code(`${outDir}/manifest.json`)}: every artifact with its content hash and file path.`);
+  lines.push(`- ${code(`${outDir}/bundle.json`)}: the whole published library, including the canonical v5 JSON of every artifact.`);
+  if (pull.foundation) {
+    if (pull.foundation.written) {
+      lines.push(`- ${code(`${outDir}/tokens/`)}: the Foundation as Design Tokens Format Module 2025.10 files.`);
+      lines.push(`  - ${code("resolver.json")}: sets, modifiers, and resolution order. Start here.`);
+      lines.push(`  - ${code("spec-layer.meta.json")}: Figma ids, scopes, publication, and ${code("code_syntax")} per DTCG path.`);
+      lines.push(`  - ${code("report.json")}: what the format could not express, with reasons. Never fill these gaps with a guess.`);
+      for (const f of pull.foundation.tokenFiles) lines.push(`  - ${code(f)}`);
+    } else {
+      lines.push(`- Foundation: present in the library but not written, because the selection excludes it. ${code("spec-layer show foundation")} still prints it.`);
+    }
+  } else {
+    lines.push("- This library has no Foundation, so there is no tokens/ directory.");
+  }
+  lines.push(`- ${code(`${outDir}/ai/components/`)}: one YAML per component.`);
+  lines.push("");
+  if (pull.foundation && (pull.foundation.sets.length || pull.foundation.modifiers.length)) {
+    lines.push("### Token collections", "");
+    for (const set of pull.foundation.sets) lines.push(`- ${code(set)}: one mode, always applied.`);
+    for (const m of pull.foundation.modifiers) {
+      lines.push(`- ${code(m.name)}: modes ${m.contexts.map(code).join(", ")}${m.default ? `, default ${code(m.default)}` : ""}.`);
+    }
+    lines.push("");
+    const counts = Object.entries(pull.foundation.reportCounts);
+    if (counts.length) {
+      lines.push(
+        `${code("report.json")} lists ${counts.map(([c, n]) => `${n} ${code(c)}`).join(", ")}. Read it before assuming a token is missing.`,
+        ""
+      );
+    }
+  }
+  lines.push("### Components", "");
+  if (pull.components.length === 0) {
+    lines.push("The library documents no components.", "");
+  } else {
+    for (const c of pull.components) {
+      lines.push(c.path ? `- ${c.name}: ${code(c.path)}` : `- ${c.name}: not written (excluded by the selection). ${code(`spec-layer show component "${c.name}"`)} prints it.`);
+    }
+    lines.push("");
+  }
+  return lines;
+}
+function commandsSection() {
+  const lines = ["## Commands", ""];
+  const cell = (s) => s.replace(/\|/g, "\\|");
+  lines.push("| Command | What it does | When | Network | Key | Writes |", "|---|---|---|---|---|---|");
+  for (const t of TOOLS) {
+    lines.push(`| ${code(cell(t.usage))} | ${cell(t.summary)} | ${cell(t.when)} | ${t.network ? "yes" : "no"} | ${t.needsKey ? "required" : "no"} | ${t.writes.length ? t.writes.map((w) => code(cell(w))).join(", ") : "nothing"} |`);
+  }
+  lines.push("");
+  lines.push("Exit codes:", "");
+  for (const t of TOOLS) {
+    lines.push(`- ${code(t.name)}: ${Object.entries(t.exits).map(([c, m]) => `${c} = ${m}`).join("; ")}.`);
+  }
+  lines.push("");
+  for (const f of GLOBAL_FLAGS) lines.push(`- ${code(f.flag)}: ${f.summary}`);
+  lines.push("", KEY_RESOLUTION, "");
+  lines.push(`Run ${code("npx --yes spec-layer <command>")} in an unattended session so npx does not stop to ask before downloading the package. ${code("spec-layer tools --json")} prints this table for machines.`, "");
+  return lines;
+}
+function buildSkillGuide(input) {
+  const { outDir } = input;
+  const lines = [];
+  lines.push("# Spec Layer: design-system context for this repository", "");
+  lines.push(
+    `The Spec Layer Figma plugin publishes a design system's components, variables, and styles as data. The ${code("spec-layer")} CLI (version ${input.version}) pulls that data into this repository under ${code(outDir + "/")}. Everything in those files is extracted deterministically from Figma and validated against a published schema; no model wrote any of it. Treat it as the source of truth for what the design system contains, and treat anything it does not state as unknown rather than as something to infer.`,
+    ""
+  );
+  lines.push("## How to use it", "");
+  lines.push(`1. Run ${code("npx spec-layer status")}. Exit 0 means the local copy is current; exit 2 means run ${code("npx spec-layer pull")} first.`);
+  lines.push(`2. Building or changing a component: read its YAML under ${code(`${outDir}/ai/components/`)}, or ${code("npx spec-layer show component NAME")}. ${code("api")} gives variants, states, booleans, and slots; ${code("anatomy")} names the parts; ${code("references.bindings")} says which token each part's property uses and under which ${code("when")} conditions; ${code("unbound")} lists values that are hardcoded in Figma.`);
+  lines.push(`3. Working with colors, spacing, type, or effects: start at ${code(`${outDir}/tokens/resolver.json`)}, load the set and mode files it names, and look up ${code("code_syntax")} in ${code("spec-layer.meta.json")} for the name the designer declared for your platform.`);
+  lines.push(`4. Reference tokens by name in code; never paste a resolved value where a token exists. A value the design system does not define is not a token: say so in your change rather than adding one.`);
+  lines.push(`5. An ${code("unbound")} entry is design debt reported from Figma. Do not silently promote it to a token; keep the literal and note that Figma has no binding for it.`);
+  lines.push(`6. Never edit files under ${code(outDir + "/")}: the next pull replaces the whole directory. Configuration lives in ${code("speclayer.json")}. Never commit ${code(CREDENTIALS_NAME)}, and never print or copy the pull key.`);
+  lines.push("");
+  lines.push(...pullSection(input));
+  lines.push(...stackSection(input));
+  lines.push(...commandsSection());
+  lines.push(`Generated by ${code("spec-layer skill")}. Re-run ${code("npx spec-layer skill --install")} after a pull that adds components or when the codebase changes stack; the file is replaced, not appended.`);
+  return `${lines.join("\n")}
+`;
+}
+var SKILL_DESCRIPTION = "Use the design-system context the Spec Layer Figma plugin published into this repository: component variants, states, anatomy, token bindings, and design tokens. Read this before building or changing UI, using tokens, or running the spec-layer CLI.";
+function installTarget(host) {
+  switch (host) {
+    case "claude":
+      return { host, path: ".claude/skills/spec-layer/SKILL.md", mode: "file" };
+    case "cursor":
+      return { host, path: ".cursor/rules/spec-layer.mdc", mode: "file" };
+    case "copilot":
+      return { host, path: ".github/instructions/spec-layer.instructions.md", mode: "file" };
+    case "windsurf":
+      return { host, path: ".windsurf/rules/spec-layer.md", mode: "file" };
+    case "gemini":
+      return { host, path: "GEMINI.md", mode: "block" };
+    case "agents-md":
+      return { host, path: "AGENTS.md", mode: "block" };
+  }
+}
+function renderForHost(host, guide) {
+  const yamlString = (s) => JSON.stringify(s);
+  switch (host) {
+    case "claude":
+      return `---
+name: spec-layer
+description: ${yamlString(SKILL_DESCRIPTION)}
+---
+
+${guide}`;
+    case "cursor":
+      return `---
+description: ${yamlString(SKILL_DESCRIPTION)}
+alwaysApply: false
+---
+
+${guide}`;
+    case "copilot":
+      return `---
+applyTo: "**"
+---
+
+${guide}`;
+    case "windsurf":
+      return `---
+trigger: model_decision
+description: ${yamlString(SKILL_DESCRIPTION)}
+---
+
+${guide}`;
+    case "gemini":
+    case "agents-md":
+      return guide;
+  }
+}
+var BLOCK_BEGIN = "<!-- spec-layer:begin -->";
+var BLOCK_END = "<!-- spec-layer:end -->";
+function upsertBlock(existing, guide) {
+  const block = `${BLOCK_BEGIN}
+${guide.trimEnd()}
+${BLOCK_END}
+`;
+  if (existing === null) return block;
+  const begin = existing.indexOf(BLOCK_BEGIN);
+  const end = existing.indexOf(BLOCK_END);
+  if (begin !== -1 && end !== -1 && end > begin) {
+    const after = existing.slice(end + BLOCK_END.length).replace(/^\n/, "");
+    return `${existing.slice(0, begin)}${block}${after}`;
+  }
+  const sep = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  return `${existing}${sep}${block}`;
+}
+function installSkill(cwd, host, guide) {
+  const target = installTarget(host);
+  const abs = join6(cwd, target.path);
+  const existing = existsSync6(abs) ? readFileSync6(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" };
+  mkdirSync2(dirname3(abs), { recursive: true });
+  writeFileSync5(abs, next);
+  return { path: target.path, result: existing === null ? "created" : "updated" };
+}
+
+// src/version.ts
+import { readFileSync as readFileSync7 } from "node:fs";
+function cliVersion() {
+  try {
+    const parsed = JSON.parse(readFileSync7(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() {
@@ -1167,9 +3106,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) {
@@ -1210,7 +3157,7 @@ function resolved(cwd, flags, env, io2, manifestAt) {
 }
 function resolvedOutDir(cwd, flags, io2) {
   try {
-    return join5(cwd, flags.out ?? readConfig(cwd)?.outDir ?? DEFAULT_OUT_DIR);
+    return join7(cwd, flags.out ?? readConfig(cwd)?.outDir ?? DEFAULT_OUT_DIR);
   } catch (err) {
     io2.err(errorText(err));
     return null;
@@ -1248,7 +3195,13 @@ async function runSetup(cwd, flags, env, io2, fetcher) {
   }
   const outDir = flags.out ?? existing?.outDir ?? DEFAULT_OUT_DIR;
   const keptInclude = include ?? existing?.include ?? null;
-  writeConfig(cwd, { libraryId: flags.id, outDir, ...keptInclude ? { include: keptInclude } : {} });
+  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) {
@@ -1287,7 +3240,14 @@ git rm --cached ${ignored.line}`);
   }
   const { replaced } = writeCredentials(cwd, { libraryId: flags.id, key });
   io2.out(replaced ? `Replaced the stored key in ${CREDENTIALS_NAME}.` : `Stored the pull key in ${CREDENTIALS_NAME}.`);
-  return runPull(cwd, { ...flags, key }, env, io2, fetcher);
+  const code2 = await runPull(cwd, { ...flags, key }, env, io2, fetcher);
+  if (code2 !== 0) return code2;
+  const hosts = detectRepo(cwd).agents;
+  io2.out("");
+  io2.out("Next step for a coding agent: npx spec-layer skill --install");
+  io2.out(hosts.length > 0 ? `That writes a guide to the pulled files, adapted to this codebase, to ${hosts.map((h) => installTarget(h).path).join(", ")}.` : `That writes a guide to the pulled files, adapted to this codebase, into ${installTarget("agents-md").path}; --agent ${AGENT_HOSTS.join("|")} chooses where.`);
+  io2.out("spec-layer skill prints the same guide; spec-layer tools lists every command.");
+  return 0;
 }
 async function runPull(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
@@ -1300,8 +3260,11 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     io2.err(errorText(err));
     return 1;
   }
-  const manifest = manifestAt(join5(cwd, opts.outDir));
-  const etag = manifest && sameSelection(manifest.selection ?? DEFAULT_SELECTION, selection) ? manifest.bundleHash : void 0;
+  const manifest = manifestAt(join7(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,
@@ -1322,14 +3285,15 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     const bundle = parseBundle(result.raw);
     const selected = selectComponents(bundle, selection);
     written = writeBundleFiles({
-      outDir: join5(cwd, opts.outDir),
+      outDir: join7(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}).`
@@ -1345,7 +3309,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(join5(cwd, opts.outDir));
+  const manifest = manifestAt(join7(cwd, opts.outDir));
   if (!manifest) {
     io2.err(NO_LOCAL_PULL);
     return 2;
@@ -1431,6 +3395,90 @@ Available: ${available || "none"}.`);
 ` : entry2.ai);
   return 0;
 }
+function runTools(flags, io2) {
+  if (flags.json) io2.write(toolsJson(cliVersion()));
+  else io2.out(toolsText());
+  return 0;
+}
+function collectSkillInput(cwd, flags, io2) {
+  let config = null;
+  try {
+    config = readConfig(cwd);
+  } catch (err) {
+    io2.err(errorText(err));
+    return null;
+  }
+  const outDir = flags.out ?? config?.outDir ?? DEFAULT_OUT_DIR;
+  const profile = detectRepo(cwd);
+  let platforms;
+  let platformSource;
+  if (flags.platform !== void 0) {
+    if (!isPlatform(flags.platform)) {
+      io2.err(`--platform takes ${PLATFORMS.join(", ")}, not "${flags.platform}".`);
+      return null;
+    }
+    platforms = [flags.platform];
+    platformSource = "flag";
+  } else {
+    platforms = profile.platforms;
+    platformSource = platforms.length > 0 ? "detected" : "none";
+  }
+  const pull = summarizePull(cwd, outDir, readManifest(join7(cwd, outDir)));
+  return { profile, platforms, platformSource, outDir, config, pull, version: cliVersion() };
+}
+function skillHosts(flags, input, io2) {
+  const named = flags.agent ?? [];
+  if (named.length > 0) {
+    const hosts = [];
+    for (const value of named) {
+      if (!isAgentHost(value)) {
+        io2.err(`--agent takes ${AGENT_HOSTS.join(", ")}, not "${value}".`);
+        return null;
+      }
+      if (!hosts.includes(value)) hosts.push(value);
+    }
+    return hosts;
+  }
+  return input.profile.agents.length > 0 ? input.profile.agents : ["agents-md"];
+}
+function runSkill(cwd, flags, io2) {
+  const input = collectSkillInput(cwd, flags, io2);
+  if (!input) return 1;
+  const hosts = skillHosts(flags, input, io2);
+  if (!hosts) return 1;
+  if (flags.json) {
+    io2.write(`${JSON.stringify({
+      cli_version: input.version,
+      detected: input.profile,
+      platforms: input.platforms,
+      platform_source: input.platformSource,
+      pull: input.pull,
+      install_targets: hosts.map((h) => installTarget(h))
+    }, null, 2)}
+`);
+    return 0;
+  }
+  const guide = buildSkillGuide(input);
+  if (!flags.install) {
+    io2.write(guide);
+    return 0;
+  }
+  const chosen = flags.agent && flags.agent.length > 0 ? "named with --agent" : input.profile.agents.length > 0 ? "detected in this repository" : "the default when no agent is detected";
+  for (const host of hosts) {
+    let outcome;
+    try {
+      outcome = installSkill(cwd, host, guide);
+    } catch (err) {
+      io2.err(`Could not write ${installTarget(host).path}: ${errorText(err)}`);
+      return 1;
+    }
+    const verb = outcome.result === "created" ? "Wrote" : outcome.result === "updated" ? "Updated" : "Unchanged:";
+    io2.out(`${verb} ${outcome.path} (${host}, ${chosen}).`);
+  }
+  if (!input.pull) io2.out(`No local pull yet, so the guide lists no components. Run spec-layer pull, then spec-layer skill --install again.`);
+  if (input.platformSource === "none") io2.out(`No target platform detected. Pass --platform ${PLATFORMS.join("|")} to write platform-specific token advice.`);
+  return 0;
+}
 
 // src/cli.ts
 var USAGE = `spec-layer <command>
@@ -1440,11 +3488,15 @@ Commands:
                                                  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)
+  tools   [--json]                               list every command with what it reaches and writes
+  skill   [--install] [--agent HOST]... [--platform P] [--json]
+                                                 print a guide for a coding agent, adapted to this repo and the last pull;
+                                                 --install writes it for claude, cursor, copilot, windsurf, gemini, or agents-md
 
 Selection (setup, pull and init; flags replace the include block in speclayer.json):
   --only foundation | components   write just the foundation, or just components
@@ -1473,7 +3525,11 @@ async function main() {
         api: { type: "string" },
         only: { type: "string" },
         component: { type: "string", multiple: true },
-        canonical: { type: "boolean" }
+        canonical: { type: "boolean" },
+        json: { type: "boolean" },
+        install: { type: "boolean" },
+        agent: { type: "string", multiple: true },
+        platform: { type: "string" }
       }
     }));
   } catch {
@@ -1489,6 +3545,8 @@ async function main() {
     if (command === "status") return await runStatus(cwd, values, process.env, io);
     if (command === "list") return runList(cwd, values, io);
     if (command === "show") return runShow(cwd, values, positionals.slice(1), io);
+    if (command === "tools") return runTools(values, io);
+    if (command === "skill") return runSkill(cwd, values, io);
     io.err(USAGE);
     return 1;
   } catch (err) {
@@ -1496,6 +3554,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: