@radicool/throughline 0.12.1 → 0.14.0

package/adapters/generic/skills/token-builder/SKILL.md

@@ -51,6 +51,22 @@ and why large `WRAP` grids time out. For a simple verification read, prefer the
 dedicated `figma_get_variables` tool (it handles dynamic-page correctly and
 resolves aliases with `resolveAliases: true`) over a hand-written script.
 
+**Execution model — sequential architect → figma-executor with model routing.**
+If your host supports subagent dispatch, plan the token architecture once with
+one **architect** dispatch (deep tier) — it reads existing Figma state and emits
+a transcription-grade spec in stable identifiers (collection/variable *names*,
+never nodeIds) — then build the variables with **figma-executor** dispatches
+(balanced tier), strictly sequentially: preflight `figma_get_status` and never
+run two Figma-touching subagents at once (the single bridge is concurrency-1).
+Each executor finalizes by build-verify-then-replace with a programmatic
+read-back (`figma_get_variables`, not a screenshot); gate the result with a
+**reviewer** pass. **Keep the human checkpoint between tiers** (the PAUSE in
+Steps 2–4) — subagents run continuously within a tier, but you pause for the
+human between them. Route per
+`.throughline/references/agent-routing.md`; never parallelize Figma
+work. If your host has no subagent dispatch, build and verify each tier inline,
+sequentially, as the steps below describe.
+
 ## Step 1 — Brainstorm the structure (before building anything)
 
 Run the protocol in `.throughline/references/brainstorm-before-build.md`. **First establish

package/adapters/generic/skills/token-sheet-builder/SKILL.md

@@ -33,6 +33,20 @@ swatch/type grids — exactly the layouts that hit the two worst traps: the
 single-call `layoutWrap = "WRAP"` timeout on big grids (build manual rows or split
 across calls instead). Also run the single-bridge-instance preflight before writing.
 
