spec-layer 0.6.0 → 0.7.0

package/README.md

@@ -60,7 +60,9 @@ against them. The Foundation landing under `tokens/` as Design Tokens Format
 Module 2025.10 files, rather than `ai/foundation.yaml`, needs 0.4.0 or later.
 `tools` and `skill` need 0.5.0 or later. `components/` in place of
 `ai/components/`, `path` in place of `aiPath` in the manifest, and the
-`outputs` block need 0.6.0 or later.
+`outputs` block need 0.6.0 or later. `component-specs/` beside `tokens/`,
+`componentSpecsDir`, cwd-relative manifest paths, and the `tokens/` directory
+need 0.7.0 or later.
 
 ## Commands
 
@@ -146,7 +148,7 @@ carry no key and are meant to be committed with the rest of the repository.
 ## Pulling part of a library
 
 By default `pull` writes the Foundation and every documented component. When
-your repo implements only some of them, narrow what lands in `components/`:
+your repo implements only some of them, narrow what lands in `component-specs/`:
 
 ```bash
 npx spec-layer pull --only foundation            # tokens and styles, no components
@@ -177,7 +179,7 @@ That stores an `include` block in `speclayer.json`:
 Selection flags on `pull` replace the stored selection for that run; they are
 never merged with it.
 
-The selection only decides which `components/` files are written. `bundle.json`
+The selection only decides which `component-specs/` files are written. `bundle.json`
 always holds the whole library, so `list` and `show` can answer for any
 artifact, written or not, and `status` compares one hash.
 
@@ -244,7 +246,7 @@ matter what the ignore rules say.
 ```text
 .speclayer/
   bundle.json                the published bundle, verbatim
-  manifest.json               every artifact indexed by content hash and path, plus the selection and outputs
+  manifest.json              every artifact indexed by content hash and path, plus the selection, outputs, and componentSpecsDir
   tokens/                    the Foundation as Design Tokens Format Module 2025.10 files
     <collection>.<mode>.json one file per collection and mode, rooted at the collection name
     styles.typography.json   text styles as typography composites (when present)
@@ -252,19 +254,22 @@ matter what the ignore rules say.
     resolver.json            Design Tokens Resolver Module 2025.10: sets, modifiers, order
     spec-layer.meta.json     Figma ids, scopes, code syntax, publication, keyed by DTCG path
     report.json              what DTCG could not express, with reasons and stable ids
-  components/<name>.yaml     one file per selected component
   outputs/
-    web-css.map.json         DTCG path -> CSS custom property, with where the name came from
-    web-css.report.json      what the CSS file could not express
-spec-layer/
-  tokens.css                 the web token file, written in place at outputs[].path
+    web-css.map.json         DTCG path -> CSS custom property, where the name came from, and which file declares it
+    web-css.report.json      what the CSS files could not express
+component-specs/
+  <name>.yaml                one brief per selected component, byte-identical to Copy for AI
+tokens/
+  index.css                  imports every file below, in resolver order
+  <collection>.css           one file per single-mode collection, at :root
+  <collection>.<mode>.css    one file per mode of a multi-mode collection; the default at :root
 ```
 
-Point your agent at `.speclayer/components/` and `.speclayer/tokens/`, and
-import the token file for your platform from where `outputs` puts it. The
-component YAML is the same compact form the plugin's **Copy for AI** puts on
-your clipboard; `bundle.json` additionally holds the full canonical artifacts
-if you need them.
+Point your agent at `component-specs/` and `.speclayer/tokens/`, and import
+`tokens/index.css` from the platform's root stylesheet. The component YAML is
+the same compact form the plugin's **Copy for AI** puts on your clipboard;
+`bundle.json` additionally holds the full canonical artifacts if you need
+them.
 
 In `manifest.json`, an artifact the selection left unwritten has `"path":
 null`. A manifest from CLI 0.1.0 has no `selection` field and means
@@ -275,12 +280,19 @@ interrupted pull never leaves a half-written directory. `pull` refuses an
 output directory that is the current directory, a parent of it, or an existing
 non-empty directory it did not write, since the swap replaces that directory.
 
+`component-specs/` and `tokens/` are written in place, not swapped. `pull`
+owns exactly the files there that begin with its marker (the CSS header, or
+the brief's opening `spec_layer:` lines): it replaces or removes those,
+ignores dotfiles, and refuses to run when anything else is present. A
+repository that already uses a path can set `componentSpecsDir` or
+`outputs[].path`.
+
 When nothing changed since the last pull with the same selection, `pull`
 prints `Already up to date` and writes nothing. Every republish stamps a new
 export id and time into the canonical artifacts, so `bundle.json` and
 `manifest.json` change on each republish even when the content did not. The
-`components/` YAML files, the `tokens/` files, and the content hashes stay
-stable.
+`component-specs/` YAML files, the `.speclayer/tokens/` files, and the
+`tokens/` CSS stay stable.
 
 ## Configuring the token output
 
@@ -309,19 +321,26 @@ the report are not token files; exclude them from token globs.
 
 ## Token files for your code
 
-`pull` also writes a file your build compiles, one per platform output. For
-the web that is a CSS file of custom properties. The file is written only
-when that pull writes the Foundation; with `--only components` it is left
-exactly as it was, and `list` shows it as `not written`.
+`pull` also writes a `tokens/` directory at `outputs[].path`: one CSS file
+per collection and mode plus `index.css`, one per platform output. The
+directory is written only when that pull writes the Foundation; with
+`--only components` it is left exactly as it was, and `list` shows it as
+`not written`.
 
 ```css
