@radicool/throughline 0.12.1 → 0.14.0

package/README.md

@@ -51,7 +51,7 @@ Most teams aren't starting from a blank file — they have a mature codebase wit
 
 1. **Audit before anything changes.** `design-system-audit` sizes both sides of your system — it greps your codebase to measure the real color surface and inventories your Figma file with verified, per-class reads — then tells you how big the migration actually is and how semantic your system already is.
 2. **A crosswalk that guarantees nothing shifts.** `token-crosswalk-builder` maps every new token to its old Figma variable and old code value, then installs a `tokens:validate` gate that fails unless every resolved new value matches the old one (N/N). A zero-reference guard blocks removing an old token while any code still references it.
-3. **A gated, reversible migration.** `retrofit-planner` walks the safe seven-phase sequence — audit → refine variables in place → rebind → sync → capture a visual baseline → retrofit the code → remove the old tokens — pausing for your confirmation between every phase, with an optional decision journal recording each call.
+3. **A gated, reversible migration.** `retrofit-planner` walks the safe seven-phase sequence — audit → refine variables in place → rebind → sync → capture a visual baseline → retrofit the code → adopt existing docs → remove the old tokens — pausing for your confirmation between every phase, with an optional decision journal recording each call.
 
 The payoff: your live product looks identical at every step, and you can prove it with a Chromatic baseline captured before the first change.
 
@@ -154,7 +154,7 @@ For the technically curious — how the machine actually runs.
 
 **Modes, within Figma's limits.** Light/Dark lives on the semantic collections; brand variants live on the primitive palette. Splitting the two axes across two collections keeps each one under Figma's 4-modes-per-collection cap on the Professional plan while still resolving correctly (`bg/default` → `{gray/50}` → the active brand's gray).
 
-**Model routing.** Setup runs on **Haiku** automatically to keep first-run costs low. Everyday work runs on whatever model your session is set to — **Sonnet** is a sensible default. For the heaviest authoring (large token systems, intricate variant matrices), **Opus** gives the best results: `/model opus`, then back to `/model sonnet`. Nothing forces an expensive model on you.
+**Model routing.** ThroughLine routes work by *cognition, not guesswork* — the expensive thinking on the best model, the mechanical doing on a cheap one. Setup runs on **Haiku** automatically to keep first-run costs low. Inside a skill, the deciding — a token architecture, a variant matrix, a slot contract — is planned once on the strongest tier, while the long mechanical part — placing Figma nodes, transcribing component code, running SVGR — runs on a cheap tier and self-verifies. You get the best model where it matters and a cheap one where it doesn't, without micromanaging it. The recommended mapping is **Haiku → Sonnet → Opus** for the `fast < balanced < deep` tiers, but nothing is hardcoded — the ladder resolves against whatever models your install actually has, and on hosts without subagents skills degrade cleanly to a single model. You can still steer the session yourself (`/model opus` for the heaviest authoring, back to `/model sonnet` after); nothing forces an expensive model on you.
 
 ## Who it's for
 

package/adapters/codex/AGENTS.md

@@ -10,7 +10,7 @@ ThroughLine builds a design system end to end. Load the matching prompt for the
 - `figma-environment-setup` — Set up the local working folder and connect Codex to Figma so the design-system skills can read and write variables, styles, and components. → load `prompts/figma-environment-setup.md`.
 - `icon-system-builder` — Build an icon system in Figma — a dedicated "Icons" page populated with the user's chosen icon library (Lucide, Material, or custom SVGs) as well-named, scalable components — using the fastest, most-automated mechanism per library (for Lucide, batch-fetching the curated subset's official SVGs from the source repo and componentizing them hands-off; for Material, the official community file or importer plugin) rather than hand-generating icons or making the user copy components by hand. → load `prompts/icon-system-builder.md`.
 - `repository-builder` — Graduate the local design-system folder into a real monorepo — a pnpm + Turborepo workspace with packages for tokens and UI components and room for apps — and walk the user from a plain folder to local git to a GitHub remote with PRs and CI. → load `prompts/repository-builder.md`.
