spec-layer 0.4.0 → 0.6.0

package/README.md

@@ -14,9 +14,12 @@ After publishing a library from the plugin's Library screen, it shows a setup
 command. Run it once in your repository:
 
 ```bash
-npx spec-layer setup --id lib_... --key sl_...
+npx spec-layer setup --id lib_... --key sl_... --platform web
 ```
 
+`--platform` says what you build; without it, `setup` reads the repository
+root and writes a token file only when it finds a web signal.
+
 That records the library id, stores the key in a gitignored
 `speclayer.local.json`, and writes `.speclayer/`. Every later command needs no
 flags at all:
@@ -55,25 +58,95 @@ 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. `components/` in place of
+`ai/components/`, `path` in place of `aiPath` in the manifest, and the
+`outputs` block need 0.6.0 or later.
 
 ## Commands
 
 | Command | What it does |
 |---|---|
-| `setup --id lib_... --key sl_... [--out DIR] [selection]` | Writes `speclayer.json`, stores the key in `speclayer.local.json`, then pulls. The command the plugin copies. |
-| `init --id lib_... [--out DIR] [selection]` | Writes `speclayer.json` so later commands need no flags. No key, no network. |
-| `pull [--id lib_...] [--key sl_...] [selection]` | Fetches the library and writes it into `DIR` (default `.speclayer`). |
+| `setup --id lib_... --key sl_... [--out DIR] [--platform P]... [selection]` | Writes `speclayer.json`, stores the key in `speclayer.local.json`, then pulls. The command the plugin copies. |
+| `init --id lib_... [--out DIR] [--platform P]... [selection]` | Writes `speclayer.json` so later commands need no flags. No key, no network. |
+| `pull [--id lib_...] [--key sl_...] [--platform P]... [selection]` | Fetches the library and writes it into `DIR` (default `.speclayer`). |
 | `status [--id lib_...] [--key sl_...]` | Checks freshness without writing. Exits `2` when the local copy is behind. |
 | `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
-your repo implements only some of them, narrow what lands in `ai/`:
+your repo implements only some of them, narrow what lands in `components/`:
 
 ```bash
 npx spec-layer pull --only foundation            # tokens and styles, no components
@@ -104,7 +177,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 `ai/` files are written. `bundle.json`
+The selection only decides which `components/` 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.
 
@@ -171,7 +244,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
+  manifest.json               every artifact indexed by content hash and path, plus the selection and outputs
   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)
@@ -179,15 +252,21 @@ 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
-  ai/components/<name>.yaml  one file per selected component
+  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
 ```
 
-Point your agent at `.speclayer/ai/` and `.speclayer/tokens/`. 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 `.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.
 
-In `manifest.json`, an artifact the selection left unwritten has `"aiPath":
+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
 everything was written.
 
@@ -200,7 +279,8 @@ 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
-`ai/` YAML files, the `tokens/` files, and the content hashes stay stable.
+`components/` YAML files, the `tokens/` files, and the content hashes stay
+stable.
 
 ## Configuring the token output
 
@@ -227,12 +307,83 @@ Point Style Dictionary at `.speclayer/tokens/` and load the files
 `resolver.json` names for the mode you are building. The metadata sidecar and
 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`.
+
+```css
+:root {
+  /* Foundation */
+  --foundation-colors-blue-500: #2e72d1;
+  --foundation-spacing-200: 8px;
+  /* Mapped Colors, Light */
+  --mapped-colors-surface-primary-default: var(--foundation-colors-blue-500);
+}
+
+[data-theme="dark"] {
+  /* Mapped Colors, Dark */
+  --mapped-colors-surface-primary-default: var(--foundation-colors-blue-900);
+}
+```
+
+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.
+
+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.
+
+```json
+{
+  "platforms": ["web"],
+  "outputs": [
+    { "platform": "web", "format": "css", "path": "spec-layer/tokens.css", "case": "kebab" }
+  ]
+}
+```
+
+`setup` and `init` write this block from `--platform`, or from what they detect
+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`.
+
+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",
+  "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.
+
+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.
+
 ## Exit codes
 
 | 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
@@ -240,5 +391,5 @@ the report are not token files; exclude them from token globs.
 
 ## Requirements
 
-Node 22 or newer. Publishing requires a Spec Layer Pro license; pulling does
-not.
+Node 22 or newer. Publishing one Figma file is free; Pro publishes up to ten.
+Pulling needs only the library id and pull key.