spec-layer 0.4.0 → 0.5.0

package/README.md

@@ -55,6 +55,7 @@ also keeps `.speclayer/manifest.json` on one format: 0.1.0 wrote no
 versions have no such command, so the setup command the plugin copies fails
 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.
 
 ## Commands
 
@@ -67,9 +68,76 @@ Module 2025.10 files, rather than `ai/foundation.yaml`, needs 0.4.0 or later.
 | `list` | Lists every artifact in the last pull, with its file path or `not written`. |
 | `show foundation [--canonical]` | Prints the Foundation's DTCG document to stdout. |
 | `show component NAME [--canonical]` | Prints one component's AI YAML to stdout. |
+| `tools [--json]` | Lists every command with what it reaches, needs, and writes. |
+| `skill [--install] [--agent HOST]... [--platform P] [--json]` | Prints a guide for a coding agent, adapted to this repository and the last pull; `--install` writes it where the agent reads instructions. |
 
 `--api URL` overrides the API origin (default `https://api.spec-layer.com`).
 
+## For a coding agent
+
+The setup command is usually handed to a coding agent, and a bare command
+tells the agent nothing about what it just wrote or how to read it. Two
+local commands close that gap; neither needs a key or the network.
+
+`spec-layer tools` lists every command with the facts an agent needs before
+running one: whether it reaches the network, whether it needs the pull key,
+what it writes, and what each exit code means. `--json` prints the same list
+in a stable shape for machines.
+
+`spec-layer skill` prints a guide to the pulled files, and `--install` writes
+it where the agent reads project instructions:
+
+```bash
+npx spec-layer skill --install
+```
+
+`setup` names this command as the next step after a successful pull, and the
+plugin's Publish screen has a **Copy for an AI agent** button that copies the
+setup command already followed by it.
+
+The guide is built from three things and nothing else:
+
+- The tool list above.
+- **What the last pull wrote.** Every component with its file path, every
+  token collection with its modes and default, the token files, the
+  `report.json` counts, and how many tokens landed as plain numbers because
+  their Figma scopes state no unit. Before a pull the guide says so and names
+  nothing.
+- **What the repository root says about the codebase.** Detection reads only
+  the top level of the working directory (`package.json` dependency names,
+  build files, agent configuration directories) and names the file behind
+  every conclusion. A signal it cannot find is reported as absent, never
+  guessed. The platform decides which Figma `code_syntax` key the guide points
+  at (`WEB`, `iOS`, `ANDROID`; Flutter has none) and which token pipeline
+  advice it gives: Tailwind, Style Dictionary (with the `legacy` value form
+  suggested when package.json declares a major version below 5), Swift,
+  Kotlin or Compose, or Dart.
+
+`--platform web|ios|android|flutter` overrides the detected target, which is
+the way to get platform advice in a repository that carries no signal (a new
+directory, a monorepo whose apps sit one level down). `--json` prints the
+detection, the pull summary, and the install targets instead of the guide.
+
+`--install` writes to every agent host detected at the root, or to the hosts
+named with a repeatable `--agent`, or to `AGENTS.md` when nothing is detected
+and nothing is named. Each run says which files it wrote, updated, or left
+unchanged.
+
+| Host | `--agent` | File |
+|---|---|---|
+| Claude Code | `claude` | `.claude/skills/spec-layer/SKILL.md` |
+| Cursor | `cursor` | `.cursor/rules/spec-layer.mdc` |
+| GitHub Copilot | `copilot` | `.github/instructions/spec-layer.instructions.md` |
+| Windsurf | `windsurf` | `.windsurf/rules/spec-layer.md` |
+| Gemini CLI | `gemini` | `GEMINI.md`, between `<!-- spec-layer:begin -->` and `<!-- spec-layer:end -->` |
+| Anything that reads `AGENTS.md` | `agents-md` | `AGENTS.md`, between the same markers |
+
+The dedicated files are replaced whole. The shared files (`AGENTS.md`,
+`GEMINI.md`) are yours: only the marked block is replaced, and a file without
+the markers gets the block appended. Re-run `skill --install` after a pull
+that adds components or when the codebase changes stack. The written files
+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
@@ -232,7 +300,7 @@ the report are not token files; exclude them from token globs.
 | Code | Meaning |
 |---|---|
 | `0` | Success, or `status` found the local copy up to date. |
-| `1` | Usage error, bad key or id, unknown component name, or a network or server failure. |
+| `1` | Usage error, bad key or id, unknown component name, a network or server failure, or a file `skill --install` could not write. |
 | `2` | `status` only: the local copy is behind, or no local pull exists yet. |
 
 `status` is safe in CI: it writes nothing, and exit `2` is the signal to run

package/dist/cli.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spec-layer",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Pull design-system context published by the Spec Layer Figma plugin",
   "license": "MIT",
   "type": "module",
@@ -23,7 +23,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/SamsonHD/spec-layer.git",
+    "url": "git+https://github.com/sandroleks/spec-layer.git",
     "directory": "packages/cli"
   },
   "homepage": "https://spec-layer.com",