-- `retrofit-planner` — Orchestrate a full brownfield design-system retrofit end to end — audit, refine variables in place, rebind components, sync, capture a Chromatic baseline, retrofit the code with dual output, then remove the old tokens only after a zero-reference grep — with a human confirmation gate between every phase. → load `prompts/retrofit-planner.md`.
+- `retrofit-planner` — Orchestrate a full brownfield design-system retrofit end to end — audit, refine variables in place, rebind components, sync, capture a Chromatic baseline, retrofit the code with dual output, adopt existing documentation then fill gaps, then remove the old tokens only after a zero-reference grep — with a human confirmation gate between every phase. → load `prompts/retrofit-planner.md`.
 - `storybook-chromatic-builder` — Stand up Storybook in the monorepo, build code components matching the Figma design system (consuming the synced tokens and implementing the captured slot contracts), generate stories for every component, set up Chromatic for visual regression testing, and wire Code Connect when the user's Figma plan supports it. → load `prompts/storybook-chromatic-builder.md`.
 - `token-builder` — Build a two-tier (primitive + semantic) design token system as Figma variables — color ramps, spacing, type scale, radius, shadows — with light/dark or brand modes. → load `prompts/token-builder.md`.
 - `token-crosswalk-builder` — Build the brownfield token crosswalk — a persistent three-way map between each new token, the old Figma variable, and the old code identifier(s) — as crosswalk.json, then install the vetted validator/reverse-index scripts into the monorepo and wire the tokens:validate CI gate. → load `prompts/token-crosswalk-builder.md`.
@@ -20,6 +20,7 @@ ThroughLine builds a design system end to end. Load the matching prompt for the
 ## ThroughLine commands
 
 - `design-system-status` — Show a plain-language summary of the current design system state — what's set up, what's not, and sensible next steps — read from design-system.json. → load `prompts/design-system-status.md`.
+- `document-component` — Author, refresh, or reconcile the usage documentation for one existing component — draft its canonical doc record from four sources, project it to Figma, the doc card, and code, and resolve any drift via a reviewable per-item choice. → load `prompts/document-component.md`.
 - `new-component` — Build a single new component end to end — in Figma, then sync any new tokens, then build its code component and stories — with a confirmation between each stage. → load `prompts/new-component.md`.
 - `start` — Start building your design system — the deterministic entry point. → load `prompts/start.md`.
 - `sync-figma-tokens` — Re-run the Figma-to-code token sync — extract current Figma variables, rebuild code outputs via Style Dictionary, and open a PR with the changes for review. → load `prompts/sync-figma-tokens.md`.

package/adapters/codex/prompts/component-builder.md

@@ -88,8 +88,23 @@ of the primitive→semantic token seam:
    slot the atoms.
 
 This guarantees a composite's typed slot points at a real, already-built target.
-Build bottom-up; checkpoint after each component (sequential — this is Figma
-authoring, no subagents).
+Build bottom-up in dependency order.
+
+**Execution model — sequential subagents with model routing.** If your host
+supports subagent dispatch, plan the whole set once with one **architect**
+dispatch (deep tier) — it reads existing Figma state and emits a
+transcription-grade spec in stable identifiers — then build **each component**
+with one **figma-executor** dispatch (fast→balanced), strictly sequentially:
+preflight `figma_get_status` and never run two Figma-touching subagents at once
+(the single bridge is concurrency-1). Each executor builds into a `WIP:` frame
+and finalizes by build-verify-then-replace (see
+`.throughline/references/figma-scripting.md`); gate each finished
+component with a **reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its slice of the spec is complete enough to transcribe. **Keep the
+human checkpoint between components** — subagents run continuously within a
+component, but you pause for the human between them. If your host has no subagent
+dispatch, build and verify each component inline, sequentially, as before.
 
 ## Step 3 — Build each component, bound to tokens/styles
 
@@ -212,6 +227,66 @@ Two rules for every slot:
 Record each component's slots, variant matrix, and token bindings in the
 component spec (for Code Connect when available, else the repo component spec).
 