+**Execution model — sequential architect → figma-executor with model routing.**
+If your host supports subagent dispatch, plan the sheet layout once with one
+**architect** dispatch (deep tier) — a lighter plan than token-builder's, since
+the tokens already exist; it emits a stable-identifier layout spec (which
+collections/sections, how much per-token detail) — then build the page with
+**figma-executor** dispatches (balanced tier), strictly sequentially: preflight
+`figma_get_status`, concurrency-1, `WIP:` frame + build-verify-then-replace with
+a programmatic read-back (spot-check that the swatches resolved to their bound
+variables via `figma_get_variables`, not just a screenshot), gated by a
+**reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`; never parallelize Figma
+work. If your host has no subagent dispatch, build and verify the page inline,
+sequentially, as the steps below describe.
+
 ## Step 1 — Brainstorm the layout (lightly)
 
 Run `.throughline/references/brainstorm-before-build.md`, but keep it light — this is a
@@ -141,7 +155,7 @@ refresh the "Last updated" date instead of creating a second Cover.)
 ## Step 3 — Checkpoint
 
 Show the user the Foundations page and the Cover page. Sequential review (this is
-a Figma-authoring skill — no subagents). Iterate on layout/styling if they want
+a Figma-authoring skill). Iterate on layout/styling if they want
 changes. Then update the manifest: `sheets.built` = `true`, append
 `token-sheet-builder` to `completedSkills`.
 

package/adapters/generic/skills/token-sync-layer/SKILL.md

@@ -139,13 +139,18 @@ register the platform, transform group, format, and `outputReferences`
 flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
 adapter also emits a Tailwind preset.
 
-**Execution model — subagent-driven for multiple platforms.** When more than one
-platform is targeted, generating each platform's output is independent and
-verifiable, so dispatch **one subagent per adapter**: each produces its
+**Execution model — subagent dispatch with model routing.** Generating each
+platform's output is independent and verifiable. If your host supports subagent
+dispatch, dispatch **one `code-executor` per adapter** — each produces its
 platform's files and verifies them (the config builds, the expected files
-appear, references resolve correctly for web / flatten for native). Review each
-before combining. For a single platform, run inline. (See the selective-
-subagent decision: code-gen skills parallelize; Figma-authoring skills don't.)
+appear, references resolve for web / flatten for native) — then a **`reviewer`**
+to check each before combining. Choose each subagent's model from its role tier
+per `.throughline/references/agent-routing.md` (`code-executor` → fast,
+`reviewer` → balanced), and only dispatch once each adapter's spec is complete
+enough to transcribe. If your host has no subagent dispatch, generate and verify
+each adapter inline instead. For a single platform, run inline either way. This
+is a code-gen stage, so these subagents may run in parallel — unlike Figma
+authoring, which is always sequential.
 
 ## Step 4 — Build and place outputs
 
@@ -169,7 +174,9 @@ icons (`icons.built` true):
 - **Custom icons** — these the repo owns, so generate them: export the custom
   SVGs from Figma, optimize, and componentize via SVGR into `packages/ui` (or a
   dedicated icons package). This is real code generation and rides the same
-  PR-review and subagent model as token output.
+  **`code-executor` (fast) + `reviewer` (balanced)** routing and PR-review as
+  token output (SVGR transforms are the textbook mechanical op the fast tier is
+  for) — see the Step 4 execution model.
 
 ## Step 5 — Full regeneration + rename detection (the safety net)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "Build a complete design system end to end — author in Figma, sync tokens to code, generate Storybook. Usable from Claude Code, Cursor, Codex, or any AGENTS.md agent.",
   "type": "module",
   "bin": {

package/references/agent-routing.md

@@ -0,0 +1,70 @@
+# Agent routing — choosing a model per subagent
+
+**Claude-only.** This reference governs subagent dispatch, a Claude Code
+capability. Hosts without subagent dispatch (Codex, generic AGENTS.md) run the
+work inline on their single model and ignore this file.
+
+## Why route
+
+Do the *thinking* on the best model and the *doing* on a cheap one. Deciding a
+component's variant matrix, token architecture, or adapter strategy is reasoning
+— it earns the best model. Running the resulting spec — transcribing code,
+placing Figma nodes, emitting adapter output — is mechanical, and a cheap model
+does it well **once the plan is complete**.
+
+## The tier ladder
+
+Relative, never a hardcoded model name — installers have different plans, so we
+name a *capability tier* and resolve it against the models actually available.
+
+- `fast` — cheapest/fastest tier. Transcription-grade work from a complete spec.
+- `balanced` — mid tier. Judgment, integration, review scaled to risk.
+- `deep` — most capable tier available. Planning, architecture, hard reasoning.
+
+### Recommended mapping (Anthropic)
+
+| Tier | Recommended model |
+|---|---|
+| `fast` | Haiku |
+| `balanced` | Sonnet |
+| `deep` | Opus (or the most capable model you have) |
+
+**Override in one place:** edit this table for your plan. Everything downstream
+reads tiers, not model names.
+
+### Resolution + fallback
+
+At dispatch, resolve the role's tier to a concrete model **from the models you
+actually have**, then pass it explicitly (an omitted model inherits the session
+model — often the most expensive — which defeats routing). If a tier's model is
+unavailable, **collapse to the nearest lower tier you have**; `deep` always maps
+to the most capable model available. An installer with only one model degrades
+to that model everywhere — routing becomes a no-op, never a failure.
+
+## Roles → tiers
+
+| Agent | Tier | Concurrency | Role |
+|---|---|---|---|
+| `code-executor` | `fast` | parallel-safe | Transcribe code/adapter output from a complete spec; verify its own build. |
+| `reviewer` | `balanced` (scale to risk) | parallel-safe | Spec-compliance + quality gate; code-diff or Figma-visual mode. |
+| `architect` | `deep` | 1 | Plan a stage; read Figma read-only; emit a transcription-grade spec in stable identifiers (names, never nodeIds). |
+| `figma-executor` | `fast`→`balanced` (default **`balanced`** for a real component build; `fast` only for trivial mechanical ops) | **1 (bridge-locked)** | Resolve names→nodeIds at run time; build into a `WIP:` frame; verify via `COMPONENT_SET` read-back (not screenshot-only); finalize by build-verify-then-replace and reap `WIP:` debris. |
+
+## The spec-completeness gate
+
+Dispatch an executor on `fast` **only when the spec is transcription-grade** —
+complete enough that execution is copying, not deciding. Turn count beats token
+price: a cheap model on a vague task takes 2–3× the turns and costs more. If the
+spec is incomplete, run the work inline on the stronger model instead.
+
+## Escalation
+
+A `BLOCKED` executor is re-dispatched **one tier up**, never the same model
+unchanged. If still blocked at `deep`, escalate to the human.
+
+## Concurrency
+
+Code-gen roles are parallel-safe. Figma work is **not**: the figma-console
+bridge is a single live connection with global selection/current-page state, so
+the entire Figma surface is concurrency-1. Route Figma work through
+sequential subagents — model routing yes, parallelism never.

package/references/component-doc-archetypes.md

@@ -0,0 +1,86 @@
+# Component documentation archetypes
+
+The best-practice knowledge layer for the documentation generation pipeline
+(`component-builder` Step: *Author the documentation record*). When authoring a
+component's `.doc.json`, match the component to the nearest **archetype** below and
+seed its `dos`, `donts`, `accessibility`, `whenToUse`, and `whenNotToUse` from that
+entry, then specialize to the target framework and confirm with the user. Stamp
+`provenance` as `best-practice` (or `w3c-apg` for the accessibility block) for
+anything sourced here.
+
+These are **seeds, not gospel** — the user's approval and the actual built
+component override them. Sources: W3C ARIA Authoring Practices Guide (roles +
+keyboard), Material 3, Shopify Polaris (content/usage), IBM Carbon (usage).
+
+## Button
+
+- **whenToUse:** trigger an action or event (submit, confirm, open a dialog).
+- **whenNotToUse:** navigation between pages/URLs — use a Link.
+- **dos:** lead the label with a verb; keep one primary (highest-emphasis) button
+  per view; keep labels short (≤ ~3 words).
+- **donts:** don't use a button for navigation; don't stack multiple primary
+  buttons; don't disable without telling the user why.
+- **accessibility (w3c-apg):** role `button`; Enter and Space activate; an
+  icon-only button needs an `aria-label`; disabled buttons are not focusable.
+
+## Input / text field
+
+- **whenToUse:** collect a single line of free-form text.
+- **whenNotToUse:** choosing from a fixed set (use Select/Radio); long multi-line
+  text (use Textarea).
+- **dos:** always pair with a visible label; show format hints as helper text;
+  reserve space for error text to avoid layout shift.
+- **donts:** don't use placeholder text as the only label; don't validate on every
+  keystroke before first blur.
+- **accessibility (w3c-apg):** every input has a programmatically associated
+  `<label>`; error state sets `aria-invalid` and links the message via
+  `aria-describedby`.
+
+## Checkbox / radio / toggle
+
+- **whenToUse:** checkbox/toggle for independent on/off; radio for one-of-many.
+- **whenNotToUse:** a single either/or action that takes effect immediately with no
+  save (prefer a toggle) vs. a form choice (prefer radio/checkbox).
+- **dos:** label the control, not just the group; make the label clickable.
+- **donts:** don't use a radio group for multi-select; don't use a toggle for
+  choices that only apply after a separate Save.
+- **accessibility (w3c-apg):** roles `checkbox` / `radio` / `switch`; Space
+  toggles; radio groups navigate with arrow keys; state exposed via
+  `aria-checked`.
+
+## Card
+
+- **whenToUse:** group related content and actions about a single subject.
+- **whenNotToUse:** primary page layout scaffolding; a bare list of text.
+- **dos:** make the primary action obvious; keep one main call-to-action per card.
+- **donts:** don't nest cards more than one level; don't make the whole card AND an
+  inner button separately clickable in conflicting ways.
+- **accessibility:** if the whole card is a link/button, it needs an accessible
+  name; don't bury interactive controls that keyboard users can't reach in order.
+
+## Modal / dialog
+
+- **whenToUse:** interrupt for a focused task or a decision that blocks the flow.
+- **whenNotToUse:** non-critical messages (use an inline banner or toast).
+- **dos:** trap focus while open; return focus to the trigger on close; provide an
+  explicit close affordance.
+- **donts:** don't stack modals; don't put long scrolling forms in a small modal.
+- **accessibility (w3c-apg):** role `dialog` with `aria-modal="true"`; labelled by
+  its title (`aria-labelledby`); Escape closes; focus is trapped within.
+
+## Badge / chip / tag
+
+- **whenToUse:** short status, count, or category label (badge); a removable/
+  selectable token (chip).
+- **whenNotToUse:** interactive primary actions (use a Button).
+- **dos:** keep text to a word or two; bind color to a semantic tone token.
+- **donts:** don't rely on color alone to convey status — include text/icon.
+- **accessibility:** a removable chip's remove control needs an accessible name
+  (e.g. "Remove <label>"); status conveyed with text, not color only (WCAG 1.4.1).
+
+## Fallback (unlisted archetype)
+
+For a component without an entry above: derive `dos`/`donts` from its role and
+built structure, source the `accessibility` block from the matching W3C APG
+pattern, and mark everything for user confirmation. Add a new archetype section
+here once the component's guidance stabilizes.

package/references/component-doc-schema.md

@@ -0,0 +1,136 @@
+# Component documentation record
+
+The canonical, folder-resident source of truth for a component's usage
+documentation. One JSON file per component at
+`design-system/docs/components/<ComponentName>.doc.json`. Every other
+documentation surface (Figma component description, the doc card, Storybook
+autodocs/MDX, the AI digest) is a **projection** rendered from this file — never
+authored independently.
+
+It lives in the working folder from the moment a component is built (exactly like
+`design-system.json`), so it exists during the Figma-only *folder* stage, before
+any repo. The path stays `design-system/docs/` across folder→repo; files never
+move.
+
+## Why JSON (not YAML)
+
+The plugin's scripts are zero-dependency and there is no YAML parser available, so
+the record is JSON to keep `docs:check` and `docs:digest` able to parse it
+deterministically. JSON is equally machine-legible for AI consumers.
+
+## Schema
+
+```json
+{
+  "name": "Button",
+  "summary": "Triggers an action or event.",
+  "description": "A clickable control that initiates an action…",
+  "whenToUse": ["Submitting a form", "Confirming a decision"],
+  "whenNotToUse": ["Navigating to a new page — use a Link"],
+  "variants": {
+    "type": { "primary": "Highest-emphasis action…", "secondary": "…", "ghost": "…" },
+    "size": { "sm": "…", "md": "…", "lg": "…" }
+  },
+  "states": { "hover": "…", "focus": "…", "disabled": "…", "loading": "…" },
+  "dos": ["Lead with a verb", "One primary button per view"],
+  "donts": ["Don't use for navigation", "Don't stack >2 primaries"],
+  "accessibility": {
+    "role": "button",
+    "keyboard": ["Enter / Space activates"],
+    "notes": ["Icon-only buttons need an aria-label"]
+  },
+  "tokensUsed": ["color.bg.primary", "spacing.sm", "radius.md"],
+  "status": "stable",
+  "updatedAt": "2026-07-14",
+  "provenance": {
+    "description": "ai-inferred",
+    "dos": "best-practice+user",
+    "accessibility": "w3c-apg"
+  }
+}
+```
+
+### Fields (v1 core)
+
+- **Required:** `name`, `summary`, `description`.
+- **Optional content:** `whenToUse`, `whenNotToUse`, `variants`, `states`, `dos`,
+  `donts`, `accessibility`, `tokensUsed`.
+- **Lifecycle:** `status` (`draft`|`beta`|`stable`|`deprecated`), `updatedAt` (ISO date).
+- **`provenance`** — per-block author source, one of `imported`, `ai-inferred`,
+  `best-practice`, `w3c-apg`, `framework`, `user`, or a `+`-joined combination
+  (e.g. `best-practice+user`). Regeneration re-infers `ai-inferred`/`framework`
+  blocks and **never overwrites** a block whose provenance includes `user` or
+  `imported`.
+
+Deferred to a later version (do not emit in v1): `anatomy`, `content` (writing
+guidelines), `examples`.
+
+## Fingerprint algorithm
+
+`fingerprint = sha256(stableStringify(record_without_provenance)).slice(0, 16)`
+
+- `provenance` is **excluded** — it is authoring metadata, not projected content.
+- `stableStringify` sorts object keys recursively so formatting/key-order never
+  affects the hash.
+- The 16-hex-char result is the stamp recorded per surface and per canonical file.
+
+Implemented once in `scripts/lib/doc-record.mjs` (`canonicalFingerprint`) and
+reused by `docs:check`, `docs:digest`, and — for the Figma surfaces — by the
+Figma-connected skill computing the identical hash over the description content.
+
+## Projection mapping
+
+| Block(s) | Figma component description | Doc card | Storybook autodocs (MDX) + JSDoc | AI digest |
+|---|---|---|---|---|
+| summary, description | ✔ | ✔ | ✔ | ✔ |
+| whenToUse / whenNotToUse | ✔ | ✔ | ✔ | ✔ |
+| variants, states (meanings) | ✔ compact | ✔ legend | ✔ argTypes | ✔ |
+| dos / donts | ✔ | ✔ | ✔ | ✔ |
+| accessibility | ✔ | ✔ | ✔ | ✔ |
+| tokensUsed | — | — | ✔ | ✔ |
+
+Each surface carries a fingerprint stamp of the record it was rendered from:
+- **Figma component description** — a trailing marker line `<!-- tl:doc <fp> -->`.
+- **Doc card** — a named metadata node `Doc Fingerprint` holding `<fp>`.
+- **Storybook MDX** — a frontmatter field `docFingerprint: <fp>`.
+
+## Manifest pointer (`components.meta[name].doc`)
+
+The manifest stores pointers + per-surface fingerprints, never content:
+
+```json
+{
+  "doc": {
+    "path": "design-system/docs/components/Button.doc.json",
+    "fingerprint": "<canonical fingerprint at last render>",
+    "surfaces": {
+      "figmaDescription": { "src": "<fp>", "render": "<hash of description text>" },
+      "docCard":          { "src": "<fp>", "render": "<hash of card content>" },
+      "storybookMdx":     { "src": "<fp>", "render": "<hash of mdx file>", "file": "packages/ui/src/Button/Button.mdx" }
+    }
+  }
+}
+```
+
+- `src` — the canonical fingerprint the surface was rendered from (detects **stale**).
+- `render` — a hash of the surface's rendered content at render time (detects
+  **edited**, for surfaces the tooling can re-read).
+- `file` — repo-relative path for code surfaces so `docs:check` can re-read them.
+
+## Drift + reconciliation contract
+
+`docs:check` classifies each surface:
+- **canonical-changed** — the `.doc.json` fingerprint ≠ `doc.fingerprint`.
+- **stale** — `surface.src` ≠ current canonical fingerprint.
+- **edited** — a re-readable surface's current content hash ≠ `surface.render`.
+- **missing-surface** — a repo surface that declares a `file` which is now gone.
+  Failing, and distinct from `edit-unverified`: the surface *was* re-readable and
+  its rendered output has been deleted, not merely unreadable this run.
+- **edit-unverified** — a surface the CLI can't read (Figma); checked live by the
+  Figma-connected skill instead.
+
+Reconciliation is **per item, reviewable**: for each drift the user chooses
+**re-render** (canonical wins) or **pull-back** (fold the surface edit into the
+record), landed as a PR. **Brownfield first run is an adoption**, not a re-render:
+existing surface content is claimed into the record as `provenance: imported` and
+fingerprints are stamped, rather than treated as `edited` drift.

package/references/figma-component-standards.md

@@ -227,6 +227,30 @@ variant explosion), so **prefer them for composite components**.
   plain instance-swap property instead — slots are for freeform/repeating areas.)
 - **Single icon** (button leading icon) → instance-swap property, not a slot.
 
+### Rule: icons match the component's text color
+
+**A leading or trailing icon inside a text-bearing component ALWAYS takes the
+same color token as that component's adjacent text/label — in every variant,
+tone, and state.** Bind the icon to the *same* variable the label uses (e.g. a
+badge icon and its label both bind the tone's `fg`; a primary button's icon and
+label both bind `text/onEmphasis`). This is what prevents the mismatch failures:
+a white-text/black-icon control, an icon that stays one fixed color while the
+text changes per tone, or an icon that ignores the theme.
+
+Apply the color on the channel the icon actually draws with, and only that
+channel:
+
+- **Line / outline icons** (Lucide, Material Symbols outlined — most sets here)
+  draw with a **stroke and no fill.** Bind the color on the vectors' **stroke**
+  and leave the **fill empty.** Never bind a line icon's fill — a filled
+  outline path renders as a solid blob.
+- **Solid / filled glyphs** draw with a **fill.** Bind the color on the fill;
+  they have no meaningful stroke.
+
+Never hardcode an icon color, and never leave a fixed dark (or light) icon color
+across tones/states. Bind the override on the icon **instance's** vectors — never
+edit the shared `icon/*` source component, which would recolor every other usage.
+
 **Practical rules (from Figma's constraints):**
 - **Auto layout must be clean first.** Slots depend on a correct auto layout
   setup — a messy one makes everything shift. This is why auto-layout-on-

package/references/figma-scripting.md

@@ -38,6 +38,37 @@ This is the bridge-side application of the read-discipline principle (B4) in
 `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`: don't assert "another
 instance is active" without confirming it's actually live.
 
+## Preflight: confirm the *active* file is your target (writes hit the active file)
+
+A connected bridge is **not** the same as the *right* file. `figma_execute` (and
+every write) targets whichever file is currently **active** in Figma Desktop — it
+takes no `fileUrl`/`fileKey` argument. So a green `figma_get_status` only proves a
+bridge exists; the active file can silently drift to a different open file between
+your preflight and your write (a user tabbing to another file, a `figma_navigate`
+from an earlier step, a plugin reload). Writing then lands in the wrong file —
+best case it errors with "collection/node not found"; worse case it mutates the
+wrong document.
+
+**So the preflight must assert the active file's *identity*, not just connection:**
+
+1. **Know your target `fileKey`** before writing (the one your architect read, or
+   the one the workflow is scoped to).
+2. **Read the active file and compare.** `figma_get_status` reports
+   `currentFileKey` / `currentFileName`; `figma_list_open_files` shows every
+   connected file and which is active. Confirm the active `fileKey` equals your
+   target before the first write **and** re-confirm after any step that could have
+   switched it.
+3. **If it drifted, navigate — don't just retry.** `figma_navigate` to the target
+   file URL, then re-read status to confirm the switch took, then write. A bare
+   re-run without navigating will hit the wrong file again.
+
+This is the file-level analogue of the live-instance discipline above: the
+instance preflight guards against *two* live bridges; this guards against the *one*
+live bridge pointing at the *wrong file*. (Observed live: a status probe reported
+the intended file connected, but by write time the active file had drifted to a
+different open document, and the build failed with "collection not found" until a
+`figma_navigate` corrected it.)
+
 ## Read discipline: never report "empty" without a verified read (B1/B2)
 
 Before reporting that a file has no variables, no text styles, or no effect styles,
@@ -276,3 +307,34 @@ const totalBindings = Object.values(tally).reduce((a, b) => a + b, 0);
 - **This is the number `design-system-audit` records** as
   `audit.figmaInventory.bindings`, and the before/after gate the `token-builder`
   brownfield branch runs around every rename.
+
+## Subagent authoring: named working frame + finalize protocol
+
+Figma writes are not git-committable, so a dead executor must never leave a
+corrupted live component. Any subagent authoring a component (`figma-executor`)
+uses **build-verify-then-replace**:
+
+1. **Always build into a distinct working frame** named `WIP: <ComponentName>` —
+   never edit the live component in place.
+2. **Verify the working frame green before touching anything real** — a
+   screenshot alone is **insufficient**: 10 tone-colored frames render
+   identically to 10 real variants, so a fast model can build plain frames and
+   self-report success. The gate is a **programmatic read-back** (`figma_execute`)
+   that asserts `node.type === 'COMPONENT_SET'` (never `'FRAME'`), the child count
+   matches the variant matrix with every child a `'COMPONENT'`,
+   `variantGroupProperties` names the expected axes, and a spot-check of ≥2
+   variants shows fills/strokes/radius bound to variables (not raw values) with
+   the expected `clipsContent`. A `figma_capture_screenshot` is a **secondary**
+   check (create → read-back → screenshot → iterate, max ~3), never the sole one.
+3. **Only then finalize:** remove/replace any existing same-named component,
+   rename the working frame's component set to the real `<ComponentName>`, **and
+   reap leftover artifacts** — search for and remove any stray `WIP:` frames or
+   orphaned fragments (from this or a prior failed run) so the file is left with
+   exactly one finalized component and zero `WIP:` debris.
+4. **On failure / `BLOCKED`:** leave the `WIP:` frame intact and named; the
+   existing real component is **never touched**. A resumed run finds the `WIP:`
+   frame by name and either continues or rebuilds it. A failure therefore leaves
+   an obvious, named, resumable artifact — not a half-built live component.
+
+Concurrency-1 still applies: the whole Figma surface serializes through the one
+bridge, so only one subagent runs this protocol at a time.

package/references/manifest-schema.md

@@ -11,11 +11,11 @@ what changed. Gating decisions are made by reading this file: if a prerequisite
 field is unset, the skill **offers** to run the prerequisite skill rather than
 bailing or running silently.
 
-## Schema (schemaVersion 4)
+## Schema (schemaVersion 5)
 
 ```json
 {
-  "schemaVersion": 4,
+  "schemaVersion": 5,
   "user": {
     "codingLevel": "new"
   },
@@ -87,7 +87,8 @@ bailing or running silently.
     "ranAt": null,
     "codeSurface": null,
     "figmaInventory": null,
-    "percentSemantic": null
+    "percentSemantic": null,
+    "docSurface": null
   },
   "tokenCrosswalk": {
     "path": null,
@@ -249,6 +250,17 @@ bailing or running silently.
   the manifest and the artboard never disagree. Re-running a component refreshes
   its `updatedAt`. Keep `built` (names) as the source of truth for "exists";
   `meta` is supplementary doc metadata.
+- `meta[name].doc` — documentation pointer + per-surface fingerprints for the
+  component (v1: components only). **Pointers and hashes, never content** — the
+  content lives in `design-system/docs/components/<name>.doc.json`. Shape:
+  `{ path, fingerprint, surfaces: { <surfaceName>: { src, render, file? } } }`,
+  where `fingerprint` is the canonical fingerprint at last render, `src` is the
+  canonical fingerprint a surface was rendered from (detects stale), `render` is a
+  hash of the surface's rendered content (detects edits, for re-readable surfaces),
+  and `file` is the repo-relative path of a code surface. Written by
+  `component-builder` (Figma + card surfaces) and `storybook-chromatic-builder`
+  (code surfaces); read by the `docs:check` gate. See
+  `${CLAUDE_PLUGIN_ROOT}/references/component-doc-schema.md`.
 - `instanceSwapUpgradePending` — array of component names whose icon/component
   slots were built with the **toggle + manual-swap fallback** because the
   library wasn't published yet, so the typed `INSTANCE_SWAP` dropdown is still
@@ -292,6 +304,11 @@ system so the retrofit can be right-sized.
   semantic. The single number that decides rename+cleanup vs. rewrite — see
   `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md` (safe sequence, `audit`
   phase) for how it's used.
+- `docSurface` — object sizing the documentation debt for a brownfield retrofit,
+  from verified per-component reads: e.g. `{ "documented": 12, "undocumented": 34,
+  "sources": { "codeJsdoc": 8, "mdx": 4, "figmaDescription": 6, "readme": 3 } }`.
+  `null` until the audit's documentation-sizing pass runs. Counts come from real
+  reads, never assumptions (same discipline as `codeSurface` / `figmaInventory`).
 
 ### `tokenCrosswalk`
 Populated by the `token-crosswalk-builder` skill. Points at the backbone artifact
@@ -307,8 +324,9 @@ that maps new token ↔ old Figma token ↔ code identifier.
 Populated by the `retrofit-planner` orchestrator. Tracks where a multi-phase
 retrofit stands so a later session can resume.
 - `phase` — one of `"audit"`, `"refine"`, `"rebind"`, `"sync"`, `"baseline"`,
-  `"code"`, `"cleanup"`, `"done"`, or `null` (no retrofit in progress). Phases run
-  in that order; see the safe sequence in
+  `"code"`, `"docs"`, `"cleanup"`, `"done"`, or `null` (no retrofit in progress).
+  Phases run in that order; the `docs` phase adopts existing documentation (see
+  `retrofit-planner`). See the safe sequence in
   `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`.
 - `startedAt` / `completedAt` — ISO timestamps bounding the retrofit.
 - `journalScaffolded` — whether the `docs/design-system/` decision journal has been
@@ -339,3 +357,7 @@ retrofit stands so a later session can resume.
 6. **`workspace.origin` is immutable after intake.** Written once by
    `figma-environment-setup` Step 0 and must not be overwritten by any downstream
    skill. Skills read it to adapt behavior — they do not modify it.
+
+**v4 → v5 migration:** add `audit.docSurface` (default `null`) and the `docs`
+retrofit phase; `components.meta[name].doc` is added lazily per component as docs
+are authored. Bump `schemaVersion` to `5`. No existing field changes.

package/references/sync-adapters.md

@@ -139,3 +139,8 @@ each platform's output is independent and verifiable, which makes it a good fit
 for **parallel subagent generation** — one subagent per adapter, each producing
 and validating its platform's files, reviewed before the combined result is
 landed in a PR. See the token-sync skill for the execution model.
+
+Token-adapter generation parallelizes because each adapter writes independent
+files. Figma authoring does **not**: the single figma-console bridge is
+concurrency-1, so Figma work uses sequential subagents — model routing yes,
+parallel never (see `${CLAUDE_PLUGIN_ROOT}/references/agent-routing.md`).

package/scripts/README.md

@@ -12,6 +12,8 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `guard-token-removal.mjs` | Grep `.ts/.tsx` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
 | `lib/crosswalk.mjs` | Shared loader + structural validation for `crosswalk.json` (used by the validator and reverse-index). | copied alongside |
 | `crosswalk.schema.json` | The finalized JSON Schema for `crosswalk.json` (contract + editor support). | copied beside `crosswalk.json` |
+| `build-docs-digest.mjs` | Aggregate every `design-system/docs/components/*.doc.json` into `design-system/docs/index.json` + `llms.txt` for AI/human consumers. | `docs:digest` |
+| `docs-check.mjs` | Drift gate — verifies each component's doc surfaces still match its canonical record (via `lib/doc-record.mjs` fingerprints). Exits 1 on drift. | `docs:check` |
 
 The crosswalk contract is documented in
 `${CLAUDE_PLUGIN_ROOT}/references/crosswalk-schema.md`.
@@ -76,3 +78,12 @@ rewriting `${CLAUDE_PLUGIN_ROOT}` → `.throughline`:
     npx @radicool/throughline init --target=cursor|codex|generic
 
 See `scripts/install.mjs` (pure core + CLI + `install.test.mjs`).
+
+## Documentation scripts
+
+`docs:digest` and `docs:check` operate on the folder-resident documentation store
+at `design-system/docs/`. Both share `lib/doc-record.mjs` (record loading +
+fingerprinting). `docs:check` re-reads repo surfaces (Storybook MDX); Figma
+surfaces are marked `edit-unverified` and are checked live by the Figma-connected
+skills. See `${CLAUDE_PLUGIN_ROOT}/references/component-doc-schema.md` for the
+record schema and fingerprint contract.