+/* Generated by spec-layer from library lib_..., foundation sha256:..., web/css/kebab.
+   Do not edit. Change the design in Figma, republish, and run spec-layer pull. */
+
 :root {
   /* Foundation */
   --foundation-colors-blue-500: #2e72d1;
   --foundation-spacing-200: 8px;
-  /* Mapped Colors, Light */
-  --mapped-colors-surface-primary-default: var(--foundation-colors-blue-500);
 }
+```
+
+```css
+/* Generated by spec-layer from library lib_..., foundation sha256:..., web/css/kebab.
+   Do not edit. Change the design in Figma, republish, and run spec-layer pull. */
 
 [data-theme="dark"] {
   /* Mapped Colors, Dark */
@@ -329,23 +348,42 @@ exactly as it was, and `list` shows it as `not written`.
 }
 ```
 
-Sets and every collection's default mode sit at `:root`; every other mode is
-a block under `[data-theme="<mode>"]`. Aliases stay as `var()`. A number whose
-Figma scopes state no unit stays a bare number. Nothing about a mode's name
-selects a media query; wire `data-theme` to `prefers-color-scheme` yourself if
-the OS should choose.
+`index.css` holds the header, then one comment and one import per file, in
+resolver order, and no declarations of its own:
+
+```css
+/* Generated by spec-layer from library lib_..., foundation sha256:..., web/css/kebab.
+   Do not edit. Change the design in Figma, republish, and run spec-layer pull. */
+
+/* Foundation */
+@import "./foundation.css";
+/* Mapped Colors, Dark */
+@import "./mapped-colors.dark.css";
+```
 
-The file is written **in place** at the path in `speclayer.json`, outside the
-managed directory, so your bundler keeps watching it and the diff shows up in
-review. It begins with a header naming the library and the Foundation's
-content hash, and `pull` refuses to overwrite a file at that path that lacks
-the header.
+A set, which has one mode by construction, writes one file named for the
+collection alone, at `:root`. A collection with modes writes one file per
+mode: the default mode's file sits at `:root`, every other mode's file under
+`[data-theme="<mode>"]`. Aliases stay as `var()`. A number whose Figma scopes
+state no unit stays a bare number. Nothing about a mode's name selects a
+media query. To let the OS choose a theme, set that collection's selector to
+`:root` under `modes` and import the mode's file yourself under `@media
+(prefers-color-scheme: dark)`. The CLI never assumes that.
+
+The directory is written **in place** at the path in `speclayer.json`,
+outside the managed directory, so your bundler keeps watching it and the diff
+shows up in review. Every file begins with a header naming the library and
+the Foundation's content hash; `pull` owns exactly the files there that begin
+with it, replacing or removing those, ignoring dotfiles, and refusing to run
+when anything else is present. A `speclayer.json` written by CLI 0.6.0 names
+a `.css` file at this path, and `pull` refuses it: set `path` to a directory
+and delete the old file.
 
 ```json
 {
   "platforms": ["web"],
   "outputs": [
-    { "platform": "web", "format": "css", "path": "spec-layer/tokens.css", "case": "kebab" }
+    { "platform": "web", "format": "css", "path": "tokens", "case": "kebab" }
   ]
 }
 ```
@@ -355,28 +393,28 @@ at the repository root, so the path is always on record. `pull` writes every
 entry; `"outputs": []` writes none. `case` chooses how derived names are
 spelled: `kebab` (default), `camel`, `pascal`, `snake`, or `constant`. A name
 the designer declared as `code_syntax` in Figma is used verbatim and never
-re-cased. `.speclayer/outputs/web-css.map.json` records every emitted name and
-whether it was declared or derived; two tokens that would share a name are
-both omitted and listed in `web-css.report.json`.
+re-cased. `.speclayer/outputs/web-css.map.json` records every emitted name,
+whether it was declared or derived, and which file declares it; two tokens
+that would share a name are both omitted and listed in `web-css.report.json`.
 
 Two collections with modes share one attribute by default, which cannot be
 right for both; the report says so, and `modes` declares a selector per
 collection:
 
 ```json