+## Step 4.5 — Author the documentation record (and project it)
+
+Every component gets a canonical documentation record — the source of truth for
+its usage docs — written to the working folder next to `design-system.json`
+(**folder-resident from day one**, exactly like the manifest; no repo required).
+Read `.throughline/references/component-doc-schema.md` for the exact JSON
+schema, the fingerprint algorithm, and the projection contract.
+
+**Run the generation pipeline (each layer only fills what it legitimately knows;
+stamp `provenance` per block):**
+
+0. **Ingest existing docs — brownfield only, runs first.** If docs already exist
+   for this component (code JSDoc/MDX/README, or a populated Figma component
+   `description`), read them and seed the record marked `provenance: imported`.
+   **Never silently overwrite existing human-written docs** — this is the
+   read-before-you-assert rule. Skip on greenfield.
+1. **Infer from the built artifact.** From the component you just built — its
+   variants, states, slots, and bound tokens — author `description`, `variants`,
+   `states`, and `tokensUsed` (`tokensUsed` comes from the real variable bindings,
+   not a guess). Provenance `ai-inferred`.
+2. **Enrich from the archetype knowledge base.** Match the component to the nearest
+   archetype in `.throughline/references/component-doc-archetypes.md` and
+   seed `dos`, `donts`, `accessibility`, `whenToUse`, `whenNotToUse`. Provenance
+   `best-practice` (or `w3c-apg` for the accessibility block).
+3. **Specialize to `project.uiFramework`.** Align variant-meaning wording and the
+   accessibility idiom to the target framework (the same field you read for variant
+   vocabulary). Provenance `framework`.
+4. **Interview for the non-inferable.** Ask the user for brand/product-specific
+   do's & don'ts and intent. Provenance `user`. **Show the whole drafted record and
+   get explicit approval before writing anything** — layers 1–4 only fill blocks the
+   ingest step did not, and an `imported`/`user` block is never overwritten.
+
+**Write the record and project it:**
+
+- Write `design-system/docs/components/<Name>.doc.json` (JSON; required fields
+  `name`, `summary`, `description`).
+- **Figma component description.** Set the component's native `description` field
+  (via `figma_set_description`) to a compact markdown rendering — summary,
+  when-to-use/not, do's/don'ts, and the a11y summary — and append a fingerprint
+  marker line `<!-- tl:doc <fp> -->` (this is the surface Dev Mode and Code Connect
+  read).
+- **Doc card body.** Extend the existing doc card (name/short-desc/status/date, per
+  `.throughline/references/figma-component-standards.md`) with a usage body:
+  when-to-use, do's/don'ts, an a11y line, and a variant/state legend — all
+  token-bound (no hardcoded hex/px). Add a metadata text node named
+  `Doc Fingerprint` holding `<fp>`.
+- Compute `<fp>` as the canonical fingerprint defined in the schema reference
+  (sha256 of the projected record without `provenance`, first 16 hex chars).
+
+**Update the manifest (fields this skill owns):** set
+`components.meta[<Name>].doc` to `{ path, fingerprint: <fp>, surfaces: {
+figmaDescription: { src: <fp>, render: <hash of the description text> }, docCard: {
+src: <fp>, render: <hash of the card body content> } } }`. The code surfaces
+(`storybookMdx`) are added later by `storybook-chromatic-builder`.
+
+Run the standard doc-card visual-validation + post-build audit
+(`.throughline/references/figma-component-standards.md`) after enriching
+the card. `docs:check` runs at the code stage; at folder stage the record + Figma
+surfaces are the fallback.
+
 ## Step 5 — Naming as contract
 
 Name components deterministically so Figma↔code mapping is automatic: `Button` ↔
