spec-layer 0.6.0 → 0.8.2

package/dist/cli.js

@@ -560,7 +560,7 @@ import { parseArgs } from "node:util";
 
 // src/commands.ts
 import { existsSync as existsSync8 } from "node:fs";
-import { join as join7, resolve as resolve4 } from "node:path";
+import { join as join8, resolve as resolve5 } from "node:path";
 
 // ../extractor/src/statesMatrix.ts
 var STATE_ORDER = [
@@ -816,6 +816,15 @@ var SUPPORTED_DURATION_UNITS = ["ms", "s"];
 
 // ../extractor/src/v5/canonical.ts
 var import_js_sha2562 = __toESM(require_sha256(), 1);
+var SCHEMA_VERSION = "5.1.0";
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => compareCodeUnits(a, b)).map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`);
+    return `{${entries.join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
 
 // ../extractor/src/v5/validate.ts
 var ROOT = "<artifact>";
@@ -1317,6 +1326,7 @@ function validateLevel1(artifact) {
 }
 
 // ../extractor/src/v5/dtcg.ts
+var import_js_sha2563 = __toESM(require_sha256(), 1);
 function dtcgSegments(name) {
   const segments = [];
   const notes = [];
@@ -1334,7 +1344,15 @@ function dtcgSegments(name) {
   }
   return { segments, notes };
 }
-var slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "unnamed";
+function trimDashes(s) {
+  let start = 0;
+  let end = s.length;
+  while (start < end && s[start] === "-") start += 1;
+  while (end > start && s[end - 1] === "-") end -= 1;
+  return s.slice(start, end);
+}
+var dtcgSlug = (s) => trimDashes(s.toLowerCase().replace(/[^a-z0-9]+/g, "-")) || "unnamed";
+var slug = dtcgSlug;
 var RESERVED_FILE_NAMES = [
   "styles.typography.json",
   "styles.effects.json",
@@ -1427,6 +1445,15 @@ function sortTree(value) {
   const keys = Object.keys(value).sort((a, b) => rank(a) - rank(b) || compareCodeUnits(a, b));
   return Object.fromEntries(keys.map((k) => [k, sortTree(value[k])]));
 }
+function recordFact(p, tokenId, mode, transform, resolved2) {
+  let facts = p.factsById.get(tokenId);
+  if (!facts) {
+    facts = { transform: {}, resolved: {} };
+    p.factsById.set(tokenId, facts);
+  }
+  facts.transform[mode] = transform;
+  if (resolved2 !== void 0) facts.resolved[mode] = resolved2;
+}
 function reportOnce(p, entry2) {
   const key = JSON.stringify([entry2.code, entry2.path, entry2.mode ?? null, entry2.details]);
   if (p.reportKeys.has(key)) return;
@@ -1492,15 +1519,47 @@ function projectedLiteral(p, token, resolved2, onOverrideConflict) {
   const collection = p.collectionById.get(token.collection_id);
   const override = collection ? unitOverrideFor(p, token, collection) : void 0;
   let literal = resolved2;
+  let overrode = false;
   if (override !== void 0 && literal.type === "number") {
     if (token.scopes.some((s) => STATED_NUMBER_SCOPES.includes(s))) onOverrideConflict?.(override);
-    else literal = { type: "dimension", number: literal.value, unit: override };
+    else {
+      literal = { type: "dimension", number: literal.value, unit: override };
+      overrode = true;
+    }
+  }
+  const converted2 = dtcgLiteral(literal, token.scopes, p.options.values);
+  if ("omit" in converted2) return { converted: converted2, transform: null };
+  return {
+    converted: converted2,
+    transform: overrode ? "number-unit-override" : literalTransform(literal, token.scopes)
+  };
+}
+function literalTransform(value, scopes) {
+  switch (value.type) {
+    case "color":
+      return "color";
+    case "dimension":
+      return "dimension";
+    case "duration":
+      return "duration";
+    case "number":
+      return scopes.includes("FONT_WEIGHT") ? "font-weight" : "number";
+    case "cubic_bezier":
+      return "cubic-bezier";
+    case "font_family":
+      return "font-family";
+    case "string":
+    case "boolean":
+      return null;
+    default: {
+      const exhaustive = value;
+      return exhaustive;
+    }
   }
-  return dtcgLiteral(literal, token.scopes, p.options.values);
 }
 function aliasLeafType(p, token, chain, resolved2) {
   const terminal = chain.length > 0 ? p.tokenById.get(chain[chain.length - 1].token_id) : void 0;
-  return projectedLiteral(p, terminal ?? token, resolved2);
+  return projectedLiteral(p, terminal ?? token, resolved2).converted;
 }
 function modeLabels(collection) {
   const counts = /* @__PURE__ */ new Map();
@@ -1539,6 +1598,17 @@ function reportCollectionNameCollisions(p) {
 function asJson(value) {
   return JSON.parse(JSON.stringify(value));
 }
+function transformField(p, token) {
+  const facts = p.factsById.get(token.id);
+  if (!facts) return {};
+  const sorted = (source) => {
+    const keys = Object.keys(source).sort(compareCodeUnits);
+    return keys.length === 0 ? void 0 : Object.fromEntries(keys.map((k) => [k, source[k]]));
+  };
+  const transform = sorted(facts.transform);
+  const resolved2 = sorted(facts.resolved);
+  return { ...transform ? { transform } : {}, ...resolved2 ? { resolved: resolved2 } : {} };
+}
 function metaEntry(p, token, collection) {
   const labels = p.modeLabelsById.get(collection.id) ?? modeLabels(collection);
   const omitted = p.omittedIds.has(token.id);
@@ -1551,6 +1621,7 @@ function metaEntry(p, token, collection) {
     collection_id: token.collection_id,
     type: token.type,
     scopes: [...token.scopes],
+    ...omitted ? {} : transformField(p, token),
     ...token.code_syntax ? { code_syntax: token.code_syntax } : {},
     ...token.publication ? { publication: token.publication } : {},
     ...omitted ? {
@@ -1849,6 +1920,64 @@ function annotateGroups(p, tree, collection) {
     }
   }
 }
+var newAccumulator = () => ({
+  tokens: 0,
+  types: /* @__PURE__ */ new Map(),
+  present: 0,
+  missing: 0,
+  aliases: 0,
+  literals: 0,
+  scopes: /* @__PURE__ */ new Map(),
+  codeSyntaxPresent: 0,
+  codeSyntaxMissing: 0,
+  published: 0,
+  hiddenFromPublishing: 0,
+  unstated: 0,
+  omitted: 0,
+  collided: 0
+});
+var bump = (counts, key) => {
+  counts.set(key, (counts.get(key) ?? 0) + 1);
+};
+var histogram = (counts) => Object.fromEntries([...counts.keys()].sort(compareCodeUnits).map((k) => [k, counts.get(k)]));
+function censusEntry(a) {
+  return {
+    tokens: a.tokens,
+    types: histogram(a.types),
+    descriptions: { present: a.present, missing: a.missing },
+    aliases: a.aliases,
+    literals: a.literals,
+    scopes: histogram(a.scopes),
+    code_syntax: { present: a.codeSyntaxPresent, missing: a.codeSyntaxMissing },
+    publication: {
+      published: a.published,
+      hidden_from_publishing: a.hiddenFromPublishing,
+      unstated: a.unstated
+    },
+    ...a.omitted > 0 ? { omitted: a.omitted } : {},
+    ...a.collided > 0 ? { collided: a.collided } : {}
+  };
+}
+function styleCensus(tree) {
+  const a = newAccumulator();
+  const walk = (node) => {
+    if (typeof node !== "object" || node === null || Array.isArray(node)) return;
+    const record = node;
+    if ("$value" in record) {
+      a.tokens += 1;
+      bump(a.types, typeof record.$type === "string" ? record.$type : "unknown");
+      if (typeof record.$description === "string" && record.$description.length > 0) a.present += 1;
+      else a.missing += 1;
+      return;
+    }
+    for (const [key, value] of Object.entries(record)) {
+      if (key.startsWith("$")) continue;
+      walk(value);
+    }
+  };
+  walk(tree);
+  return { tokens: a.tokens, types: histogram(a.types), descriptions: { present: a.present, missing: a.missing } };
+}
 function foundationDtcg(artifact, options = {}) {
   const p = {
     artifact,
@@ -1863,7 +1992,8 @@ function foundationDtcg(artifact, options = {}) {
     omittedIds: /* @__PURE__ */ new Set(),
     collidedIds: /* @__PURE__ */ new Set(),
     report: [],
-    reportKeys: /* @__PURE__ */ new Set()
+    reportKeys: /* @__PURE__ */ new Set(),
+    factsById: /* @__PURE__ */ new Map()
   };
   indexPaths(p);
   omitInexpressibleTypes(p);
@@ -1871,23 +2001,46 @@ function foundationDtcg(artifact, options = {}) {
   reportCollectionNameCollisions(p);
   const files = {};
   const plans = [];
+  const census = {};
   const taken = new Set(RESERVED_FILE_NAMES);
   for (const collection of artifact.collections) {
     for (const mode of collection.modes) {
       const tree = {};
+      const a = newAccumulator();
       for (const token of artifact.tokens) {
-        if (token.collection_id !== collection.id || p.omittedIds.has(token.id)) continue;
+        if (token.collection_id !== collection.id) continue;
+        if (p.omittedIds.has(token.id)) {
+          a.omitted += 1;
+          if (p.collidedIds.has(token.id)) a.collided += 1;
+          continue;
+        }
         const leaf = tokenLeaf(p, token, collection, mode.id);
-        if (leaf) setLeaf(tree, p.segmentsById.get(token.id) ?? [], leaf);
+        if (!leaf) continue;
+        setLeaf(tree, p.segmentsById.get(token.id) ?? [], leaf);
+        a.tokens += 1;
+        bump(a.types, typeof leaf.$type === "string" ? leaf.$type : "unknown");
+        const modeLabel = modeLabelOf(p, collection, mode.id);
+        if (p.factsById.get(token.id)?.transform[modeLabel] === "alias") a.aliases += 1;
+        else a.literals += 1;
+        if (token.description.length > 0) a.present += 1;
+        else a.missing += 1;
+        for (const scope of token.scopes) bump(a.scopes, scope);
+        if (token.code_syntax) a.codeSyntaxPresent += 1;
+        else a.codeSyntaxMissing += 1;
+        if (token.publication?.published) a.published += 1;
+        if (token.publication?.hidden_from_publishing) a.hiddenFromPublishing += 1;
+        if (!token.publication) a.unstated += 1;
       }
       annotateGroups(p, tree, collection);
       const file = fileNameFor(collection, mode, taken);
       plans.push({ collection, modeId: mode.id, file });
       files[file] = sortTree(tree);
+      census[file] = censusEntry(a);
     }
   }
   const styles = styleFiles(p);
   Object.assign(files, styles);
+  for (const [file, tree] of Object.entries(styles)) census[file] = styleCensus(tree);
   const resolver = buildResolver(p, plans, Object.keys(styles).sort(compareCodeUnits));
   p.report.sort((a, b) => compareCodeUnits(a.path, b.path) || compareCodeUnits(a.code, b.code) || compareCodeUnits(a.mode ?? "", b.mode ?? ""));
   const meta = {};
@@ -1898,7 +2051,25 @@ function foundationDtcg(artifact, options = {}) {
     meta[p.collidedIds.has(token.id) ? `${path} [${token.id}]` : path] = metaEntry(p, token, collection);
   }
   const sortedMeta = Object.fromEntries(Object.entries(meta).sort(([a], [b]) => compareCodeUnits(a, b)));
-  return { files, resolver, meta: sortedMeta, report: p.report };
+  const codeSyntax = {};
+  for (const [path, entry2] of Object.entries(sortedMeta)) {
+    if (entry2.code_syntax) codeSyntax[path] = entry2.code_syntax;
+  }
+  const sourceFileName = artifact.spec_layer.source.file_name;
+  const extension = {
+    schema_version: SCHEMA_VERSION,
+    content_hash: artifact.spec_layer.export.content_hash,
+    config_hash: `sha256:${(0, import_js_sha2563.sha256)(canonicalJson(p.options))}`,
+    source: {
+      provider: "figma",
+      ...typeof sourceFileName === "string" && sourceFileName.length > 0 ? { file_name: sourceFileName } : {}
+    },
+    completeness: artifact.completeness,
+    code_syntax: codeSyntax,
+    census: Object.fromEntries(Object.keys(census).sort(compareCodeUnits).map((k) => [k, census[k]])),
+    report: p.report
+  };
+  return { files, resolver, meta: sortedMeta, report: p.report, extension };
 }
 function omitInexpressibleTypes(p) {
   for (const token of p.artifact.tokens) {
@@ -1999,9 +2170,10 @@ function tokenLeaf(p, token, collection, modeId) {
       });
       return null;
     }
+    recordFact(p, token.id, mode, "alias", typed.$value);
     return { $type: typed.$type, $value: `{${targetPath}}`, ...description };
   }
-  const converted2 = projectedLiteral(p, token, value.value, (override) => {
+  const projected = projectedLiteral(p, token, value.value, (override) => {
     reportOnce(p, {
       code: "unit_override_conflicts_with_scope",
       severity: "warning",
@@ -2010,6 +2182,7 @@ function tokenLeaf(p, token, collection, modeId) {
       details: { id: token.id, override, scopes: [...token.scopes] }
     });
   });
+  const converted2 = projected.converted;
   if ("omit" in converted2) {
     reportOnce(p, {
       code: converted2.omit,
@@ -2021,6 +2194,7 @@ function tokenLeaf(p, token, collection, modeId) {
     });
     return null;
   }
+  if (projected.transform !== null) recordFact(p, token.id, mode, projected.transform);
   return { $type: converted2.$type, $value: converted2.$value, ...description };
 }
 function dtcgExportFiles(out) {
@@ -2028,7 +2202,10 @@ function dtcgExportFiles(out) {
 `;
   const files = {};
   for (const name of Object.keys(out.files).sort(compareCodeUnits)) files[name] = text(out.files[name]);
-  files["resolver.json"] = text(out.resolver);
+  files["resolver.json"] = text({
+    ...out.resolver,
+    $extensions: { "com.spec-layer": out.extension }
+  });
   files["spec-layer.meta.json"] = text(out.meta);
   files["report.json"] = text(out.report);
   return files;
@@ -2121,6 +2298,7 @@ function resolveNames(paths, meta, rules) {
 }
 
 // ../extractor/src/v5/outputs/css.ts
+var CSS_INDEX_FILE = "index.css";
 var CSS_DEFAULTS = {
   case: "kebab",
   root: ":root",
@@ -2186,6 +2364,23 @@ function sourcesOf(resolver) {
 }
 var modeSlug = (file) => file.replace(/\.json$/, "").split(".").slice(1).join(".");
 var collectionSlug = (file) => file.split(".")[0];
+function cssFileNames(sources) {
+  const taken = /* @__PURE__ */ new Set([CSS_INDEX_FILE]);
+  const out = /* @__PURE__ */ new Map();
+  for (const s of sources) {
+    if (out.has(s.file)) continue;
+    const base = s.mode === null ? dtcgSlug(s.collection) : `${dtcgSlug(s.collection)}.${modeSlug(s.file)}`;
+    let candidate = `${base}.css`;
+    let n = 1;
+    while (taken.has(candidate)) {
+      n += 1;
+      candidate = `${base}-${n}.css`;
+    }
+    taken.add(candidate);
+    out.set(s.file, candidate);
+  }
+  return out;
+}
 var REF = /^\{(.+)\}$/;
 function hexChannels(hex) {
   const at = (i) => parseInt(hex.slice(i, i + 2), 16);
@@ -2394,17 +2589,22 @@ function headerText(header, nameCase) {
 function emitPass(sources, leavesByFile, names, alive, root, template, modes) {
   const entries = [];
   const declared = /* @__PURE__ */ new Set();
+  const firstFile = /* @__PURE__ */ new Map();
   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 = [];
+    const declaredHere = [];
     for (const leaf of leavesByFile.get(s.file) ?? []) {
       const ctx = { names, alive, report: entries, path: leaf.path, ...s.mode !== null ? { mode: s.mode } : {} };
       if (leaf.type === "typography") {
         const t = typographyDecls(ctx, leaf, names);
         decls.push(...t.decls);
-        for (const p of t.declaredPaths) declared.add(p);
+        for (const p of t.declaredPaths) {
+          declared.add(p);
+          declaredHere.push(p);
+        }
       } else {
         const name = names.get(leaf.path);
         if (name === void 0) continue;
@@ -2413,22 +2613,26 @@ function emitPass(sources, leavesByFile, names, alive, root, template, modes) {
           if (d !== null) {
             decls.push(d);
             declared.add(leaf.path);
+            declaredHere.push(leaf.path);
           }
         } else {
           const v = cssValue(ctx, leaf.type, leaf.value);
           if (v !== null) {
             decls.push(`${name}: ${v};`);
             declared.add(leaf.path);
+            declaredHere.push(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);
+    for (const p of declaredHere) if (!firstFile.has(p)) firstFile.set(p, s.file);
+    const comment = `/* ${commentSafe(`${s.collection}${s.mode !== null ? `, ${s.mode}` : ""}`)} */`;
+    const existing = blocks.get(s.file);
+    if (existing) existing.decls.push(...decls);
+    else blocks.set(s.file, { selector, comment, decls });
   }
-  return { blocks, entries, declared };
+  return { blocks, entries, declared, firstFile };
 }
 function cssOutput(exp, header, options = {}) {
   const nameCase = options.case ?? CSS_DEFAULTS.case;
@@ -2458,7 +2662,7 @@ function cssOutput(exp, header, options = {}) {
   const resolved2 = resolveNames([...candidatePaths], exp.meta, {
     codeSyntaxKey: "WEB",
     acceptDeclared: acceptCssDeclared,
-    affix: (body2) => `--${body2}`,
+    affix: (body) => `--${body}`,
     nameCase
   });
   const names = resolved2.names;
@@ -2470,9 +2674,11 @@ function cssOutput(exp, header, options = {}) {
     alive = pass.declared;
     pass = emit(alive);
   }
+  const fileNames = cssFileNames(sources);
   const map = {};
   for (const [path, entry2] of Object.entries(resolved2.map)) {
-    if (alive.has(path)) map[path] = entry2;
+    const from = pass.firstFile.get(path);
+    if (alive.has(path) && from !== void 0) map[path] = { ...entry2, file: fileNames.get(from) };
   }
   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);
@@ -2487,14 +2693,29 @@ function cssOutput(exp, header, options = {}) {
       });
     }
   }
-  const body = [...pass.blocks].flatMap(([selector, lines]) => [`${selector} {`, ...lines, "}", ""]);
-  const text = `${[headerText(header, nameCase), "", ...body].join("\n").trimEnd()}
+  const head = headerText(header, nameCase);
+  const files = {};
+  const imports = [];
+  for (const [source, block] of pass.blocks) {
+    const name = fileNames.get(source);
+    files[name] = `${head}
+
+${block.selector} {
+  ${block.comment}
+${block.decls.map((d) => `  ${d}`).join("\n")}
+}
 `;
-  return { text, map, report: sortReport(entries) };
+    imports.push(block.comment, `@import "./${name}";`);
+  }
+  if (imports.length > 0) files[CSS_INDEX_FILE] = `${head}
+
+${imports.join("\n")}
+`;
+  return { files, map, report: sortReport(entries) };
 }
 
 // ../extractor/src/v5/componentContext.ts
-var import_js_sha2563 = __toESM(require_sha256(), 1);
+var import_js_sha2564 = __toESM(require_sha256(), 1);
 
 // ../extractor/src/libraryBundle.ts
 var LIBRARY_BUNDLE_SCHEMA = "spec-layer-library-bundle";
@@ -2562,7 +2783,7 @@ function parseLibraryBundle(input) {
 }
 
 // ../extractor/src/libraryBundleHash.ts
-var import_js_sha2564 = __toESM(require_sha256(), 1);
+var import_js_sha2565 = __toESM(require_sha256(), 1);
 
 // src/bundle.ts
 function parseBundle(raw) {
@@ -2585,7 +2806,7 @@ function parseBundle(raw) {
 
 // src/config.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync3, existsSync as existsSync4 } from "node:fs";
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 
 // src/credentials.ts
 import { readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
@@ -2768,17 +2989,93 @@ function isAgentHost(value) {
 }
 
 // src/outputs.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { resolve as resolve2 } from "node:path";
+
+// src/visibleDir.ts
 import {
+  closeSync,
   existsSync as existsSync3,
+  lstatSync,
   mkdirSync,
-  readFileSync as readFileSync3,
+  openSync,
+  readSync,
+  readdirSync as readdirSync2,
   renameSync,
   rmSync,
   writeFileSync as writeFileSync2
 } from "node:fs";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { isAbsolute, join as join3, relative, resolve } from "node:path";
+var inside = (parent, child) => {
+  const rel = relative(parent, child);
+  return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+};
+var isDotfile = (name) => name.startsWith(".");
+function carriesMarker(abs, marker) {
+  const newlines = (marker.match(/\n/g) ?? []).length;
+  const wantBytes = Buffer.byteLength(marker, "utf8") + newlines;
+  const fd = openSync(abs, "r");
+  try {
+    const buf = Buffer.alloc(wantBytes);
+    const read = readSync(fd, buf, 0, wantBytes, 0);
+    const text = buf.subarray(0, read).toString("utf8").replace(/\r\n/g, "\n");
+    return text.startsWith(marker);
+  } finally {
+    closeSync(fd);
+  }
+}
+function visibleDirProblem(cwd, outDir, dir, marker, others, configKey) {
+  const root = resolve(cwd);
+  const abs = resolve(cwd, dir);
+  if (!inside(root, abs) || abs === root) return `${dir} is outside this directory. Choose a path inside the repository.`;
+  if (inside(resolve(cwd, outDir), abs)) return `${dir} is inside ${outDir}, which pull replaces wholesale. Choose a path outside it.`;
+  for (const other of others) {
+    const otherAbs = resolve(cwd, other);
+    if (inside(abs, otherAbs) || inside(otherAbs, abs)) return `${dir} and ${other} overlap. Give each output its own directory.`;
+  }
+  if (!existsSync3(abs)) return null;
+  if (!lstatSync(abs).isDirectory()) return `${dir} exists and is not a directory. Choose another path or remove the file.`;
+  const foreign = `${dir} holds files spec-layer did not write. Set ${configKey} in speclayer.json to another path, or move them.`;
+  for (const entry2 of readdirSync2(abs, { withFileTypes: true })) {
+    if (isDotfile(entry2.name)) continue;
+    if (!entry2.isFile()) return foreign;
+    try {
+      if (!carriesMarker(join3(abs, entry2.name), marker)) return foreign;
+    } catch {
+      return `${dir}/${entry2.name} could not be read.`;
+    }
+  }
+  return null;
+}
+function writeAtomically(abs, text) {
+  const partial = `${abs}.partial`;
+  writeFileSync2(partial, text);
+  try {
+    renameSync(partial, abs);
+  } catch (err) {
+    rmSync(partial, { force: true });
+    throw err;
+  }
+}
+function writeVisibleDir(cwd, dir, marker, files, last) {
+  const abs = resolve(cwd, dir);
+  const names = Object.keys(files).filter((n) => n !== last);
+  if (last !== void 0 && last in files) names.push(last);
+  if (names.length === 0 && !existsSync3(abs)) return [];
+  mkdirSync(abs, { recursive: true });
+  for (const name of names) writeAtomically(join3(abs, name), files[name]);
+  const keep = new Set(names);
+  for (const entry2 of readdirSync2(abs, { withFileTypes: true })) {
+    if (isDotfile(entry2.name) || keep.has(entry2.name) || !entry2.isFile()) continue;
+    const path = join3(abs, entry2.name);
+    if (carriesMarker(path, marker)) rmSync(path);
+  }
+  return names;
+}
+
+// src/outputs.ts
 var FORMATS = [
-  { platform: "web", format: "css", defaultPath: "spec-layer/tokens.css", defaultCase: "kebab", headerPrefix: CSS_HEADER_PREFIX }
+  { platform: "web", format: "css", defaultPath: "tokens", 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;
@@ -2844,45 +3141,27 @@ function renderOutput(exp, o, header) {
     }
   }
 }
-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);
+function readIndexImports(cwd, o) {
+  const path = resolve2(cwd, o.path, CSS_INDEX_FILE);
+  let text;
   try {
-    renameSync(partial, abs);
-  } catch (err) {
-    rmSync(partial, { force: true });
-    throw err;
+    text = readFileSync3(path, "utf8");
+  } catch {
+    return null;
   }
+  return [...text.matchAll(/^@import "\.\/([^"\n]+)";$/gm)].map((m) => m[1]);
+}
+var LEGACY_CSS_PATH_NOTE = (path) => `${path} names a file; spec-layer 0.7.0 writes a directory. Set outputs[].path to a directory, for example "tokens", delete the old file, and pull again.`;
+function outputPathProblem(cwd, outDir, o, others = []) {
+  if (/\.css$/i.test(o.path)) return LEGACY_CSS_PATH_NOTE(o.path);
+  const marker = specOf(o.platform, o.format)?.headerPrefix ?? CSS_HEADER_PREFIX;
+  return visibleDirProblem(cwd, outDir, o.path, marker, others, "outputs[].path");
 }
 
 // src/config.ts
 var DEFAULT_API = "https://api.spec-layer.com";
 var DEFAULT_OUT_DIR = ".speclayer";
+var DEFAULT_COMPONENT_SPECS_DIR = "component-specs";
 var CONFIG_NAME = "speclayer.json";
 var invalidConfig = () => new Error(`${CONFIG_NAME} is not valid JSON. Fix or delete it, then retry.`);
 function parseInclude(value) {
@@ -2914,6 +3193,14 @@ function parseDtcg(value) {
   }
   return out;
 }
+function parseComponentSpecsDir(value) {
+  if (typeof value !== "string" || value.length === 0) throw new Error('speclayer.json "componentSpecsDir" must be a non-empty string.');
+  let dir = value.replace(/\\/g, "/");
+  if (dir.startsWith("./")) dir = dir.slice(2);
+  dir = dir.replace(/\/+$/, "");
+  if (dir.length === 0) throw new Error('speclayer.json "componentSpecsDir" must be a non-empty string.');
+  return dir;
+}
 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(", ")}.`);
@@ -2934,7 +3221,7 @@ function parseOutputs(value) {
   return outputs;
 }
 function readConfig(cwd) {
-  const path = join3(cwd, CONFIG_NAME);
+  const path = join4(cwd, CONFIG_NAME);
   if (!existsSync4(path)) return null;
   let parsed;
   try {
@@ -2947,6 +3234,7 @@ function readConfig(cwd) {
   return {
     ...typeof record.libraryId === "string" ? { libraryId: record.libraryId } : {},
     ...typeof record.outDir === "string" ? { outDir: record.outDir } : {},
+    ...record.componentSpecsDir !== void 0 ? { componentSpecsDir: parseComponentSpecsDir(record.componentSpecsDir) } : {},
     ...record.include !== void 0 ? { include: parseInclude(record.include) } : {},
     ...record.dtcg !== void 0 ? { dtcg: parseDtcg(record.dtcg) } : {},
     ...record.platforms !== void 0 ? { platforms: parsePlatforms(record.platforms) } : {},
@@ -2957,18 +3245,19 @@ function writeConfig(cwd, config) {
   const body = {
     libraryId: config.libraryId,
     outDir: config.outDir,
+    ...config.componentSpecsDir ? { componentSpecsDir: config.componentSpecsDir } : {},
     ...config.include ? { include: config.include } : {},
     ...config.dtcg ? { dtcg: config.dtcg } : {},
     ...config.platforms && config.platforms.length > 0 ? { platforms: config.platforms } : {},
     ...config.outputs ? { outputs: config.outputs } : {}
   };
-  writeFileSync3(join3(cwd, CONFIG_NAME), `${JSON.stringify(body, null, 2)}
+  writeFileSync3(join4(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(join3(cwd, outDir));
+  const libraryId = flags.id ?? config?.libraryId ?? manifestLibraryId(join4(cwd, outDir));
   const supplied = flags.key || env.SPEC_LAYER_KEY || null;
   let storedKey = null;
   let storedKeyFor;
@@ -2982,6 +3271,7 @@ function resolveOptions(cwd, flags, env, manifestLibraryId) {
   return {
     libraryId,
     outDir,
+    componentSpecsDir: config?.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR,
     // A trailing slash would build "//v1/..." paths the proxy router 404s on.
     api: (flags.api ?? env.SPEC_LAYER_API ?? DEFAULT_API).replace(/\/+$/, ""),
     key: supplied ?? storedKey,
@@ -3027,8 +3317,8 @@ async function fetchBundle(opts) {
 }
 
 // src/files.ts
-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";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync4, readFileSync as readFileSync5, readdirSync as readdirSync3, rmSync as rmSync2, renameSync as renameSync2, existsSync as existsSync5 } from "node:fs";
+import { join as join5, dirname, relative as relative2, resolve as resolve3, isAbsolute as isAbsolute2, sep } from "node:path";
 
 // src/selection.ts
 var DEFAULT_SELECTION = { foundation: true, components: null };
@@ -3066,8 +3356,9 @@ function slugify(name) {
   const slug2 = name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return slug2 || "component";
 }
+var COMPONENT_SPEC_MARKER = "spec_layer:\n  kind: component";
 function readManifest(outDir) {
-  const path = join4(outDir, "manifest.json");
+  const path = join5(outDir, "manifest.json");
   if (!existsSync5(path)) return null;
   try {
     const parsed = JSON.parse(readFileSync5(path, "utf8"));
@@ -3084,7 +3375,7 @@ function readManifest(outDir) {
   }
 }
 function readLocalBundle(outDir) {
-  const path = join4(outDir, "bundle.json");
+  const path = join5(outDir, "bundle.json");
   if (!existsSync5(path)) return null;
   try {
     return parseBundle(readFileSync5(path, "utf8"));
@@ -3114,11 +3405,11 @@ function componentSlugs(bundle) {
   });
 }
 function assertReplaceable(outDir, cwd) {
-  const rel = relative2(resolve2(cwd), resolve2(outDir));
+  const rel = relative2(resolve3(cwd), resolve3(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 (existsSync5(outDir) && !existsSync5(join4(outDir, "manifest.json")) && readdirSync2(outDir).length > 0) {
+  if (existsSync5(outDir) && !existsSync5(join5(outDir, "manifest.json")) && readdirSync3(outDir).length > 0) {
     throw new Error(`${outDir} exists and was not written by spec-layer pull. Choose an empty or new directory.`);
   }
 }
@@ -3128,13 +3419,23 @@ function writeBundleFiles(opts) {
   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 componentSpecsDir = opts.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR;
+  const outDirRel = relative2(resolve3(opts.cwd), resolve3(opts.outDir)).split(sep).join("/");
+  const outputPaths = outputs.map((o) => o.path);
+  const specsProblem = visibleDirProblem(opts.cwd, outDirRel, componentSpecsDir, COMPONENT_SPEC_MARKER, outputPaths, "componentSpecsDir");
+  if (specsProblem) throw new Error(specsProblem);
+  for (const o of outputs) {
+    const problem = outputPathProblem(opts.cwd, outDirRel, o, [componentSpecsDir, ...outputPaths.filter((p) => p !== o.path)]);
+    if (problem) throw new Error(problem);
+  }
+  const briefs = {};
+  opts.bundle.components.forEach((component, i) => {
+    if (!selected[i]) return;
+    if (!component.ai.startsWith(COMPONENT_SPEC_MARKER)) {
+      throw new Error(`The published brief for ${component.name} does not begin with the Spec Layer marker. Republish from the plugin, then pull again.`);
     }
-  }
+    briefs[`${slugs[i]}.yaml`] = component.ai;
+  });
   const staging = `${opts.outDir}.partial`;
   rmSync2(staging, { recursive: true, force: true });
   const written = [];
@@ -3142,8 +3443,8 @@ function writeBundleFiles(opts) {
   const json = (v) => `${JSON.stringify(v, null, 2)}
 `;
   const put = (rel, content) => {
-    const path = join4(staging, rel);
-    mkdirSync2(dirname2(path), { recursive: true });
+    const path = join5(staging, rel);
+    mkdirSync2(dirname(path), { recursive: true });
     writeFileSync4(path, content);
     written.push(rel);
   };
@@ -3159,13 +3460,13 @@ function writeBundleFiles(opts) {
         }
         const exp = foundationDtcg(artifact, opts.dtcg ?? {});
         for (const [name, text] of Object.entries(dtcgExportFiles(exp))) put(`tokens/${name}`, text);
-        path = "tokens/resolver.json";
+        path = `${outDirRel}/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 });
+          deliverables.push({ output, files: rendered.files });
         }
       }
       artifacts.push({
@@ -3176,13 +3477,11 @@ function writeBundleFiles(opts) {
       });
     }
     opts.bundle.components.forEach((component, i) => {
-      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,
-        path
+        path: selected[i] ? `${componentSpecsDir}/${slugs[i]}.yaml` : null
       });
     });
     const manifest = {
@@ -3192,6 +3491,7 @@ function writeBundleFiles(opts) {
       pluginVersion: opts.bundle.pluginVersion,
       extractorVersion: opts.bundle.extractorVersion,
       selection,
+      componentSpecsDir,
       artifacts,
       ...opts.dtcg && Object.keys(opts.dtcg).length > 0 ? { dtcg: opts.dtcg } : {},
       ...opts.platforms && opts.platforms.length > 0 ? { platforms: opts.platforms } : {},
@@ -3204,18 +3504,18 @@ function writeBundleFiles(opts) {
   }
   rmSync2(opts.outDir, { recursive: true, force: true });
   renameSync2(staging, opts.outDir);
-  const outputPaths = [];
+  const componentSpecs = { path: componentSpecsDir, files: writeVisibleDir(opts.cwd, componentSpecsDir, COMPONENT_SPEC_MARKER, briefs) };
+  const outputResults = [];
   for (const d of deliverables) {
-    writeOutputFile(opts.cwd, d.output, d.text);
-    outputPaths.push(d.output.path);
+    outputResults.push({ path: d.output.path, files: writeVisibleDir(opts.cwd, d.output.path, CSS_HEADER_PREFIX, d.files, CSS_INDEX_FILE) });
   }
-  return { written, outputs: outputPaths };
+  return { written, componentSpecs, outputs: outputResults };
 }
 
 // src/gitignore.ts
 import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync6 } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { join as join5, dirname as dirname3, resolve as resolve3 } from "node:path";
+import { join as join6, dirname as dirname2, resolve as resolve4 } 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" });
@@ -3223,10 +3523,10 @@ function git(cwd, args) {
   return { ranGit: true, status: res.status, stdout: res.stdout ?? "" };
 }
 function insideWorkTreeWithoutGit(cwd) {
-  let dir = resolve3(cwd);
+  let dir = resolve4(cwd);
   for (; ; ) {
-    if (existsSync6(join5(dir, ".git"))) return true;
-    const parent = dirname3(dir);
+    if (existsSync6(join6(dir, ".git"))) return true;
+    const parent = dirname2(dir);
     if (parent === dir) return false;
     dir = parent;
   }
@@ -3242,7 +3542,7 @@ 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 = join5(cwd, ".gitignore");
+  const path = join6(cwd, ".gitignore");
   const existed = existsSync6(path);
   try {
     if (!existed) {
@@ -3267,8 +3567,8 @@ ${fileName}
 }
 
 // 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";
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, readdirSync as readdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync6 } from "node:fs";
+import { dirname as dirname3, join as join7 } from "node:path";
 
 // src/tools.ts
 var OK_OR_ERROR = { "0": "success", "1": "usage error, bad key or id, or a network or server failure" };
@@ -3286,7 +3586,8 @@ var TOOLS = [
       "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"
+      "outputs[].path from speclayer.json (default tokens/ for web), a directory written in place",
+      "componentSpecsDir from speclayer.json (default component-specs/), written in place"
     ],
     exits: OK_OR_ERROR
   },
@@ -3303,11 +3604,15 @@ var TOOLS = [
   {
     name: "pull",
     usage: "spec-layer pull [--id lib_...] [--key sl_...] [--out DIR] [--platform web|ios|android|flutter]... [--only foundation|components] [--component NAME]...",
-    summary: "Fetches the published library and writes 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.",
+    summary: "Fetches the published library and writes the record under the output directory (default .speclayer/), the briefs under componentSpecsDir, and the token files under outputs[].path.",
+    when: "After setup, whenever status says the local copy is behind, or after changing the include, dtcg, outputs, or componentSpecsDir blocks.",
     network: true,
     needsKey: true,
-    writes: ["<outDir>/", "outputs[].path from speclayer.json (default spec-layer/tokens.css for web), written in place"],
+    writes: [
+      "<outDir>/",
+      "outputs[].path from speclayer.json (default tokens/ for web), a directory written in place",
+      "componentSpecsDir from speclayer.json (default component-specs/), written in place"
+    ],
     exits: OK_OR_ERROR
   },
   {
@@ -3416,24 +3721,24 @@ function readJson(path) {
 }
 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 absOut = join7(cwd, outDir);
+  const components = manifest.artifacts.filter((a) => a.kind === "component").map((a) => ({ name: a.name, path: a.path }));
   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"));
+    const tokensDir = join7(absOut, "tokens");
+    const resolver = readJson(join7(tokensDir, "resolver.json"));
+    const report2 = readJson(join7(tokensDir, "report.json"));
     let tokenFiles = [];
     try {
-      tokenFiles = readdirSync3(tokensDir).filter((f) => f.endsWith(".json") && !RESERVED.has(f)).sort();
+      tokenFiles = readdirSync4(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)));
+      unitlessNumbers += countNumberTokens(readJson(join7(tokensDir, file)));
     }
     const reportCounts = {};
     if (Array.isArray(report2)) {
@@ -3459,20 +3764,33 @@ function summarizePull(cwd, outDir, manifest) {
     libraryId: manifest.libraryId,
     publishedAt: manifest.publishedAt,
     pluginVersion: manifest.pluginVersion,
+    componentSpecsDir: manifest.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR,
     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`))
-    }))
+    outputs: (manifest.outputs ?? []).map((o) => {
+      const mapPath = join7(absOut, "outputs", `${o.platform}-${o.format}.map.json`);
+      const map = readJson(mapPath);
+      const imports = map ? readIndexImports(cwd, o) : null;
+      const files = imports !== null ? [...imports, CSS_INDEX_FILE] : [];
+      return {
+        platform: o.platform,
+        format: o.format,
+        path: o.path,
+        case: o.case,
+        modeSelector: o.modeSelector ?? '[data-theme="{mode}"]',
+        modes: o.modes ?? {},
+        // index.css must be readable, not just the map, or a deleted index.css
+        // (with the map still on disk from an interrupted pull) would report
+        // written with an empty file list, a sentence that claims files exist.
+        written: map !== null && imports !== null,
+        // Distinguishes "the map is on disk but index.css is gone" from "the
+        // map itself never existed" (the Foundation was excluded), so the
+        // guide can name the actual cause instead of always blaming the
+        // Foundation.
+        indexMissing: map !== null && imports === null,
+        files
+      };
+    })
   };
 }
 var code = (s) => `\`${s}\``;
@@ -3511,16 +3829,17 @@ function stackSection(input) {
       if (cssOut) {
         const mapPath = `${input.outDir}/outputs/web-css.map.json`;
         lines.push(
-          `The CSS custom property for every token is in ${code(mapPath)}: source "code_syntax" when the designer declared it in Figma, "derived" when the CLI built it from the DTCG path by the stated rule (${cssOut.case} case, collection root included). Use those names; never invent a third. ${code(`${tokensDir}spec-layer.meta.json`)} still holds the raw ${code("code_syntax.WEB")} the designer declared.`,
+          `The CSS custom property for every token is in ${code(mapPath)}: source "code_syntax" when the designer declared it in Figma, "derived" when the CLI built it from the DTCG path by the stated rule (${cssOut.case} case, collection root included). Each entry names the file that declares the property. Use those names; never invent a third. ${code(`${tokensDir}spec-layer.meta.json`)} still holds the raw ${code("code_syntax.WEB")} the designer declared.`,
           ""
         );
+        const partFiles = cssOut.files.filter((f) => f !== CSS_INDEX_FILE);
         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.`,
+          `Import ${code(`${cssOut.path}/index.css`)} from the root stylesheet. It imports one file per collection and mode: ${partFiles.join(", ")}. Sets and default modes are at ${code(":root")}; every other mode is a block under ${code(cssOut.modeSelector)} in its own file, so a mode can also be imported alone. To switch, set ${code("data-theme")} on ${code("<html>")} (or whatever the selector names). To let the OS choose, set that collection's selector to ${code(":root")} under ${code("outputs[].modes")} and import the mode's file yourself under ${code("@media (prefers-color-scheme: dark)")}; the CLI never assumes that.`,
           ""
         );
         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.`,
+            `${code(`${cssOut.path}/`)} is a projection of the same ${code(tokensDir)} files, not a second source. Import one or the other.`,
             ""
           );
         }
@@ -3530,14 +3849,19 @@ function stackSection(input) {
           ""
         );
         const configuredNotWritten = pull?.outputs.find((o) => o.platform === "web" && !o.written) ?? null;
-        if (configuredNotWritten) {
+        if (configuredNotWritten?.indexMissing) {
+          lines.push(
+            `A web/css output is configured at ${code(`${configuredNotWritten.path}/`)} but its ${code("index.css")} is missing, so the file list is unknown. Run ${code("npx spec-layer pull")} to write it again.`,
+            ""
+          );
+        } else if (configuredNotWritten) {
           lines.push(
-            `A web/css output is configured at ${code(configuredNotWritten.path)} but was not written, because the last pull did not write the Foundation. Pull with the Foundation selected to write it.`,
+            `A web/css output is configured at ${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")}.`,
+            `No token file was written for web. Add \`"outputs"\` in \`speclayer.json\` (or run \`spec-layer pull --platform web\` once) and pull again; the default lands at ${code("tokens/")}.`,
             ""
           );
         }
@@ -3619,9 +3943,9 @@ function pullSection(input) {
   } else {
     lines.push("- This library has no Foundation, so there is no tokens/ directory.");
   }
-  lines.push(`- ${code(`${outDir}/components/`)}: one YAML per component.`);
+  lines.push(`- ${code(`${pull.componentSpecsDir}/`)}: 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(o.written ? `- ${code(`${o.path}/`)}: ${o.platform}/${o.format} token files, ${o.case} names: ${o.files.join(", ")}. Non-default modes are under ${code(o.modeSelector)}, each in its own file. Names and provenance: ${code(`${outDir}/outputs/${o.platform}-${o.format}.map.json`)}; what it could not express: ${code(`${outDir}/outputs/${o.platform}-${o.format}.report.json`)}.` : o.indexMissing ? `- ${code(`${o.path}/`)}: ${o.platform}/${o.format} token files, but ${code("index.css")} is missing; run ${code("npx spec-layer pull")} to restore the directory.` : `- ${code(`${o.path}/`)}: ${o.platform}/${o.format} token files, configured but not written by the last pull (the Foundation was not written). Nothing is on disk at that path from Spec Layer.`);
   }
   lines.push("");
   if (pull.foundation && (pull.foundation.sets.length || pull.foundation.modifiers.length)) {
@@ -3676,20 +4000,21 @@ function buildSkillGuide(input) {
     `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.`,
     ""
   );
+  const componentSpecsDir = input.pull?.componentSpecsDir ?? input.config?.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR;
   lines.push("## How to use it", "");
   lines.push(`1. Run ${code("npx spec-layer status")}. Exit 0 means the local copy is current; exit 2 means run ${code("npx spec-layer pull")} first.`);
-  lines.push(`2. Building or changing a component: read its YAML under ${code(`${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(`2. Building or changing a component: read its YAML under ${code(`${componentSpecsDir}/`)}, or ${code("npx spec-layer show component NAME")}. ${code("api")} gives variants, states, booleans, and slots; ${code("anatomy")} names the parts; ${code("references.bindings")} says which token each part's property uses and under which ${code("when")} conditions; ${code("unbound")} lists values that are hardcoded in Figma.`);
   lines.push(`3. Working with colors, spacing, type, or effects: start at ${code(`${outDir}/tokens/resolver.json`)}, load the set and mode files it names, and look up ${code("code_syntax")} in ${code("spec-layer.meta.json")} for the name the designer declared for your platform.`);
   lines.push(`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.`);
+  const outputNote = writtenOutputs.length ? ` Never edit ${writtenOutputs.map((o) => code(`${o.path}/`)).join(", ")} either: pull replaces or removes files there.` : "";
+  lines.push(`6. Never edit files under ${code(outDir + "/")} or ${code(componentSpecsDir + "/")}: the next pull replaces or removes them.${outputNote} Configuration lives in ${code("speclayer.json")}. Never commit ${code(CREDENTIALS_NAME)}, and never print or copy the pull key.`);
   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.`);
+  lines.push(`Generated by ${code("spec-layer skill")}. Re-run ${code("npx spec-layer skill --install")} after a pull that adds components, after changing ${code("outputs")} or ${code("componentSpecsDir")}, or when the codebase changes stack; the file is replaced, not appended.`);
   return `${lines.join("\n")}
 `;
 }
@@ -3759,16 +4084,16 @@ ${BLOCK_END}
     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}`;
+  const sep2 = existing.length === 0 ? "" : existing.endsWith("\n\n") ? "" : existing.endsWith("\n") ? "\n" : "\n\n";
+  return `${existing}${sep2}${block}`;
 }
 function installSkill(cwd, host, guide) {
   const target = installTarget(host);
-  const abs = join6(cwd, target.path);
+  const abs = join7(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 });
+  mkdirSync3(dirname3(abs), { recursive: true });
   writeFileSync6(abs, next);
   return { path: target.path, result: existing === null ? "created" : "updated" };
 }
@@ -3796,7 +4121,7 @@ function manifestReader() {
 function sameOutput(a, b) {
   const selectionKey = (s) => JSON.stringify([s.foundation, s.components === null ? null : [...new Set(s.components.map(slugify))].sort()]);
   const key = (v) => JSON.stringify(sortKeys(v ?? {}));
-  return selectionKey(a.selection) === selectionKey(b.selection) && key(a.dtcg) === key(b.dtcg) && key(a.outputs ?? []) === key(b.outputs ?? []);
+  return selectionKey(a.selection) === selectionKey(b.selection) && key(a.dtcg) === key(b.dtcg) && key(a.outputs ?? []) === key(b.outputs ?? []) && (a.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR) === (b.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR);
 }
 function sortKeys(value) {
   if (Array.isArray(value)) return value.map(sortKeys);
@@ -3827,12 +4152,12 @@ 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.`;
+var NO_PLATFORM_NOTE = `No target platform detected, so no token files were 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.`;
+  return `No token files exist 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) {
@@ -3855,12 +4180,13 @@ function runInit(cwd, flags, io2) {
   writeConfig(cwd, {
     libraryId: flags.id,
     outDir,
+    componentSpecsDir: DEFAULT_COMPONENT_SPECS_DIR,
     ...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.`);
+  for (const o of outputs) io2.out(`Token files 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));
@@ -3888,7 +4214,7 @@ function resolved(cwd, flags, env, io2, manifestAt) {
 }
 function resolvedOutDir(cwd, flags, io2) {
   try {
-    return join7(cwd, flags.out ?? readConfig(cwd)?.outDir ?? DEFAULT_OUT_DIR);
+    return join8(cwd, flags.out ?? readConfig(cwd)?.outDir ?? DEFAULT_OUT_DIR);
   } catch (err) {
     io2.err(errorText(err));
     return null;
@@ -3927,6 +4253,7 @@ async function runSetup(cwd, flags, env, io2, fetcher) {
   const fromFlags = platformsFromFlags(flags, io2);
   if (fromFlags === null) return 1;
   const outDir = flags.out ?? existing?.outDir ?? DEFAULT_OUT_DIR;
+  const componentSpecsDir = existing?.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR;
   const keptInclude = include ?? existing?.include ?? null;
   const keptDtcg = existing?.dtcg ?? null;
   const { platforms } = resolvePlatforms(cwd, fromFlags, existing);
@@ -3934,6 +4261,7 @@ async function runSetup(cwd, flags, env, io2, fetcher) {
   writeConfig(cwd, {
     libraryId: flags.id,
     outDir,
+    componentSpecsDir,
     ...keptInclude ? { include: keptInclude } : {},
     ...keptDtcg ? { dtcg: keptDtcg } : {},
     ...platforms.length > 0 ? { platforms } : {},
@@ -3986,6 +4314,12 @@ git rm --cached ${ignored.line}`);
   io2.out("spec-layer skill prints the same guide; spec-layer tools lists every command.");
   return 0;
 }
+function outputFilesOnDisk(cwd, outDir, o) {
+  const mapPath = join8(cwd, outDir, "outputs", `${outputId(o)}.map.json`);
+  if (!existsSync8(mapPath)) return false;
+  const imports = readIndexImports(cwd, o);
+  return imports !== null && imports.every((f) => existsSync8(resolve5(cwd, o.path, f)));
+}
 async function runPull(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
   const opts = resolved(cwd, flags, env, io2, manifestAt);
@@ -4001,13 +4335,14 @@ async function runPull(cwd, flags, env, io2, fetcher) {
   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 manifest = manifestAt(join8(cwd, opts.outDir));
   const foundationOnDisk = Boolean(manifest?.artifacts.find((a) => a.kind === "foundation")?.path);
   const willWriteFoundation = selection.foundation && foundationOnDisk;
+  const briefsOnDisk = (manifest?.artifacts ?? []).filter((a) => a.kind === "component" && a.path !== null).every((a) => existsSync8(resolve5(cwd, a.path)));
   const etag = manifest && sameOutput(
-    { 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;
+    { selection: manifest.selection ?? DEFAULT_SELECTION, dtcg: manifest.dtcg, outputs: manifest.outputs, componentSpecsDir: manifest.componentSpecsDir },
+    { selection, dtcg: opts.dtcg, outputs, componentSpecsDir: opts.componentSpecsDir }
+  ) && briefsOnDisk && (!willWriteFoundation || outputs.every((o) => outputFilesOnDisk(cwd, opts.outDir, o))) ? manifest.bundleHash : void 0;
   const result = await fetchBundle({
     api: opts.api,
     libraryId: opts.libraryId,
@@ -4024,12 +4359,13 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     return 0;
   }
   let written;
-  let outputPaths = [];
+  let componentSpecs;
+  let outputResults;
   try {
     const bundle = parseBundle(result.raw);
     const selected = selectComponents(bundle, selection);
     const writeResult = writeBundleFiles({
-      outDir: join7(cwd, opts.outDir),
+      outDir: join8(cwd, opts.outDir),
       cwd,
       raw: result.raw,
       bundle,
@@ -4039,10 +4375,12 @@ async function runPull(cwd, flags, env, io2, fetcher) {
       bundleHash: result.bundleHash,
       dtcg: opts.dtcg,
       platforms,
-      outputs
+      outputs,
+      componentSpecsDir: opts.componentSpecsDir
     });
     written = writeResult.written;
-    outputPaths = writeResult.outputs;
+    componentSpecs = writeResult.componentSpecs;
+    outputResults = writeResult.outputs;
     io2.out(
       `Pulled ${bundle.fileName ?? opts.libraryId}: ${describePull(bundle, selection, selected)} (published ${result.publishedAt}).`
     );
@@ -4050,12 +4388,24 @@ async function runPull(cwd, flags, env, io2, fetcher) {
     io2.err(errorText(err));
     return 1;
   }
+  const count = (n) => `${n} file${n === 1 ? "" : "s"}`;
   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 (componentSpecs.files.length > 0) io2.out(`Wrote ${componentSpecs.path}/ (${count(componentSpecs.files.length)}).`);
+  for (const r of outputResults) {
+    const o = outputs.find((x) => x.path === r.path);
+    if (o) io2.out(`Wrote ${r.path}/ (${count(r.files.length)}, ${o.platform}/${o.format}, ${o.case} names).`);
+  }
+  const staleDirNote = (previous, current) => {
+    if (previous !== current && existsSync8(resolve5(cwd, previous))) {
+      io2.out(`The previous pull wrote ${previous}/; this one wrote ${current}/. Delete ${previous}/ if nothing else uses it.`);
+    }
+  };
+  if (manifest) staleDirNote(manifest.componentSpecsDir ?? DEFAULT_COMPONENT_SPECS_DIR, opts.componentSpecsDir);
+  for (const prev of manifest?.outputs ?? []) {
+    const current = outputs.find((o) => outputId(o) === outputId(prev));
+    if (current) staleDirNote(prev.path, current.path);
   }
-  if (outputPaths.length === 0 && selection.foundation && source === "none" && opts.outputs === void 0) io2.out(NO_PLATFORM_NOTE);
+  if (outputResults.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));
@@ -4066,7 +4416,7 @@ async function runStatus(cwd, flags, env, io2, fetcher) {
   const manifestAt = manifestReader();
   const opts = resolved(cwd, flags, env, io2, manifestAt);
   if (!opts) return 1;
-  const manifest = manifestAt(join7(cwd, opts.outDir));
+  const manifest = manifestAt(join8(cwd, opts.outDir));
   if (!manifest) {
     io2.err(NO_LOCAL_PULL);
     return 2;
@@ -4104,7 +4454,7 @@ function runList(cwd, flags, io2) {
     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`));
+    const written = existsSync8(join8(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;
@@ -4174,7 +4524,7 @@ function collectSkillInput(cwd, flags, io2) {
   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)));
+  const pull = summarizePull(cwd, outDir, readManifest(join8(cwd, outDir)));
   return { profile, platforms, platformSource, outDir, config, pull, version: cliVersion() };
 }
 function skillHosts(flags, input, io2) {