-{ "platform": "web", "format": "css", "path": "spec-layer/tokens.css",
+{ "platform": "web", "format": "css", "path": "tokens",
   "modes": { "Density": "[data-density=\"{mode}\"]" } }
 ```
 
 `root` and `modeSelector` override the defaults `:root` and
 `[data-theme="{mode}"]`; `{mode}` and `{collection}` are replaced by slugs.
 A repository that already builds tokens with Style Dictionary can keep reading
-`tokens/`: the CSS file is a projection of the same files, not a second
-source, so import one or the other.
+`.speclayer/tokens/`: the CSS files are a projection of the same record, not a
+second source, so import one or the other.
 
-Commit `.speclayer/`, `speclayer.json`, and the output paths. A repository
-that would rather regenerate in CI ignores them and runs `pull` there;
-`status` exits `2` when a pull is due.
+Commit `.speclayer/`, `speclayer.json`, `component-specs/`, and the output
+paths. A repository that would rather regenerate in CI ignores them and runs
+`pull` there; `status` exits `2` when a pull is due.
 
 ## Exit codes
 

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 = [
@@ -1334,7 +1334,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",
@@ -2121,6 +2129,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 +2195,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 +2420,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 +2444,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 +2493,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 +2505,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,10 +2524,25 @@ 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")}
+}
+`;
+    imports.push(block.comment, `@import "./${name}";`);
+  }
+  if (imports.length > 0) files[CSS_INDEX_FILE] = `${head}
+
+${imports.join("\n")}
 `;
-  return { text, map, report: sortReport(entries) };
+  return { files, map, report: sortReport(entries) };
 }
 
 // ../extractor/src/v5/componentContext.ts
@@ -2585,7 +2637,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 +2820,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 +2972,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 +3024,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 +3052,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 +3065,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 +3076,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 +3102,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 +3148,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 +3187,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 +3206,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 +3236,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 +3250,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 +3274,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 +3291,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 +3308,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 +3322,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 +3335,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 +3354,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 +3373,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 +3398,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 +3417,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 +3435,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 +3552,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 +3595,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 +3660,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 +3680,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 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 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.`,
             ""
           );
         } 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 +3774,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 +3831,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 +3915,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 +3952,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 +3983,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 +4011,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 +4045,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 +4084,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 +4092,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 +4145,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 +4166,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 +4190,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 +4206,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 +4219,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 +4247,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 +4285,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 +4355,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) {

package/package.json

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