@@ -269,4 +344,7 @@ Offer next steps: build the code counterparts and stories
   internal architecture) **detaches every instance** that referenced its variants (the
   Card's footer buttons, etc.). Record which components consume which, warn before an
   architectural rebuild, and re-instance the affected consumers afterward.
+- Never overwrite an existing component `description` or imported doc content
+  without reading it first and marking it `provenance: imported` — brownfield docs
+  are seeds, not blank slates.
 

package/adapters/codex/prompts/design-system-audit.md

@@ -56,6 +56,23 @@ counts:
 repo with no Tailwind simply scores `0` there. Detect what the repo actually uses (is
 there a `tailwind.config`? SCSS? CSS-in-JS?) and explain the counts in those terms.
 
+## Step 1.5 — Size the documentation surface
+
+Inventory existing documentation the same way the code surface is sized — from
+**verified reads, never assumptions**. Per component (or per code component when no
+Figma component exists yet), record whether usage docs already exist and where:
+
+- **Code:** JSDoc/TSDoc on the component, an `.mdx` doc page, a per-component
+  README.
+- **Figma:** a populated component `description` field.
+
+Write the totals to `audit.docSurface` in the manifest, e.g. `{ "documented": 12,
+"undocumented": 34, "sources": { "codeJsdoc": 8, "mdx": 4, "figmaDescription": 6,
+"readme": 3 } }`. This right-sizes the documentation retrofit (how much exists to
+adopt vs. author from scratch) so `retrofit-planner`'s `docs` phase can be planned
+against real numbers. See `.throughline/references/component-doc-schema.md`
+for what a full record contains.
+
 ## Step 2 — Inventory the Figma file (verified per-class reads)
 
 Variables, text styles, and effect/paint styles are **different surfaces** — read each
@@ -103,6 +120,9 @@ Set `tokens.intakeMode: "retrofit"` (this skill establishes the brownfield path
 owns this transition). Append `design-system-audit` to `completedSkills`.
 
 Then recommend the next step:
+- Report the documentation debt from `audit.docSurface` (documented vs.
+  undocumented) and note that the retrofit's `docs` phase will adopt existing docs
+  before authoring the gaps.
 - If the user wants the guided, gated end-to-end retrofit → **`retrofit-planner`**
   (the orchestrator; recommended for multi-session retrofits).
 - If they only want the crosswalk backbone next → **`token-crosswalk-builder`** (it

package/adapters/codex/prompts/document-component.md

@@ -0,0 +1,26 @@
+Document a single existing component end to end, using the settings already in
+`design-system.json` (`project.uiFramework`, `figma.mechanism`, `sync.platforms`)
+rather than re-asking configuration. Scale explanation to `user.codingLevel`.
+
+Ask which component to document (e.g. "Button"), then:
+
+1. **Author/refresh the record.** Run the doc-authoring pipeline from
+   the `component-builder` prompt's *Author the documentation record* step —
+   ingest any existing docs first (brownfield), then infer → enrich (from
+   `.throughline/references/component-doc-archetypes.md`) → specialize →
+   interview. The user approves the drafted record; `imported`/`user` blocks are
+   never overwritten.
+2. **Project it.** Write `design-system/docs/components/<Name>.doc.json`, set the
+   Figma component `description`, enrich the doc card, and (if the repo/code side
+   exists) render MDX/JSDoc and run `docs:digest` per the
+   `storybook-chromatic-builder` render step.
+3. **Reconcile drift.** Run `docs:check`. For each drifted surface, offer a per-item
+   choice — **re-render** (canonical wins) or **pull-back** (fold the surface edit
+   into the record) — and land the result as a reviewable change. On a brownfield
+   component's first pass, adopt existing content (`provenance: imported`) rather
+   than overwriting it.
+
+See `.throughline/references/component-doc-schema.md` for the record schema,
+fingerprint contract, and projection mapping. If a component was never built in
+Figma, point the user at `component-builder` first.
+

package/adapters/codex/prompts/icon-system-builder.md

@@ -169,8 +169,16 @@ Execute the library's mechanism:
   install/run and subset selection.
 - **Custom SVGs:** batch-import and componentize them.
 
-This is a Figma-authoring step — sequential, with the user in the loop; no
-subagents. When scripting the SVG-to-component pass, follow
+**Execution model — sequential Figma-lane subagent with model routing.** If your
+host supports subagent dispatch, run the bring-in + componentize pass as a
+**`figma-executor`** dispatch (balanced tier): preflight `figma_get_status`,
+never run two Figma-touching subagents at once (the single bridge is
+concurrency-1), build into a `WIP:` frame and finalize by build-verify-then-
+replace with the read-back audit in Step 3. The subset + naming contract were
+already settled with the user in Step 1, so no separate architect dispatch is
+needed here. Route per `.throughline/references/agent-routing.md`. If
+your host has no subagent dispatch, script the SVG-to-component pass inline,
+sequentially, with the user in the loop. Either way, follow
 `.throughline/references/figma-scripting.md`.
 
 ## Step 3 — Normalize: page, naming, sizing, variants

package/adapters/codex/prompts/repository-builder.md

@@ -106,6 +106,20 @@ in it" — they already have a working local repo.
 On success, set `workspace.stage` and `repo.stage` to `github` and record
 `repo.remote`. Append `repository-builder` to `completedSkills`.
 
+### Adopt the documentation store
+
+The folder-resident documentation store at `design-system/docs/` (canonical
+`*.doc.json` records plus the generated `index.json` + `llms.txt`) already exists
+from the Figma phase. Bring it under version control as-is — **do not relocate it**
+(the path is stable across folder→repo, and every manifest `doc.path` points at it).
+Ensure it is committed (not git-ignored).
+
+Wire the documentation drift gate into the repo's verification so it runs in CI
+alongside `tokens:validate`: add a `docs:check` step (the `docs-check.mjs` script is
+installed by `storybook-chromatic-builder`; if code hasn't been set up yet, note
+that the gate comes online with the Storybook step). `docs:check` exits non-zero on
+drift; Figma surfaces report `edit-unverified` and are checked in a Figma session.
+
 ## Secrets: the part most people have never done
 
 This is where users with low coding experience get stuck — many have never made

package/adapters/codex/prompts/retrofit-planner.md

@@ -1,6 +1,7 @@
 # Retrofit planner (orchestrator)
 
-Sequences a brownfield retrofit through the safe 7-phase order, gating each phase on a
+Sequences a brownfield retrofit through the safe seven-phase order (with `docs` inserted
+as a gated Phase 6.5), gating each phase on a
 human confirmation. Like `component-pipeline`, this skill holds **zero domain logic of
 its own** — it is a sequencer that invokes the real skills and the phase work, and only
 updates the manifest fields it owns (`retrofit.*`, `completedSkills`). All the
@@ -102,6 +103,25 @@ triad as you go — `check-types`, `build-storybook` + Chromatic, **and run the
 + spot-check 5–7 routes (the build alone is blind to story-unreachable SCSS). **Gate:**
 confirm the triad passes before continuing.
 
+### Phase 6.5 — `docs` (adopt existing documentation, then fill gaps)
+
+Set `retrofit.phase = "docs"`. Bring the documentation layer onto the system's
+components **adopt-first**, so no existing human-written doc is lost:
+
+1. **Adopt.** For each component, run the doc-authoring ingest (Step 4.5 of
+   `component-builder`): read existing code JSDoc/MDX/README and Figma
+   `description`, seed the canonical `.doc.json` marked `provenance: imported`, and
+   stamp fingerprints. This first pass **claims** existing content — it is not a
+   re-render and must not overwrite it.
+2. **Fill gaps.** Run the remaining generation layers (infer → enrich → specialize
+   → interview) only for blocks the adoption did not populate; the user approves.
+3. **Project + gate.** Render the code surfaces (Step 5.5 of
+   `storybook-chromatic-builder`), run `docs:digest`, and run `docs:check` — it
+   should pass (surfaces just rendered) with Figma surfaces `edit-unverified`.
+
+Confirm with the user before writing, consistent with every other phase. On a large
+system, size the batch from `audit.docSurface` and adopt in reviewable chunks.
+
 ### Phase 7 — `cleanup`
 
 Remove the old token outputs **only after** the repo-wide token-removal guard returns

package/adapters/codex/prompts/storybook-chromatic-builder.md

@@ -27,6 +27,16 @@ system). Wire it to consume `packages/tokens` output so stories render with the
 real design tokens (import the generated CSS/theme). Checkpoint: confirm
 Storybook runs and shows the token-themed canvas.
 
+Install the documentation scripts alongside the token scripts (copy from the
+plugin's `scripts/` — `build-docs-digest.mjs`, `docs-check.mjs`, and
+`lib/doc-record.mjs` — into the repo and register npm scripts):
+
+- `"docs:digest": "node scripts/build-docs-digest.mjs"`
+- `"docs:check": "node scripts/docs-check.mjs"`
+
+These are the documentation analog of `tokens:validate`; see
+`.throughline/scripts/README.md`.
+
 **pnpm build-script allowlist (first-run gotcha).** On pnpm workspaces, the
 `@storybook/react-vite` install pulls `esbuild`, whose postinstall is blocked by
 pnpm's default `onlyBuiltDependencies` policy — Storybook then fails to start with a
@@ -67,13 +77,19 @@ Match the deterministic naming so `Button` (Figma) ↔ `Button` (code).
 
 ## Step 3 — Generate stories (subagent-driven, parallel)
 
-Story generation is independent and verifiable per component, so use the
-**subagent-driven model** (code-gen skills parallelize; this is the opposite of
-the sequential Figma-authoring skills): dispatch one subagent per component to
-write its stories — a story per meaningful variant, controls wired to props,
-slot props demonstrated. Each subagent verifies its work (the story builds and
-renders). Two-stage review (does it match the component spec; is it quality
-code) before combining.
+Story generation is independent and verifiable per component, so it
+parallelizes — one worker per component, unlike the concurrency-1 Figma lane.
+
+**Execution model — parallel subagents with model routing.** If your host
+supports subagent dispatch, dispatch **one `code-executor` per component** (fast
+tier) to write its stories — a story per meaningful variant, controls wired to
+props, slot props demonstrated — each verifying its own work (the story builds
+and renders); then a **`reviewer`** (balanced) two-stage pass (does it match the
+component spec; is it quality code) before combining. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its story spec is complete enough to transcribe. If your host has
+no subagent dispatch, generate and verify each component's stories inline
+instead.
 
 **Controls must actually drive the component (args-through render).** A `render`
 that ignores its args silently breaks the Controls panel — the toggle writes to
@@ -164,6 +180,32 @@ mode shows the real code. It's plan-gated (Figma Organization/Enterprise).
   run after the user publishes. This does **not** block the code side: implement
   each slot prop from the recorded slot contract regardless of the Figma dropdown.
 
+## Step 5.5 — Render documentation to code
+
+For each component that has a canonical record
+(`design-system/docs/components/<Name>.doc.json`), render the code-side surfaces
+from it (read `.throughline/references/component-doc-schema.md` for the
+projection contract):
+
+- **Storybook autodocs (MDX).** Generate `<Name>.mdx` next to the component (e.g.
+  `packages/ui/src/<Name>/<Name>.mdx`) rendering summary, description,
+  when-to-use/not, do's/don'ts, accessibility, and a variant/state table. Put the
+  record's fingerprint in MDX frontmatter as `docFingerprint: <fp>`.
+- **JSDoc.** Add a doc comment to the code component from `summary` + `description`
+  and per-prop descriptions from `variants`/`states` meanings, so `argTypes`
+  descriptions surface in the Storybook controls table.
+- **AI digest.** Run `docs:digest` to (re)generate `design-system/docs/index.json`
+  + `design-system/docs/llms.txt` from all records.
+
+**Update the manifest:** add the `storybookMdx` surface to
+`components.meta[<Name>].doc.surfaces` as `{ src: <fp>, render: <hash of the MDX
+file>, file: "<repo-relative MDX path>" }`.
+
+**Wire the gate.** Ensure `docs:check` is part of the repo's verification (a CI
+step and/or a Turbo task). It compares every surface against its record and exits
+non-zero on drift; Figma surfaces report `edit-unverified` (checked live in a Figma
+session). Run `docs:check` once here and confirm it passes before handing off.
+
 ## Step 6 — Finalize component status (Figma write-back)
 
 A component built and storied here is now **done** — but its Figma doc card was
