spec-layer 0.4.0 → 0.6.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,8 @@ var require_sha256 = __commonJS({
 import { parseArgs } from "node:util";
 
 // src/commands.ts
-import { join as join5 } from "node:path";
+import { existsSync as existsSync8 } from "node:fs";
+import { join as join7, resolve as resolve4 } from "node:path";
 
 // ../extractor/src/statesMatrix.ts
 var STATE_ORDER = [
@@ -642,10 +643,10 @@ var DEFAULT_SEVERITY = {
   EXPORT_SCOPED: "info"
 };
 var compareCodeUnits = (a, b) => a < b ? -1 : a > b ? 1 : 0;
-function diagnostic(code, fields) {
+function diagnostic(code2, fields) {
   return {
-    code,
-    severity: DEFAULT_SEVERITY[code],
+    code: code2,
+    severity: DEFAULT_SEVERITY[code2],
     entity_id: fields.entity_id,
     ...fields.mode_id !== void 0 ? { mode_id: fields.mode_id } : {},
     message: fields.message,
@@ -1611,15 +1612,15 @@ function styleMember(p, property, scopes, path, name) {
     });
     return null;
   }
-  const converted = dtcgLiteral(property.resolved, scopes, p.options.values);
-  if ("omit" in converted) {
-    if (converted.omit === "unit_not_expressible") {
+  const converted2 = dtcgLiteral(property.resolved, scopes, p.options.values);
+  if ("omit" in converted2) {
+    if (converted2.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 }
+        details: { property: name, ...converted2.details }
       });
       const d = property.resolved;
       return { extension: { value: d.number, unit: d.unit } };
@@ -1629,11 +1630,11 @@ function styleMember(p, property, scopes, path, name) {
       severity: "warning",
       path,
       message: `The ${name} property has a type DTCG cannot state and was omitted.`,
-      details: { property: name, ...converted.details }
+      details: { property: name, ...converted2.details }
     });
     return null;
   }
-  return { value: converted.$value };
+  return { value: converted2.$value };
 }
 var TYPOGRAPHY_MEMBERS = [
   ["font_family", "fontFamily", []],
@@ -1733,8 +1734,8 @@ function effectLeaf(p, style, path) {
       }
       const raw = effect[field];
       if (raw === void 0) continue;
-      const converted = dtcgLiteral(raw, [], p.options.values);
-      if (!("omit" in converted)) shadow[name] = converted.$value;
+      const converted2 = dtcgLiteral(raw, [], p.options.values);
+      if (!("omit" in converted2)) shadow[name] = converted2.$value;
     }
     shadow.inset = effect.type === "inner_shadow";
     shadows.push(shadow);
@@ -2000,7 +2001,7 @@ function tokenLeaf(p, token, collection, modeId) {
     }
     return { $type: typed.$type, $value: `{${targetPath}}`, ...description };
   }
-  const converted = projectedLiteral(p, token, value.value, (override) => {
+  const converted2 = projectedLiteral(p, token, value.value, (override) => {
     reportOnce(p, {
       code: "unit_override_conflicts_with_scope",
       severity: "warning",
@@ -2009,18 +2010,18 @@ function tokenLeaf(p, token, collection, modeId) {
       details: { id: token.id, override, scopes: [...token.scopes] }
     });
   });
-  if ("omit" in converted) {
+  if ("omit" in converted2) {
     reportOnce(p, {
-      code: converted.omit,
+      code: converted2.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 }
+      message: converted2.omit === "type_not_expressible" ? `DTCG has no ${String(converted2.details.type)} type; the value was omitted.` : `DTCG dimensions take px or rem; a ${String(converted2.details.unit)} value was omitted.`,
+      details: { id: token.id, ...converted2.details }
     });
     return null;
   }
-  return { $type: converted.$type, $value: converted.$value, ...description };
+  return { $type: converted2.$type, $value: converted2.$value, ...description };
 }
 function dtcgExportFiles(out) {
   const text = (v) => `${JSON.stringify(v, null, 2)}
@@ -2033,16 +2034,475 @@ function dtcgExportFiles(out) {
   return files;
 }
 
+// ../extractor/src/v5/outputs/naming.ts
+var NAME_CASES = ["kebab", "camel", "pascal", "snake", "constant"];
+function splitWords(segment) {
+  return segment.replace(new RegExp("(\\p{Ll})(\\p{Lu})", "gu"), "$1 $2").split(/[^\p{L}\p{N}]+/u).filter((w) => w.length > 0);
+}
+function pathWords(path) {
+  return path.split(".").flatMap((seg) => {
+    const words = splitWords(seg);
+    return words.length > 0 ? words : ["_"];
+  });
+}
+function joinWords(words, nameCase) {
+  const lower = words.map((w) => w.toLowerCase());
+  const cap = (w) => w.charAt(0).toUpperCase() + w.slice(1);
+  switch (nameCase) {
+    case "kebab":
+      return lower.join("-");
+    case "snake":
+      return lower.join("_");
+    case "constant":
+      return lower.join("_").toUpperCase();
+    case "camel":
+      return lower.map((w, i) => i === 0 ? w : cap(w)).join("");
+    case "pascal":
+      return lower.map(cap).join("");
+    default: {
+      const exhaustive = nameCase;
+      return exhaustive;
+    }
+  }
+}
+function deriveName(path, nameCase) {
+  return joinWords(pathWords(path), nameCase);
+}
+function sortReport(entries) {
+  return [...entries].sort((a, b) => compareCodeUnits(a.path, b.path) || compareCodeUnits(a.code, b.code) || compareCodeUnits(a.mode ?? "", b.mode ?? ""));
+}
+function resolveNames(paths, meta, rules) {
+  const report2 = [];
+  const candidates = /* @__PURE__ */ new Map();
+  for (const path of [...paths].sort(compareCodeUnits)) {
+    let name = null;
+    let source = "derived";
+    const declared = rules.codeSyntaxKey ? meta[path]?.code_syntax?.[rules.codeSyntaxKey] : void 0;
+    if (declared !== void 0) {
+      name = rules.acceptDeclared(declared);
+      if (name !== null) {
+        source = "code_syntax";
+      } else {
+        report2.push({
+          code: "code_syntax_not_usable",
+          severity: "info",
+          path,
+          message: `The declared ${rules.codeSyntaxKey} identifier "${declared}" is not a name this format can use; the name was derived instead.`,
+          details: { declared, platform: rules.codeSyntaxKey ?? "" }
+        });
+      }
+    }
+    if (name === null) name = rules.affix(deriveName(path, rules.nameCase));
+    const list = candidates.get(name) ?? [];
+    list.push({ path, source });
+    candidates.set(name, list);
+  }
+  const names = /* @__PURE__ */ new Map();
+  const map = {};
+  for (const [name, list] of candidates) {
+    if (list.length > 1) {
+      const collided = list.map((c) => c.path).sort(compareCodeUnits);
+      for (const c of list) {
+        report2.push({
+          code: "name_collision",
+          severity: "error",
+          path: c.path,
+          message: `${list.length} tokens would share the name ${name}; all were omitted.`,
+          details: { name, paths: collided }
+        });
+      }
+      continue;
+    }
+    names.set(list[0].path, name);
+    map[list[0].path] = { name, source: list[0].source };
+  }
+  const sortedMap = Object.fromEntries(Object.entries(map).sort(([a], [b]) => compareCodeUnits(a, b)));
+  return { names, map: sortedMap, report: sortReport(report2) };
+}
+
+// ../extractor/src/v5/outputs/css.ts
+var CSS_DEFAULTS = {
+  case: "kebab",
+  root: ":root",
+  modeSelector: '[data-theme="{mode}"]'
+};
+var CSS_HEADER_PREFIX = "/* Generated by spec-layer";
+var EXT = "com.spec-layer";
+var CUSTOM_PROPERTY = /^--[A-Za-z0-9_-]+$/;
+var BARE_IDENT = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function acceptCssDeclared(declared) {
+  if (CUSTOM_PROPERTY.test(declared)) return declared;
+  if (BARE_IDENT.test(declared)) return `--${declared}`;
+  return null;
+}
+var asRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v) ? v : null;
+function collectLeaves(tree, prefix, out) {
+  const node = asRecord(tree);
+  if (!node) return;
+  if ("$value" in node) {
+    const ours = asRecord(asRecord(node.$extensions)?.[EXT]);
+    out.push({
+      path: prefix.join("."),
+      type: typeof node.$type === "string" ? node.$type : "",
+      value: node.$value,
+      ext: ours
+    });
+    return;
+  }
+  for (const key of Object.keys(node)) {
+    if (key.startsWith("$")) continue;
+    collectLeaves(node[key], [...prefix, key], out);
+  }
+}
+var unpointer = (s) => s.replace(/~1/g, "/").replace(/~0/g, "~");
+var refFile = (src) => {
+  const r = asRecord(src);
+  return r && typeof r.$ref === "string" ? r.$ref : null;
+};
+function sourcesOf(resolver) {
+  const out = [];
+  for (const { $ref } of resolver.resolutionOrder) {
+    const set = /^#\/sets\/(.+)$/.exec($ref);
+    const mod = /^#\/modifiers\/(.+)$/.exec($ref);
+    if (set) {
+      const label = unpointer(set[1]);
+      for (const src of resolver.sets[label]?.sources ?? []) {
+        const file = refFile(src);
+        if (file) out.push({ collection: label, mode: null, file, isDefault: true });
+      }
+    } else if (mod) {
+      const label = unpointer(mod[1]);
+      const m = resolver.modifiers[label];
+      if (!m) continue;
+      for (const [context, srcs] of Object.entries(m.contexts)) {
+        for (const src of srcs) {
+          const file = refFile(src);
+          if (file) out.push({ collection: label, mode: context, file, isDefault: context === m.default });
+        }
+      }
+    }
+  }
+  return out;
+}
+var modeSlug = (file) => file.replace(/\.json$/, "").split(".").slice(1).join(".");
+var collectionSlug = (file) => file.split(".")[0];
+var REF = /^\{(.+)\}$/;
+function hexChannels(hex) {
+  const at = (i) => parseInt(hex.slice(i, i + 2), 16);
+  return [at(1), at(3), at(5)];
+}
+var quoteFamily = (f) => `"${f.replace(/["\\]/g, "\\$&")}"`;
+function report(ctx, entry2) {
+  ctx.report.push({ ...entry2, path: ctx.path, ...ctx.mode !== void 0 ? { mode: ctx.mode } : {} });
+}
+function cssValue(ctx, type, value, property) {
+  const member = property !== void 0 ? { property } : {};
+  if (typeof value === "string") {
+    const ref = REF.exec(value);
+    if (ref) {
+      const name = ctx.alive.has(ref[1]) ? ctx.names.get(ref[1]) : void 0;
+      if (name !== void 0) return `var(${name})`;
+      report(ctx, {
+        code: "reference_target_omitted",
+        severity: "warning",
+        message: `References ${ref[1]}, which this output does not emit; the value was omitted.`,
+        details: { target: ref[1], ...member }
+      });
+      return null;
+    }
+  }
+  switch (type) {
+    case "color": {
+      if (typeof value === "string") return value;
+      const c = asRecord(value);
+      if (c && typeof c.hex === "string" && typeof c.alpha === "number") {
+        if (c.alpha === 1) return c.hex;
+        const [r, g, b] = hexChannels(c.hex);
+        return `rgb(${r} ${g} ${b} / ${c.alpha})`;
+      }
+      break;
+    }
+    case "dimension":
+    case "duration": {
+      if (typeof value === "string") return value;
+      const d = asRecord(value);
+      if (d && typeof d.value === "number" && typeof d.unit === "string") return `${d.value}${d.unit}`;
+      break;
+    }
+    case "number":
+    case "fontWeight":
+      if (typeof value === "number") return String(value);
+      break;
+    case "cubicBezier":
+      if (Array.isArray(value) && value.length === 4 && value.every((n) => typeof n === "number")) {
+        return `cubic-bezier(${value.join(", ")})`;
+      }
+      break;
+    case "fontFamily":
+      if (typeof value === "string") return quoteFamily(value);
+      if (Array.isArray(value) && value.every((f) => typeof f === "string")) {
+        return value.map(quoteFamily).join(", ");
+      }
+      break;
+    default:
+      break;
+  }
+  report(ctx, {
+    code: "not_expressible",
+    severity: "warning",
+    message: `CSS has no form for this ${type || "untyped"} value; it was omitted.`,
+    details: { type, value, ...member }
+  });
+  return null;
+}
+var TEXT_TRANSFORM = { original: "none", upper: "uppercase", lower: "lowercase", title: "capitalize" };
+var TEXT_DECORATION = { none: "none", underline: "underline", strikethrough: "line-through" };
+var TYPOGRAPHY_MEMBERS2 = [
+  ["fontFamily", "fontFamily"],
+  ["fontSize", "dimension"],
+  ["fontWeight", "fontWeight"],
+  ["lineHeight", "number"],
+  ["letterSpacing", "dimension"]
+];
+var TEXT_MEMBERS = [
+  ["textTransform", "textCase", TEXT_TRANSFORM],
+  ["textDecoration", "textDecoration", TEXT_DECORATION]
+];
+function typographyMemberKeys(value, ext) {
+  const keys = [];
+  for (const [key] of TYPOGRAPHY_MEMBERS2) {
+    if (key in value) keys.push(key);
+  }
+  for (const key of ["lineHeight", "letterSpacing"]) {
+    if (key in value) continue;
+    const d = asRecord(ext[key]);
+    if (d && typeof d.value === "number" && typeof d.unit === "string") keys.push(key);
+  }
+  for (const [key, extKey] of TEXT_MEMBERS) {
+    if (typeof ext[extKey] === "string") keys.push(key);
+  }
+  return keys;
+}
+function converted(ctx, property, from, to) {
+  report(ctx, {
+    code: "value_converted",
+    severity: "info",
+    message: `${property} was restated from ${String(from.value)}${String(from.unit)} as ${to}.`,
+    details: { property, from, to }
+  });
+}
+function extensionDimension(ctx, ext, key, name, percentTo) {
+  const d = asRecord(ext[key]);
+  if (!d || typeof d.value !== "number" || typeof d.unit !== "string") return null;
+  if (d.unit === "%") {
+    const to = percentTo(canonicalNumber(d.value / 100));
+    converted(ctx, key, d, to);
+    return `${name}: ${to};`;
+  }
+  return `${name}: ${d.value}${d.unit};`;
+}
+function typographyDecls(ctx, leaf, names) {
+  const decls = [];
+  const declaredPaths = [];
+  const value = asRecord(leaf.value) ?? {};
+  const ext = leaf.ext ?? {};
+  const nameFor = (key) => names.get(`${leaf.path}.${key}`);
+  for (const [key, type] of TYPOGRAPHY_MEMBERS2) {
+    if (!(key in value)) continue;
+    const name = nameFor(key);
+    if (name === void 0) continue;
+    const css = cssValue(ctx, type, value[key], key);
+    if (css !== null) {
+      decls.push(`${name}: ${css};`);
+      declaredPaths.push(`${leaf.path}.${key}`);
+    }
+  }
+  if (!("lineHeight" in value)) {
+    const name = nameFor("lineHeight");
+    if (name !== void 0) {
+      const d = extensionDimension(ctx, ext, "lineHeight", name, (n) => String(n));
+      if (d) {
+        decls.push(d);
+        declaredPaths.push(`${leaf.path}.lineHeight`);
+      }
+    }
+  }
+  if (!("letterSpacing" in value)) {
+    const name = nameFor("letterSpacing");
+    if (name !== void 0) {
+      const d = extensionDimension(ctx, ext, "letterSpacing", name, (n) => `${n}em`);
+      if (d) {
+        decls.push(d);
+        declaredPaths.push(`${leaf.path}.letterSpacing`);
+      }
+    }
+  }
+  for (const [key, extKey, table] of TEXT_MEMBERS) {
+    const raw = ext[extKey];
+    if (typeof raw !== "string") continue;
+    const name = nameFor(key);
+    if (name === void 0) continue;
+    const css = table[raw];
+    if (css !== void 0) {
+      decls.push(`${name}: ${css};`);
+      declaredPaths.push(`${leaf.path}.${key}`);
+    } else {
+      report(ctx, {
+        code: "not_expressible",
+        severity: "info",
+        message: `CSS text properties have no form for ${extKey} "${raw}"; it was omitted.`,
+        details: { property: extKey, value: raw }
+      });
+    }
+  }
+  return { decls, declaredPaths };
+}
+var SHADOW_MEMBERS = [
+  ["offsetX", "dimension"],
+  ["offsetY", "dimension"],
+  ["blur", "dimension"],
+  ["spread", "dimension"],
+  ["color", "color"]
+];
+function shadowDecl(ctx, leaf, name) {
+  const layers = Array.isArray(leaf.value) ? leaf.value : [];
+  const omit = (reason, message) => {
+    report(ctx, { code: "not_expressible", severity: "warning", message, details: { reason } });
+    return null;
+  };
+  if (layers.length === 0) return omit("no_visible_shadow", "The style has no visible shadow, so no box-shadow was written.");
+  const parts = [];
+  for (const layer of layers) {
+    const l = asRecord(layer);
+    if (!l) return omit("layer_not_an_object", "A shadow layer is not an object; the style was omitted.");
+    const members = [];
+    for (const [key, type] of SHADOW_MEMBERS) {
+      if (!(key in l)) return omit(`missing_${key}`, `A shadow layer has no ${key}, which box-shadow needs; the style was omitted.`);
+      const css = cssValue(ctx, type, l[key], key);
+      if (css === null) return null;
+      members.push(css);
+    }
+    parts.push(`${l.inset === true ? "inset " : ""}${members.join(" ")}`);
+  }
+  return `${name}: ${parts.join(", ")};`;
+}
+var commentSafe = (text) => text.replace(/\*\//g, "* /").replace(/[\r\n]+/g, " ");
+function headerText(header, nameCase) {
+  return `${CSS_HEADER_PREFIX} from library ${commentSafe(header.libraryId)}, foundation ${header.contentHash}, ${header.platform}/${header.format}/${nameCase}.
+   Do not edit. Change the design in Figma, republish, and run spec-layer pull. */`;
+}
+function emitPass(sources, leavesByFile, names, alive, root, template, modes) {
+  const entries = [];
+  const declared = /* @__PURE__ */ new Set();
+  const blocks = /* @__PURE__ */ new Map();
+  for (const s of sources) {
+    const perCollection = modes?.[s.collection];
+    const selector = s.isDefault ? root : (perCollection ?? template).replace(/\{mode\}/g, modeSlug(s.file)).replace(/\{collection\}/g, collectionSlug(s.file));
+    const decls = [];
+    for (const leaf of leavesByFile.get(s.file) ?? []) {
+      const ctx = { names, alive, report: entries, path: leaf.path, ...s.mode !== null ? { mode: s.mode } : {} };
+      if (leaf.type === "typography") {
+        const t = typographyDecls(ctx, leaf, names);
+        decls.push(...t.decls);
+        for (const p of t.declaredPaths) declared.add(p);
+      } else {
+        const name = names.get(leaf.path);
+        if (name === void 0) continue;
+        if (leaf.type === "shadow") {
+          const d = shadowDecl(ctx, leaf, name);
+          if (d !== null) {
+            decls.push(d);
+            declared.add(leaf.path);
+          }
+        } else {
+          const v = cssValue(ctx, leaf.type, leaf.value);
+          if (v !== null) {
+            decls.push(`${name}: ${v};`);
+            declared.add(leaf.path);
+          }
+        }
+      }
+    }
+    if (decls.length === 0) continue;
+    const lines = blocks.get(selector) ?? [];
+    lines.push(`  /* ${commentSafe(`${s.collection}${s.mode !== null ? `, ${s.mode}` : ""}`)} */`, ...decls.map((d) => `  ${d}`));
+    blocks.set(selector, lines);
+  }
+  return { blocks, entries, declared };
+}
+function cssOutput(exp, header, options = {}) {
+  const nameCase = options.case ?? CSS_DEFAULTS.case;
+  const root = options.root ?? CSS_DEFAULTS.root;
+  const template = options.modeSelector ?? CSS_DEFAULTS.modeSelector;
+  const sources = sourcesOf(exp.resolver);
+  const leavesByFile = /* @__PURE__ */ new Map();
+  for (const s of sources) {
+    if (!leavesByFile.has(s.file)) {
+      const out = [];
+      collectLeaves(exp.files[s.file] ?? {}, [], out);
+      leavesByFile.set(s.file, out);
+    }
+  }
+  const candidatePaths = /* @__PURE__ */ new Set();
+  for (const leaves of leavesByFile.values()) {
+    for (const leaf of leaves) {
+      if (leaf.type === "typography") {
+        const value = asRecord(leaf.value) ?? {};
+        const ext = leaf.ext ?? {};
+        for (const key of typographyMemberKeys(value, ext)) candidatePaths.add(`${leaf.path}.${key}`);
+      } else {
+        candidatePaths.add(leaf.path);
+      }
+    }
+  }
+  const resolved2 = resolveNames([...candidatePaths], exp.meta, {
+    codeSyntaxKey: "WEB",
+    acceptDeclared: acceptCssDeclared,
+    affix: (body2) => `--${body2}`,
+    nameCase
+  });
+  const names = resolved2.names;
+  const emit = (alive2) => emitPass(sources, leavesByFile, names, alive2, root, template, options.modes);
+  let alive = new Set(names.keys());
+  let pass = emit(alive);
+  for (; ; ) {
+    if (pass.declared.size === alive.size) break;
+    alive = pass.declared;
+    pass = emit(alive);
+  }
+  const map = {};
+  for (const [path, entry2] of Object.entries(resolved2.map)) {
+    if (alive.has(path)) map[path] = entry2;
+  }
+  const entries = [...resolved2.report, ...pass.entries];
+  const shared = [...new Set(sources.filter((s) => !s.isDefault && options.modes?.[s.collection] === void 0).map((s) => s.collection))].sort(compareCodeUnits);
+  if (shared.length > 1) {
+    for (const collection of shared) {
+      entries.push({
+        code: "mode_selector_shared",
+        severity: "warning",
+        path: collection,
+        message: `${shared.length} collections with modes share the selector template ${template}; one attribute cannot carry both axes. Declare a selector per collection under outputs[].modes.`,
+        details: { modifiers: shared, selector: template }
+      });
+    }
+  }
+  const body = [...pass.blocks].flatMap(([selector, lines]) => [`${selector} {`, ...lines, "}", ""]);
+  const text = `${[headerText(header, nameCase), "", ...body].join("\n").trimEnd()}
+`;
+  return { text, map, report: sortReport(entries) };
+}
+
 // ../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 isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
@@ -2101,6 +2561,9 @@ function parseLibraryBundle(input) {
   };
 }
 
+// ../extractor/src/libraryBundleHash.ts
+var import_js_sha2564 = __toESM(require_sha256(), 1);
+
 // src/bundle.ts
 function parseBundle(raw) {
   try {
@@ -2121,8 +2584,8 @@ function parseBundle(raw) {
 }
 
 // src/config.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "node:fs";
-import { join as join2 } from "node:path";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync4 } from "node:fs";
+import { join as join3 } from "node:path";
 
 // src/credentials.ts
 import { readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
@@ -2155,6 +2618,268 @@ function writeCredentials(cwd, stored) {
   return { replaced };
 }
 
+// src/detect.ts
+import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { join as join2 } 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 = join2(cwd, "package.json");
+  if (!existsSync2(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync2(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 = readdirSync(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 (existsSync2(join2(cwd, ".github", "copilot-instructions.md")) || existsSync2(join2(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/outputs.ts
+import {
+  existsSync as existsSync3,
+  mkdirSync,
+  readFileSync as readFileSync3,
+  renameSync,
+  rmSync,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+var FORMATS = [
+  { platform: "web", format: "css", defaultPath: "spec-layer/tokens.css", defaultCase: "kebab", headerPrefix: CSS_HEADER_PREFIX }
+];
+var knownFormats = () => FORMATS.map((f) => `${f.platform}/${f.format}`).join(", ");
+var specOf = (platform, format) => FORMATS.find((f) => f.platform === platform && f.format === format) ?? null;
+function defaultOutputs(platforms) {
+  return FORMATS.filter((f) => f.defaultPath !== null && platforms.includes(f.platform)).map((f) => ({ platform: f.platform, format: f.format, path: f.defaultPath, case: f.defaultCase }));
+}
+function withDefaults(existing, platforms) {
+  const covered = new Set(existing.map((o) => o.platform));
+  return [...existing, ...defaultOutputs(platforms.filter((p) => !covered.has(p)))];
+}
+var outputId = (o) => `${o.platform}-${o.format}`;
+function parseOutput(value, index) {
+  const at = `speclayer.json outputs[${index}]`;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error(`${at} must be an object.`);
+  const r = value;
+  if (typeof r.platform !== "string" || typeof r.format !== "string") {
+    throw new Error(`${at} needs "platform" and "format". Known: ${knownFormats()}.`);
+  }
+  const spec = specOf(r.platform, r.format);
+  if (!spec) throw new Error(`${at}: unknown platform/format "${r.platform}/${r.format}". Known: ${knownFormats()}.`);
+  const str = (key) => {
+    if (r[key] !== void 0 && typeof r[key] !== "string") throw new Error(`${at} "${key}" must be a string.`);
+    return r[key];
+  };
+  const path = str("path") ?? spec.defaultPath;
+  if (path === null) throw new Error(`${at} needs "path": ${spec.platform} has no default location.`);
+  const nameCase = str("case");
+  if (nameCase !== void 0 && !NAME_CASES.includes(nameCase)) {
+    throw new Error(`${at} "case" takes ${NAME_CASES.join(", ")}.`);
+  }
+  const root = str("root");
+  const modeSelector = str("modeSelector");
+  let modes;
+  if (r.modes !== void 0) {
+    const m = r.modes;
+    if (typeof m !== "object" || m === null || Array.isArray(m) || !Object.values(m).every((v) => typeof v === "string")) {
+      throw new Error(`${at} "modes" must map collection names to selector strings.`);
+    }
+    modes = m;
+  }
+  return {
+    platform: spec.platform,
+    format: spec.format,
+    path,
+    case: nameCase ?? spec.defaultCase,
+    ...root !== void 0 ? { root } : {},
+    ...modeSelector !== void 0 ? { modeSelector } : {},
+    ...modes ? { modes } : {}
+  };
+}
+function renderOutput(exp, o, header) {
+  switch (o.format) {
+    case "css":
+      return cssOutput(exp, { ...header, platform: o.platform, format: o.format }, {
+        case: o.case,
+        ...o.root !== void 0 ? { root: o.root } : {},
+        ...o.modeSelector !== void 0 ? { modeSelector: o.modeSelector } : {},
+        ...o.modes ? { modes: o.modes } : {}
+      });
+    default: {
+      const exhaustive = o.format;
+      return exhaustive;
+    }
+  }
+}
+var inside = (parent, child) => {
+  const rel = relative(parent, child);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+};
+function outputPathProblem(cwd, outDir, o) {
+  const root = resolve(cwd);
+  const abs = resolve(cwd, o.path);
+  if (!inside(root, abs) || abs === root) return `${o.path} is outside this directory. Choose a path inside the repository.`;
+  if (inside(resolve(cwd, outDir), abs)) {
+    return `${o.path} is inside ${outDir}, which pull replaces wholesale. Choose a path outside it.`;
+  }
+  if (existsSync3(abs)) {
+    const prefix = specOf(o.platform, o.format)?.headerPrefix ?? CSS_HEADER_PREFIX;
+    let head;
+    try {
+      head = readFileSync3(abs, "utf8").slice(0, prefix.length);
+    } catch {
+      return `${o.path} exists and could not be read.`;
+    }
+    if (head !== prefix) return `${o.path} exists and was not written by spec-layer. Choose another path or remove the file.`;
+  }
+  return null;
+}
+function writeOutputFile(cwd, o, text) {
+  const abs = resolve(cwd, o.path);
+  mkdirSync(dirname(abs), { recursive: true });
+  const partial = `${abs}.partial`;
+  writeFileSync2(partial, text);
+  try {
+    renameSync(partial, abs);
+  } catch (err) {
+    rmSync(partial, { force: true });
+    throw err;
+  }
+}
+
 // src/config.ts
 var DEFAULT_API = "https://api.spec-layer.com";
 var DEFAULT_OUT_DIR = ".speclayer";
@@ -2164,12 +2889,12 @@ function parseInclude(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) throw invalidConfig();
   const record = value;
   if (record.foundation !== void 0 && typeof record.foundation !== "boolean") throw invalidConfig();
-  if (record.components !== void 0 && !(Array.isArray(record.components) && record.components.every((c) => typeof c === "string"))) {
+  if (record.components !== void 0 && record.components !== null && !(Array.isArray(record.components) && record.components.every((c) => typeof c === "string"))) {
     throw invalidConfig();
   }
   return {
     foundation: record.foundation === void 0 ? true : record.foundation,
-    components: record.components === void 0 ? null : record.components
+    components: record.components ?? null
   };
 }
 function parseDtcg(value) {
@@ -2189,12 +2914,31 @@ function parseDtcg(value) {
   }
   return out;
 }
+function parsePlatforms(value) {
+  if (!Array.isArray(value) || !value.every((p) => typeof p === "string" && isPlatform(p))) {
+    throw new Error(`speclayer.json "platforms" must be an array of ${PLATFORMS.join(", ")}.`);
+  }
+  return [...new Set(value)];
+}
+function parseOutputs(value) {
+  if (!Array.isArray(value)) throw new Error('speclayer.json "outputs" must be an array.');
+  const outputs = value.map((v, i) => parseOutput(v, i));
+  const seen = /* @__PURE__ */ new Set();
+  for (const output of outputs) {
+    const key = `${output.platform}/${output.format}`;
+    if (seen.has(key)) {
+      throw new Error(`speclayer.json "outputs" lists ${output.platform}/${output.format} more than once. Keep one entry per platform and format.`);
+    }
+    seen.add(key);
+  }
+  return outputs;
+}
 function readConfig(cwd) {
-  const path = join2(cwd, CONFIG_NAME);
-  if (!existsSync2(path)) return null;
+  const path = join3(cwd, CONFIG_NAME);
+  if (!existsSync4(path)) return null;
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync2(path, "utf8"));
+    parsed = JSON.parse(readFileSync4(path, "utf8"));
   } catch {
     throw invalidConfig();
   }
@@ -2204,7 +2948,9 @@ function readConfig(cwd) {
     ...typeof record.libraryId === "string" ? { libraryId: record.libraryId } : {},
     ...typeof record.outDir === "string" ? { outDir: record.outDir } : {},
     ...record.include !== void 0 ? { include: parseInclude(record.include) } : {},
-    ...record.dtcg !== void 0 ? { dtcg: parseDtcg(record.dtcg) } : {}
+    ...record.dtcg !== void 0 ? { dtcg: parseDtcg(record.dtcg) } : {},
+    ...record.platforms !== void 0 ? { platforms: parsePlatforms(record.platforms) } : {},
+    ...record.outputs !== void 0 ? { outputs: parseOutputs(record.outputs) } : {}
   };
 }
 function writeConfig(cwd, config) {
@@ -2212,15 +2958,17 @@ function writeConfig(cwd, config) {
     libraryId: config.libraryId,
     outDir: config.outDir,
     ...config.include ? { include: config.include } : {},
-    ...config.dtcg ? { dtcg: config.dtcg } : {}
+    ...config.dtcg ? { dtcg: config.dtcg } : {},
+    ...config.platforms && config.platforms.length > 0 ? { platforms: config.platforms } : {},
+    ...config.outputs ? { outputs: config.outputs } : {}
   };
-  writeFileSync2(join2(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
+  writeFileSync3(join3(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
 `);
 }
 function resolveOptions(cwd, flags, env, manifestLibraryId) {
   const config = readConfig(cwd);
   const outDir = flags.out ?? config?.outDir ?? DEFAULT_OUT_DIR;
-  const libraryId = flags.id ?? config?.libraryId ?? manifestLibraryId(join2(cwd, outDir));
+  const libraryId = flags.id ?? config?.libraryId ?? manifestLibraryId(join3(cwd, outDir));
   const supplied = flags.key || env.SPEC_LAYER_KEY || null;
   let storedKey = null;
   let storedKeyFor;
@@ -2239,6 +2987,8 @@ function resolveOptions(cwd, flags, env, manifestLibraryId) {
     key: supplied ?? storedKey,
     ...config?.include ? { include: config.include } : {},
     ...config?.dtcg ? { dtcg: config.dtcg } : {},
+    ...config?.platforms ? { platforms: config.platforms } : {},
+    ...config?.outputs ? { outputs: config.outputs } : {},
     ...storedKeyFor ? { storedKeyFor } : {}
   };
 }
@@ -2277,8 +3027,8 @@ async function fetchBundle(opts) {
 }
 
 // src/files.ts
-import { mkdirSync, writeFileSync as writeFileSync3, readFileSync as readFileSync3, readdirSync, rmSync, renameSync, existsSync as existsSync3 } from "node:fs";
-import { join as join3, dirname, relative, resolve, isAbsolute } from "node:path";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4, readFileSync as readFileSync5, readdirSync as readdirSync2, rmSync as rmSync2, renameSync as renameSync2, existsSync as existsSync5 } from "node:fs";
+import { join as join4, dirname as dirname2, relative as relative2, resolve as resolve2, isAbsolute as isAbsolute2 } from "node:path";
 
 // src/selection.ts
 var DEFAULT_SELECTION = { foundation: true, components: null };
@@ -2317,19 +3067,27 @@ function slugify(name) {
   return slug2 || "component";
 }
 function readManifest(outDir) {
-  const path = join3(outDir, "manifest.json");
-  if (!existsSync3(path)) return null;
+  const path = join4(outDir, "manifest.json");
+  if (!existsSync5(path)) return null;
   try {
-    return JSON.parse(readFileSync3(path, "utf8"));
+    const parsed = JSON.parse(readFileSync5(path, "utf8"));
+    parsed.artifacts = parsed.artifacts.map((artifact) => {
+      const { aiPath, ...rest } = artifact;
+      return {
+        ...rest,
+        path: rest.path ?? aiPath ?? null
+      };
+    });
+    return parsed;
   } catch {
     return null;
   }
 }
 function readLocalBundle(outDir) {
-  const path = join3(outDir, "bundle.json");
-  if (!existsSync3(path)) return null;
+  const path = join4(outDir, "bundle.json");
+  if (!existsSync5(path)) return null;
   try {
-    return parseBundle(readFileSync3(path, "utf8"));
+    return parseBundle(readFileSync5(path, "utf8"));
   } catch {
     throw new Error(`${path} could not be read as a library bundle. Run spec-layer pull again.`);
   }
@@ -2356,11 +3114,11 @@ function componentSlugs(bundle) {
   });
 }
 function assertReplaceable(outDir, cwd) {
-  const rel = relative(resolve(cwd), resolve(outDir));
-  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+  const rel = relative2(resolve2(cwd), resolve2(outDir));
+  if (rel === "" || rel.startsWith("..") || isAbsolute2(rel)) {
     throw new Error('The output directory must sit inside the current directory, not be "." or a parent of it.');
   }
-  if (existsSync3(outDir) && !existsSync3(join3(outDir, "manifest.json")) && readdirSync(outDir).length > 0) {
+  if (existsSync5(outDir) && !existsSync5(join4(outDir, "manifest.json")) && readdirSync2(outDir).length > 0) {
     throw new Error(`${outDir} exists and was not written by spec-layer pull. Choose an empty or new directory.`);
   }
 }
@@ -2369,44 +3127,62 @@ function writeBundleFiles(opts) {
   const selection = opts.selection ?? DEFAULT_SELECTION;
   const selected = selectComponents(opts.bundle, selection);
   const slugs = componentSlugs(opts.bundle);
+  const outputs = opts.outputs ?? [];
+  const willWriteFoundation = Boolean(opts.bundle.foundation) && selection.foundation;
+  if (willWriteFoundation) {
+    for (const o of outputs) {
+      const problem = outputPathProblem(opts.cwd, opts.outDir, o);
+      if (problem) throw new Error(problem);
+    }
+  }
   const staging = `${opts.outDir}.partial`;
-  rmSync(staging, { recursive: true, force: true });
+  rmSync2(staging, { recursive: true, force: true });
   const written = [];
+  const deliverables = [];
+  const json = (v) => `${JSON.stringify(v, null, 2)}
+`;
   const put = (rel, content) => {
-    const path = join3(staging, rel);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync3(path, content);
+    const path = join4(staging, rel);
+    mkdirSync2(dirname2(path), { recursive: true });
+    writeFileSync4(path, content);
     written.push(rel);
   };
   try {
     put("bundle.json", opts.raw);
     const artifacts = [];
     if (opts.bundle.foundation) {
-      let aiPath = null;
+      let path = 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";
+        const exp = foundationDtcg(artifact, opts.dtcg ?? {});
+        for (const [name, text] of Object.entries(dtcgExportFiles(exp))) put(`tokens/${name}`, text);
+        path = "tokens/resolver.json";
+        const header = { libraryId: opts.libraryId, contentHash: opts.bundle.foundation.artifact.spec_layer.export.content_hash };
+        for (const output of outputs) {
+          const rendered = renderOutput(exp, output, header);
+          put(`outputs/${outputId(output)}.map.json`, json(rendered.map));
+          put(`outputs/${outputId(output)}.report.json`, json(rendered.report));
+          deliverables.push({ output, text: rendered.text });
+        }
       }
       artifacts.push({
         kind: "foundation",
         name: "foundation",
         contentHash: opts.bundle.foundation.artifact.spec_layer.export.content_hash,
-        aiPath
+        path
       });
     }
     opts.bundle.components.forEach((component, i) => {
-      const aiPath = selected[i] ? `ai/components/${slugs[i]}.yaml` : null;
-      if (aiPath) put(aiPath, component.ai);
+      const path = selected[i] ? `components/${slugs[i]}.yaml` : null;
+      if (path) put(path, component.ai);
       artifacts.push({
         kind: "component",
         name: component.name,
         contentHash: component.artifact.spec_layer.export.content_hash,
-        aiPath
+        path
       });
     });
     const manifest = {
@@ -2417,23 +3193,29 @@ function writeBundleFiles(opts) {
       extractorVersion: opts.bundle.extractorVersion,
       selection,
       artifacts,
-      ...opts.dtcg && Object.keys(opts.dtcg).length > 0 ? { dtcg: opts.dtcg } : {}
+      ...opts.dtcg && Object.keys(opts.dtcg).length > 0 ? { dtcg: opts.dtcg } : {},
+      ...opts.platforms && opts.platforms.length > 0 ? { platforms: opts.platforms } : {},
+      ...opts.outputs ? { outputs: opts.outputs } : {}
     };
-    put("manifest.json", `${JSON.stringify(manifest, null, 2)}
-`);
+    put("manifest.json", json(manifest));
   } catch (err) {
-    rmSync(staging, { recursive: true, force: true });
+    rmSync2(staging, { recursive: true, force: true });
     throw err;
   }
-  rmSync(opts.outDir, { recursive: true, force: true });
-  renameSync(staging, opts.outDir);
-  return written;
+  rmSync2(opts.outDir, { recursive: true, force: true });
+  renameSync2(staging, opts.outDir);
+  const outputPaths = [];
+  for (const d of deliverables) {
+    writeOutputFile(opts.cwd, d.output, d.text);
+    outputPaths.push(d.output.path);
+  }
+  return { written, outputs: outputPaths };
 }
 
 // src/gitignore.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync4 } from "node:fs";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync6 } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { join as join4, dirname as dirname2, resolve as resolve2 } from "node:path";
+import { join as join5, dirname as dirname3, resolve as resolve3 } from "node:path";
 var COMMENT = "# Spec Layer pull key, not for committing";
 function git(cwd, args) {
   const res = spawnSync("git", args, { cwd, stdio: ["ignore", "pipe", "ignore"], encoding: "utf8" });
@@ -2441,10 +3223,10 @@ function git(cwd, args) {
   return { ranGit: true, status: res.status, stdout: res.stdout ?? "" };
 }
 function insideWorkTreeWithoutGit(cwd) {
-  let dir = resolve2(cwd);
+  let dir = resolve3(cwd);
   for (; ; ) {
-    if (existsSync4(join4(dir, ".git"))) return true;
-    const parent = dirname2(dir);
+    if (existsSync6(join5(dir, ".git"))) return true;
+    const parent = dirname3(dir);
     if (parent === dir) return false;
     dir = parent;
   }
@@ -2460,18 +3242,18 @@ function ensureIgnored(cwd, fileName) {
   if (inWorkTree.status !== 0 || inWorkTree.stdout.trim() !== "true") return { kind: "not-a-repo" };
   const checkIgnore = git(cwd, ["check-ignore", "-q", fileName]);
   if (checkIgnore.ranGit && checkIgnore.status === 0) return { kind: "already" };
-  const path = join4(cwd, ".gitignore");
-  const existed = existsSync4(path);
+  const path = join5(cwd, ".gitignore");
+  const existed = existsSync6(path);
   try {
     if (!existed) {
-      writeFileSync4(path, `${COMMENT}
+      writeFileSync5(path, `${COMMENT}
 ${fileName}
 `);
     } else {
-      const body = readFileSync4(path, "utf8");
+      const body = readFileSync6(path, "utf8");
       if (!hasEntryLine(body, fileName)) {
         const lead = body.length === 0 || body.endsWith("\n") ? "" : "\n";
-        writeFileSync4(path, `${body}${lead}${COMMENT}
+        writeFileSync5(path, `${body}${lead}${COMMENT}
 ${fileName}
 `);
       }
@@ -2484,6 +3266,524 @@ ${fileName}
   return existed ? { kind: "added" } : { kind: "created" };
 }
 
+// src/skill.ts
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync7, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname4, 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] [--platform web|ios|android|flutter]... [--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>/",
+      "outputs[].path from speclayer.json (default spec-layer/tokens.css for web), written in place"
+    ],
+    exits: OK_OR_ERROR
+  },
+  {
+    name: "init",
+    usage: "spec-layer init --id lib_... [--out DIR] [--platform web|ios|android|flutter]... [--only foundation|components] [--component NAME]...",
+    summary: "Writes speclayer.json, with the platforms and default outputs, so later commands need no flags. Stores no key and reaches no server.",
+    when: "A repo that supplies the key from SPEC_LAYER_KEY instead of a stored file.",
+    network: false,
+    needsKey: false,
+    writes: ["speclayer.json"],
+    exits: { "0": "success", "1": "usage error" }
+  },
+  {
+    name: "pull",
+    usage: "spec-layer pull [--id lib_...] [--key sl_...] [--out DIR] [--platform web|ios|android|flutter]... [--only foundation|components] [--component NAME]...",
+    summary: "Fetches the published library and writes 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, or the outputs block.",
+    network: true,
+    needsKey: true,
+    writes: ["<outDir>/", "outputs[].path from speclayer.json (default spec-layer/tokens.css for web), written in place"],
+    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 (!existsSync7(path)) return null;
+  try {
+    return JSON.parse(readFileSync7(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.path ? `${outDir}/${a.path}` : 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 report2 = 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(report2)) {
+      for (const entry2 of report2) {
+        if (typeof entry2?.code === "string") reportCounts[entry2.code] = (reportCounts[entry2.code] ?? 0) + 1;
+      }
+    }
+    foundation = {
+      written: foundationEntry.path !== 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,
+    outputs: (manifest.outputs ?? []).map((o) => ({
+      platform: o.platform,
+      format: o.format,
+      path: o.path,
+      case: o.case,
+      modeSelector: o.modeSelector ?? '[data-theme="{mode}"]',
+      modes: o.modes ?? {},
+      // manifest.outputs records the configured list regardless of whether the
+      // Foundation was written; the map file exists only when it was actually
+      // rendered, so it is the on-disk proof a sentence can point to.
+      written: existsSync7(join6(absOut, "outputs", `${o.platform}-${o.format}.map.json`))
+    }))
+  };
+}
+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" : platformSource === "config" ? "set in speclayer.json" : "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", "");
+      const cssOut = pull?.outputs.find((o) => o.platform === "web" && o.format === "css" && o.written) ?? null;
+      if (cssOut) {
+        const mapPath = `${input.outDir}/outputs/web-css.map.json`;
+        lines.push(
+          `The CSS custom property for every token is in ${code(mapPath)}: source "code_syntax" when the designer declared it in Figma, "derived" when the CLI built it from the DTCG path by the stated rule (${cssOut.case} case, collection root included). Use those names; never invent a third. ${code(`${tokensDir}spec-layer.meta.json`)} still holds the raw ${code("code_syntax.WEB")} the designer declared.`,
+          ""
+        );
+        lines.push(
+          `Import ${code(cssOut.path)} from the root stylesheet. It holds every set and every default mode at ${code(":root")}; every other mode is a block under ${code(cssOut.modeSelector)}. To switch, set ${code("data-theme")} on ${code("<html>")} (or whatever the selector names). Wire it to prefers-color-scheme yourself if the OS should choose; the file never assumes that.`,
+          ""
+        );
+        if (profile.tokenTools.includes("style-dictionary") || profile.tokenTools.includes("tokens-studio")) {
+          lines.push(
+            `${code(cssOut.path)} is a projection of the same ${code("tokens/")} files, not a second source. Import one or the other.`,
+            ""
+          );
+        }
+      } else {
+        lines.push(
+          `Token identifiers for code live in ${code(`${tokensDir}spec-layer.meta.json`)} under each token's ${code(`code_syntax.${key}`)}, when the designer declared one in Figma. When a token has no WEB entry, use the DTCG path as it appears in the token file and say in your change that the code name is not declared in Figma.`,
+          ""
+        );
+        const configuredNotWritten = pull?.outputs.find((o) => o.platform === "web" && !o.written) ?? null;
+        if (configuredNotWritten) {
+          lines.push(
+            `A web/css output is configured at ${code(configuredNotWritten.path)} but was not written, because the last pull did not write the Foundation. Pull with the Foundation selected to write it.`,
+            ""
+          );
+        } else if (pull?.foundation?.written) {
+          lines.push(
+            `No token file was written for web. Add \`"outputs"\` in \`speclayer.json\` (or run \`spec-layer pull --platform web\` once) and pull again; the default lands at ${code("spec-layer/tokens.css")}.`,
+            ""
+          );
+        }
+      }
+      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}/components/`)}: one YAML per component.`);
+  for (const o of pull.outputs) {
+    lines.push(o.written ? `- ${code(o.path)}: ${o.platform}/${o.format} token file, ${o.case} names, modes under ${code(o.modeSelector)}. Names and provenance: ${code(`${outDir}/outputs/${o.platform}-${o.format}.map.json`)}; what it could not express: ${code(`${outDir}/outputs/${o.platform}-${o.format}.report.json`)}.` : `- ${code(o.path)}: ${o.platform}/${o.format} token file, configured but not written by the last pull (the Foundation was not written). Nothing is on disk at that path from Spec Layer.`);
+  }
+  lines.push("");
+  if (pull.foundation && (pull.foundation.sets.length || pull.foundation.modifiers.length)) {
+    lines.push("### Token collections", "");
+    for (const set of pull.foundation.sets) lines.push(`- ${code(set)}: one mode, always applied.`);
+    for (const 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}/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.`);
+  const writtenOutputs = input.pull?.outputs.filter((o) => o.written) ?? [];
+  const outputNote = writtenOutputs.length ? ` Never edit ${writtenOutputs.map((o) => code(o.path)).join(", ")} either: pull replaces ${writtenOutputs.length === 1 ? "it" : "them"} in place.` : "";
+  lines.push(`6. Never edit files under ${code(outDir + "/")}: the next pull replaces the whole directory.${outputNote} 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 = existsSync7(abs) ? readFileSync7(abs, "utf8") : null;
+  const next = target.mode === "file" ? renderForHost(host, guide) : upsertBlock(existing, renderForHost(host, guide));
+  if (existing === next) return { path: target.path, result: "unchanged" };
+  mkdirSync3(dirname4(abs), { recursive: true });
+  writeFileSync6(abs, next);
+  return { path: target.path, result: existing === null ? "created" : "updated" };
+}
+
+// src/version.ts
+import { readFileSync as readFileSync8 } from "node:fs";
+function cliVersion() {
+  try {
+    const parsed = JSON.parse(readFileSync8(new URL("../package.json", import.meta.url), "utf8"));
+    return typeof parsed.version === "string" ? parsed.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
 // src/commands.ts
 var NO_LOCAL_PULL = "No local pull found. Run spec-layer pull.";
 function manifestReader() {
@@ -2495,8 +3795,8 @@ function manifestReader() {
 }
 function sameOutput(a, b) {
   const selectionKey = (s) => JSON.stringify([s.foundation, s.components === null ? null : [...new Set(s.components.map(slugify))].sort()]);
-  const dtcgKey = (d) => JSON.stringify(sortKeys(d ?? {}));
-  return selectionKey(a.selection) === selectionKey(b.selection) && dtcgKey(a.dtcg) === dtcgKey(b.dtcg);
+  const key = (v) => JSON.stringify(sortKeys(v ?? {}));
+  return selectionKey(a.selection) === selectionKey(b.selection) && key(a.dtcg) === key(b.dtcg) && key(a.outputs ?? []) === key(b.outputs ?? []);
 }
 function sortKeys(value) {
   if (Array.isArray(value)) return value.map(sortKeys);
@@ -2505,6 +3805,35 @@ function sortKeys(value) {
   }
   return value;
 }
+function platformsFromFlags(flags, io2) {
+  if (flags.platform === void 0 || flags.platform.length === 0) return void 0;
+  const out = [];
+  for (const value of flags.platform) {
+    if (!isPlatform(value)) {
+      io2.err(`--platform takes ${PLATFORMS.join(", ")}, not "${value}".`);
+      return null;
+    }
+    if (!out.includes(value)) out.push(value);
+  }
+  return out;
+}
+function resolvePlatforms(cwd, fromFlags, config) {
+  if (fromFlags) return { platforms: fromFlags, source: "flag" };
+  if (config?.platforms && config.platforms.length > 0) return { platforms: config.platforms, source: "config" };
+  const detected = detectRepo(cwd).platforms;
+  return { platforms: detected, source: detected.length > 0 ? "detected" : "none" };
+}
+function outputsForRun(fromFlags, config, platforms) {
+  if (fromFlags) return withDefaults(config?.outputs ?? [], fromFlags);
+  return config?.outputs ?? defaultOutputs(platforms);
+}
+var NO_PLATFORM_NOTE = `No target platform detected, so no token file was written for your code. Pass --platform ${PLATFORMS.join("|")}, or add outputs to speclayer.json.`;
+function platformsMissingFormat(platforms) {
+  return platforms.filter((p) => !FORMATS.some((f) => f.platform === p));
+}
+function missingFormatNote(platforms) {
+  return `No token file exists yet for ${platforms.join(", ")}: no output format is available for that platform. Web has css.`;
+}
 var errorText = (err) => err instanceof Error ? err.message : String(err);
 function runInit(cwd, flags, io2) {
   if (!flags.id) {
@@ -2518,9 +3847,24 @@ function runInit(cwd, flags, io2) {
     io2.err(errorText(err));
     return 1;
   }
+  const fromFlags = platformsFromFlags(flags, io2);
+  if (fromFlags === null) return 1;
+  const { platforms, source } = resolvePlatforms(cwd, fromFlags, null);
+  const outputs = defaultOutputs(platforms);
   const outDir = flags.out ?? DEFAULT_OUT_DIR;
-  writeConfig(cwd, { libraryId: flags.id, outDir, ...include ? { include } : {} });
-  io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}).`);
+  writeConfig(cwd, {
+    libraryId: flags.id,
+    outDir,
+    ...include ? { include } : {},
+    ...platforms.length > 0 ? { platforms } : {},
+    ...outputs.length > 0 ? { outputs } : {}
+  });
+  io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}${platforms.length > 0 ? `, platforms ${platforms.join(", ")}` : ""}).`);
+  for (const o of outputs) io2.out(`Token file for ${o.platform}: ${o.path} (${o.format}, ${o.case} names), written by the next pull.`);
+  if (source === "flag" || source === "detected") {
+    const missing = platformsMissingFormat(platforms);
+    if (missing.length > 0) io2.out(missingFormatNote(missing));
+  }
   io2.out(`The pull key is not stored here. Run spec-layer setup to store it in ${CREDENTIALS_NAME}, or set SPEC_LAYER_KEY.`);
   return 0;
 }
@@ -2544,7 +3888,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;
@@ -2580,16 +3924,22 @@ async function runSetup(cwd, flags, env, io2, fetcher) {
   } catch {
     existing = null;
   }
+  const fromFlags = platformsFromFlags(flags, io2);
+  if (fromFlags === null) return 1;
   const outDir = flags.out ?? existing?.outDir ?? DEFAULT_OUT_DIR;
   const keptInclude = include ?? existing?.include ?? null;
   const keptDtcg = existing?.dtcg ?? null;
+  const { platforms } = resolvePlatforms(cwd, fromFlags, existing);
+  const outputs = withDefaults(existing?.outputs ?? [], platforms);
   writeConfig(cwd, {
     libraryId: flags.id,
     outDir,
     ...keptInclude ? { include: keptInclude } : {},
-    ...keptDtcg ? { dtcg: keptDtcg } : {}
+    ...keptDtcg ? { dtcg: keptDtcg } : {},
+    ...platforms.length > 0 ? { platforms } : {},
+    ...existing?.outputs !== void 0 || outputs.length > 0 ? { outputs } : {}
   });
-  io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}).`);
+  io2.out(`Wrote speclayer.json (library ${flags.id}, output ${outDir}${platforms.length > 0 ? `, platforms ${platforms.join(", ")}` : ""}).`);
   const ignored = ensureIgnored(cwd, CREDENTIALS_NAME);
   switch (ignored.kind) {
     case "refused":
@@ -2627,7 +3977,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();
@@ -2640,11 +3997,17 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     io2.err(errorText(err));
     return 1;
   }
-  const manifest = manifestAt(join5(cwd, opts.outDir));
+  const fromFlags = platformsFromFlags(flags, io2);
+  if (fromFlags === null) return 1;
+  const { platforms, source } = resolvePlatforms(cwd, fromFlags, opts);
+  const outputs = outputsForRun(fromFlags, opts, platforms);
+  const manifest = manifestAt(join7(cwd, opts.outDir));
+  const foundationOnDisk = Boolean(manifest?.artifacts.find((a) => a.kind === "foundation")?.path);
+  const willWriteFoundation = selection.foundation && foundationOnDisk;
   const etag = manifest && sameOutput(
-    { selection: manifest.selection ?? DEFAULT_SELECTION, dtcg: manifest.dtcg },
-    { selection, dtcg: opts.dtcg }
-  ) ? manifest.bundleHash : void 0;
+    { selection: manifest.selection ?? DEFAULT_SELECTION, dtcg: manifest.dtcg, outputs: manifest.outputs },
+    { selection, dtcg: opts.dtcg, outputs }
+  ) && (!willWriteFoundation || outputs.every((o) => existsSync8(resolve4(cwd, o.path)) && existsSync8(join7(cwd, opts.outDir, "outputs", `${outputId(o)}.map.json`)))) ? manifest.bundleHash : void 0;
   const result = await fetchBundle({
     api: opts.api,
     libraryId: opts.libraryId,
@@ -2661,11 +4024,12 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     return 0;
   }
   let written;
+  let outputPaths = [];
   try {
     const bundle = parseBundle(result.raw);
     const selected = selectComponents(bundle, selection);
-    written = writeBundleFiles({
-      outDir: join5(cwd, opts.outDir),
+    const writeResult = writeBundleFiles({
+      outDir: join7(cwd, opts.outDir),
       cwd,
       raw: result.raw,
       bundle,
@@ -2673,8 +4037,12 @@ async function runPull(cwd, flags, env, io2, fetcher) {
       libraryId: opts.libraryId,
       publishedAt: result.publishedAt,
       bundleHash: result.bundleHash,
-      dtcg: opts.dtcg
+      dtcg: opts.dtcg,
+      platforms,
+      outputs
     });
+    written = writeResult.written;
+    outputPaths = writeResult.outputs;
     io2.out(
       `Pulled ${bundle.fileName ?? opts.libraryId}: ${describePull(bundle, selection, selected)} (published ${result.publishedAt}).`
     );
@@ -2683,13 +4051,22 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     return 1;
   }
   io2.out(`Wrote ${written.length} files under ${opts.outDir}/.`);
+  for (const path of outputPaths) {
+    const o = outputs.find((x) => x.path === path);
+    if (o) io2.out(`Wrote ${path} (${o.platform}/${o.format}, ${o.case} names).`);
+  }
+  if (outputPaths.length === 0 && selection.foundation && source === "none" && opts.outputs === void 0) io2.out(NO_PLATFORM_NOTE);
+  if (source === "flag" || source === "config") {
+    const missing = platformsMissingFormat(platforms);
+    if (missing.length > 0) io2.out(missingFormatNote(missing));
+  }
   return 0;
 }
 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;
@@ -2721,11 +4098,15 @@ function runList(cwd, flags, io2) {
     return 1;
   }
   io2.out(`Library ${manifest.libraryId}, published ${manifest.publishedAt}.`);
-  const rows = manifest.artifacts.map((a) => [a.kind, a.name, a.aiPath ?? "not written", a.contentHash]);
+  const rows = manifest.artifacts.map((a) => [a.kind, a.name, a.path ?? "not written", a.contentHash]);
   const widths = [0, 1, 2].map((i) => Math.max(...rows.map((r) => r[i].length)));
   for (const row of rows) {
     io2.out(row.map((cell, i) => i < 3 ? cell.padEnd(widths[i]) : cell).join("  "));
   }
+  for (const o of manifest.outputs ?? []) {
+    const written = existsSync8(join7(outDir, "outputs", `${o.platform}-${o.format}.map.json`));
+    io2.out(["output".padEnd(widths[0]), `${o.platform}/${o.format}`.padEnd(widths[1]), written ? o.path : "not written"].join("  "));
+  }
   return 0;
 }
 var SHOW_USAGE = 'spec-layer show takes "foundation" or "component NAME".';
@@ -2775,20 +4156,99 @@ 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);
+  const fromFlags = platformsFromFlags(flags, io2);
+  if (fromFlags === null) return null;
+  const { platforms, source: platformSource } = resolvePlatforms(cwd, fromFlags, config);
+  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>
 
 Commands:
-  setup   --id lib_... --key sl_... [--out DIR] [selection]
+  setup   --id lib_... --key sl_... [--out DIR] [selection] [--platform P]...
                                                  store the key, then pull
-  init    --id lib_... [--out DIR] [selection]   write speclayer.json
-  pull    [--id lib_...] [--key sl_...] [selection]
+  init    --id lib_... [--out DIR] [selection] [--platform P]...
+                                                 write speclayer.json
+  pull    [--id lib_...] [--key sl_...] [selection] [--platform P]...
                                                  fetch the library into DIR (default .speclayer); the foundation lands as DTCG under DIR/tokens/
   status  [--id lib_...] [--key sl_...]          check freshness; exits 2 when behind
   list                                           list every artifact in the last pull
   show    foundation | component NAME [--canonical]
                                                  print one artifact (foundation: the DTCG document; component: its AI YAML; --canonical for JSON)
+  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
@@ -2796,6 +4256,7 @@ Selection (setup, pull and init; flags replace the include block in speclayer.js
 
 Options:
   --api URL   override the API origin (default https://api.spec-layer.com)
+  --platform web|ios|android|flutter   the target this repo builds for (repeatable); applies to setup, init, pull, and skill; setup and init store it, pull uses it for the run
 The pull key comes from --key, SPEC_LAYER_KEY, or speclayer.local.json written by setup.`;
 var io = {
   out: (l) => console.log(l),
@@ -2817,7 +4278,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", multiple: true }
       }
     }));
   } catch {
@@ -2833,6 +4298,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) {