@@ -187,6 +229,9 @@ the `figma_execute` scripting gotchas — `getNodeByIdAsync` and an explicit
 
 - Set `components.meta[name].status` = `"stable"` and refresh
   `components.meta[name].updatedAt` to today.
+- When promoting status (e.g. draft → stable), also set `status` + `updatedAt` in
+  the component's `.doc.json`, recompute its fingerprint, re-run `docs:digest`, and
+  re-render the affected surfaces so `docs:check` stays green.
 - If Figma is connected (per `figma.mechanism`), open the component's doc card and
   update the `Status Label` text to `stable`, re-bind the `Status` chip fill to
   the **success** semantic color variable (mode-aware, not a hardcoded hex), and

package/adapters/codex/prompts/token-builder.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/codex/prompts/token-sheet-builder.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/codex/prompts/token-sync-layer.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/adapters/cursor/.cursor/commands/document-component.md

@@ -0,0 +1,26 @@
+Document a single existing component end to end, using the settings already in
+`design-system.json` (`project.uiFramework`, `figma.mechanism`, `sync.platforms`)
+rather than re-asking configuration. Scale explanation to `user.codingLevel`.
+
+Ask which component to document (e.g. "Button"), then:
+
+1. **Author/refresh the record.** Run the doc-authoring pipeline from
+   the `component-builder` rule's *Author the documentation record* step —
+   ingest any existing docs first (brownfield), then infer → enrich (from
+   `.throughline/references/component-doc-archetypes.md`) → specialize →
+   interview. The user approves the drafted record; `imported`/`user` blocks are
+   never overwritten.
+2. **Project it.** Write `design-system/docs/components/<Name>.doc.json`, set the
+   Figma component `description`, enrich the doc card, and (if the repo/code side
+   exists) render MDX/JSDoc and run `docs:digest` per the
+   `storybook-chromatic-builder` render step.
+3. **Reconcile drift.** Run `docs:check`. For each drifted surface, offer a per-item
+   choice — **re-render** (canonical wins) or **pull-back** (fold the surface edit
+   into the record) — and land the result as a reviewable change. On a brownfield
+   component's first pass, adopt existing content (`provenance: imported`) rather
+   than overwriting it.
+
+See `.throughline/references/component-doc-schema.md` for the record schema,
+fingerprint contract, and projection mapping. If a component was never built in
+Figma, point the user at `component-builder` first.
+

package/adapters/cursor/.cursor/rules/component-builder.mdc

@@ -92,8 +92,23 @@ of the primitive→semantic token seam:
    slot the atoms.
 
 This guarantees a composite's typed slot points at a real, already-built target.
-Build bottom-up; checkpoint after each component (sequential — this is Figma
-authoring, no subagents).
+Build bottom-up in dependency order.
+
+**Execution model — sequential subagents with model routing.** If your host
+supports subagent dispatch, plan the whole set once with one **architect**
+dispatch (deep tier) — it reads existing Figma state and emits a
+transcription-grade spec in stable identifiers — then build **each component**
+with one **figma-executor** dispatch (fast→balanced), strictly sequentially:
+preflight `figma_get_status` and never run two Figma-touching subagents at once
+(the single bridge is concurrency-1). Each executor builds into a `WIP:` frame
+and finalizes by build-verify-then-replace (see
+`.throughline/references/figma-scripting.md`); gate each finished
+component with a **reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its slice of the spec is complete enough to transcribe. **Keep the
+human checkpoint between components** — subagents run continuously within a
+component, but you pause for the human between them. If your host has no subagent
+dispatch, build and verify each component inline, sequentially, as before.
 
 ## Step 3 — Build each component, bound to tokens/styles
 
@@ -216,6 +231,66 @@ Two rules for every slot:
 Record each component's slots, variant matrix, and token bindings in the
 component spec (for Code Connect when available, else the repo component spec).
 
+## Step 4.5 — Author the documentation record (and project it)
+
+Every component gets a canonical documentation record — the source of truth for
+its usage docs — written to the working folder next to `design-system.json`
+(**folder-resident from day one**, exactly like the manifest; no repo required).
+Read `.throughline/references/component-doc-schema.md` for the exact JSON
+schema, the fingerprint algorithm, and the projection contract.
+
+**Run the generation pipeline (each layer only fills what it legitimately knows;
+stamp `provenance` per block):**
+
+0. **Ingest existing docs — brownfield only, runs first.** If docs already exist
+   for this component (code JSDoc/MDX/README, or a populated Figma component
+   `description`), read them and seed the record marked `provenance: imported`.
+   **Never silently overwrite existing human-written docs** — this is the
+   read-before-you-assert rule. Skip on greenfield.
+1. **Infer from the built artifact.** From the component you just built — its
+   variants, states, slots, and bound tokens — author `description`, `variants`,
+   `states`, and `tokensUsed` (`tokensUsed` comes from the real variable bindings,
+   not a guess). Provenance `ai-inferred`.
+2. **Enrich from the archetype knowledge base.** Match the component to the nearest
+   archetype in `.throughline/references/component-doc-archetypes.md` and
+   seed `dos`, `donts`, `accessibility`, `whenToUse`, `whenNotToUse`. Provenance
+   `best-practice` (or `w3c-apg` for the accessibility block).
+3. **Specialize to `project.uiFramework`.** Align variant-meaning wording and the
+   accessibility idiom to the target framework (the same field you read for variant
+   vocabulary). Provenance `framework`.
+4. **Interview for the non-inferable.** Ask the user for brand/product-specific
+   do's & don'ts and intent. Provenance `user`. **Show the whole drafted record and
+   get explicit approval before writing anything** — layers 1–4 only fill blocks the
+   ingest step did not, and an `imported`/`user` block is never overwritten.
+
+**Write the record and project it:**
+
+- Write `design-system/docs/components/<Name>.doc.json` (JSON; required fields
+  `name`, `summary`, `description`).
+- **Figma component description.** Set the component's native `description` field
+  (via `figma_set_description`) to a compact markdown rendering — summary,
+  when-to-use/not, do's/don'ts, and the a11y summary — and append a fingerprint
+  marker line `<!-- tl:doc <fp> -->` (this is the surface Dev Mode and Code Connect
+  read).
+- **Doc card body.** Extend the existing doc card (name/short-desc/status/date, per
+  `.throughline/references/figma-component-standards.md`) with a usage body:
+  when-to-use, do's/don'ts, an a11y line, and a variant/state legend — all
+  token-bound (no hardcoded hex/px). Add a metadata text node named
+  `Doc Fingerprint` holding `<fp>`.
+- Compute `<fp>` as the canonical fingerprint defined in the schema reference
+  (sha256 of the projected record without `provenance`, first 16 hex chars).
+
+**Update the manifest (fields this skill owns):** set
+`components.meta[<Name>].doc` to `{ path, fingerprint: <fp>, surfaces: {
+figmaDescription: { src: <fp>, render: <hash of the description text> }, docCard: {
+src: <fp>, render: <hash of the card body content> } } }`. The code surfaces
+(`storybookMdx`) are added later by `storybook-chromatic-builder`.
+
+Run the standard doc-card visual-validation + post-build audit
+(`.throughline/references/figma-component-standards.md`) after enriching
+the card. `docs:check` runs at the code stage; at folder stage the record + Figma
+surfaces are the fallback.
+
 ## Step 5 — Naming as contract
 
 Name components deterministically so Figma↔code mapping is automatic: `Button` ↔
@@ -273,4 +348,7 @@ Offer next steps: build the code counterparts and stories
   internal architecture) **detaches every instance** that referenced its variants (the
   Card's footer buttons, etc.). Record which components consume which, warn before an
   architectural rebuild, and re-instance the affected consumers afterward.
+- Never overwrite an existing component `description` or imported doc content
+  without reading it first and marking it `provenance: imported` — brownfield docs
+  are seeds, not blank slates.
 

package/adapters/cursor/.cursor/rules/design-system-audit.mdc

@@ -60,6 +60,23 @@ counts:
 repo with no Tailwind simply scores `0` there. Detect what the repo actually uses (is
 there a `tailwind.config`? SCSS? CSS-in-JS?) and explain the counts in those terms.
 
+## Step 1.5 — Size the documentation surface
+
+Inventory existing documentation the same way the code surface is sized — from
+**verified reads, never assumptions**. Per component (or per code component when no
+Figma component exists yet), record whether usage docs already exist and where:
+
+- **Code:** JSDoc/TSDoc on the component, an `.mdx` doc page, a per-component
+  README.
+- **Figma:** a populated component `description` field.
+
+Write the totals to `audit.docSurface` in the manifest, e.g. `{ "documented": 12,
+"undocumented": 34, "sources": { "codeJsdoc": 8, "mdx": 4, "figmaDescription": 6,
+"readme": 3 } }`. This right-sizes the documentation retrofit (how much exists to
+adopt vs. author from scratch) so `retrofit-planner`'s `docs` phase can be planned
+against real numbers. See `.throughline/references/component-doc-schema.md`
+for what a full record contains.
+
 ## Step 2 — Inventory the Figma file (verified per-class reads)
 
 Variables, text styles, and effect/paint styles are **different surfaces** — read each
@@ -107,6 +124,9 @@ Set `tokens.intakeMode: "retrofit"` (this skill establishes the brownfield path
 owns this transition). Append `design-system-audit` to `completedSkills`.
 
 Then recommend the next step:
+- Report the documentation debt from `audit.docSurface` (documented vs.
+  undocumented) and note that the retrofit's `docs` phase will adopt existing docs
+  before authoring the gaps.
 - If the user wants the guided, gated end-to-end retrofit → **`retrofit-planner`**
   (the orchestrator; recommended for multi-session retrofits).
 - If they only want the crosswalk backbone next → **`token-crosswalk-builder`** (it