@radicool/throughline 0.14.0 → 0.15.0

package/references/doc-writing-standard.md

@@ -0,0 +1,144 @@
+# Doc-writing standard
+
+The writing standard for all doc-record (`.doc.json`) content. Applied by the
+authoring pipeline in `component-builder` and `/document-component`. Every
+projection — Figma component description, doc card, Storybook MDX, AI digest —
+inherits this text unchanged; none of them are written separately.
+
+**Governing rule: describe the thing and how to use it, never how it was
+made.**
+
+## Register
+
+Plain reference: neutral and declarative for descriptions, imperative for
+guidance — the register Polaris and Carbon use.
+
+This is **not** the conversational guide voice of `references/guide-voice.md`.
+Guide voice is for skill conversation — a guide talking to the person building
+the system. This standard is for doc-record content — what gets written about
+the component itself, read by whoever uses it later. Different audience,
+different register; do not blend them.
+
+## Per-block rules
+
+Before/after pairs are the real Button record
+(`throughline-sample/design-system/docs/components/Button.doc.json`).
+
+### `description`
+
+2–3 sentences: what it is, what it's for, and the one thing that most changes
+how you use it. Never variant/size counts (the specimen and legend already show
+them), never token binding, never a slot inventory.
+
+> **Before:** "A clickable control that triggers an action — submitting a
+> form, confirming a decision, or opening a dialog. It comes in six emphasis
+> variants across three sizes, supports optional leading and trailing icons
+> and a loading state, and binds every color, spacing, radius, and type value
+> to the system's semantic tokens."
+>
+> **After:** "A clickable control that starts an action: saving a form,
+> confirming a choice, opening a dialog. Its emphasis levels signal how
+> important an action is."
+
+### `whenToUse` / `whenNotToUse`
+
+Situations, never an echo of `summary`. `whenNotToUse` always names the
+alternative.
+
+> **Before:** summary "Triggers an action or event." → whenToUse[0] "Trigger
+> an action or event — submit, confirm, open a dialog"
+>
+> **After:** "Something happens on the current page — save, confirm, open a
+> dialog"
+
+### `variants` / `states`
+
+Lead with meaning; visual treatment is optional and never the whole entry.
+
+> **Before:** "Highest-emphasis, solid brand fill — the one primary action in
+> a view." → **After:** "The one main action in a view."
+>
+> **Before:** "Non-interactive and not focusable; reduced opacity." →
+> **After:** "Can't be clicked or tabbed to."
+
+### `dos` / `donts`
+
+Imperative, one action per entry, ≤ 14 words, full stop. Don'ts open with
+*Don't / Never / Avoid* and name the alternative.
+
+> **Before:** "Don't use a button for navigation — use a Link" →
+> **After:** "Don't use a button to navigate. Use a Link."
+
+### `accessibility.notes`
+
+What the reader must do, not what the framework emits.
+
+> **Cut:** "Renders a native `<button>`, so `role=\"button\"` is implicit."
+>
+> **Before:** "An icon-only button needs an aria-label" → **After:** "An
+> icon-only button needs an aria-label so screen readers can announce it."
+
+## Vocabulary
+
+Technical terms that are the real names of things stay — `aria-label`, `role`,
+`Enter`, `Space` are what a reader would search for. What is banned from
+user-facing prose is the system's own machinery vocabulary: tokens,
+variables, bindings, fingerprints, provenance, projections, surfaces (in the
+machinery sense). `tokensUsed` keeps its token names — it is a structured
+field, machine-useful, and never rendered as prose.
+
+**No inline-code markup.** Write `aria-label`, `Enter`, `role` as plain words.
+One record string is projected to three surfaces that render backticks three
+different ways — MDX styles them, Figma's plain-text `description` strips them,
+and the doc card shows the literal character — so the record carries no
+presentation markup at all. Where formatting is wanted, the projection template
+supplies it: the Storybook MDX wraps variant and state keys in backticks itself.
+
+## Global rules
+
+- Full sentences. No em-dash label-fragments bolting a clause onto a fragment.
+- One set of strings for humans and AI — no dual copy. The digest (`llms.txt`
+  / `index.json`) inherits the same text.
+
+## The lint — `scripts/docs-lint.mjs`
+
+Checks the mechanically reliable subset of this standard. Zero-dependency,
+**warnings only, always exits 0**.
+
+| Rule | Checks | Threshold |
+|---|---|---|
+| `machinery-vocabulary` | banned-word list in user-facing prose (all prose fields; `tokensUsed`, `name`, `status`, `provenance` exempt) | — |
+| `summary-echo` | `whenToUse[0]` reusing the summary's content words (stopwords removed, naive plural/verb-s stemming) | > 60% overlap |
+| `run-on-sentence` | sentence length | > 35 words |
+| `summary-length` | `summary` length | > 12 words |
+| `description-length` | `description` length | outside 15–70 words |
+| `guidance-length` | `dos` / `donts` entry length | > 14 words |
+| `dont-shape` | a `donts` entry not opening with *Don't / Never / Avoid* | — |
+| `terminal-stop` | a `dos` / `donts` entry not ending with a full stop | — |
+| `treatment-lead` | a variant/state meaning opening with a visual-treatment word ({fill, filled, solid, stroke, border, bordered, outline, shadow, opacity, elevation}) | first 4 words |
+| `empty-meaning` | a variant or state meaning that's too short to say anything | < 3 words |
+| `no-inline-code` | backticks in user-facing prose (the card renders them literally; Figma strips them from `description`) | — |
+
+**Output contract:** always exits 0; one warning per line as
+`<file>: <block-path>: <rule>: <message>`; `--json` emits
+`{"warnings": [{path, rule, message}]}`.
+
+**Deliberately not linted: verb-presence.** Not reliably detectable in plain
+JS without an NLP dependency, and a rule that fires wrongly is worse than no
+rule. It stays a prose rule, caught by the authoring pipeline and the user
+approval step.
+
+## Sequencing
+
+1. Draft the record.
+2. Write the file to disk.
+3. `node ${CLAUDE_PLUGIN_ROOT}/scripts/docs-lint.mjs <file>`
+4. Fix warnings.
+5. Show the user.
+
+The lint shapes the draft before approval — it does not nag afterward.
+
+`imported` / `user` provenance blocks are never silently rewritten. The lint
+still warns on them; the proposed rewrite is carried into the single
+record-approval gate (shown as before/after, labelled with provenance).
+Blocks the user clears are stamped `imported+user`.

package/references/figma-component-standards.md

@@ -281,9 +281,28 @@ frames. Applies to `component-builder`, `icon-system-builder`, and
 
 ### Every component sits on its own documentation card
 
-Wrap each generated component in a "doc card" — a frame that holds the component
-plus a small header. Never leave components floating on bare canvas. The card
-shows:
+Wrap each generated component in a "doc card" — a **vertical, three-band
+auto-layout frame**: a **header** band, a **specimen** band (holding the
+component set — the builder's specimen contract is the card's `COMPONENT_SET`,
+not a band name), and a **`Usage`** band holding the documentation body. Never
+leave components floating on bare canvas.
+
+**The `Usage` band is never hand-built.** It is rendered by the canonical
+builder snippet in `${CLAUDE_PLUGIN_ROOT}/references/doc-card-builder.md`
+(generated — that file carries the full call contract: the record/fingerprint
+slots, the nine required semantic variables, the `Body/Default` text style, and
+the returned summary you verify and stamp the manifest from). The builder
+computes the card's width from the body type — a column-unit grid whose text
+fills its block, not the card. The column count comes from the record's
+content — the widest row's block count, with a floor of three. It rebuilds
+the `Usage` frame and rewrites the header's short description and date from
+the record; it reads the specimen and never writes it, and the status chip
+keeps its own owner (the finalize write-back below). The header's
+short-description text node is clamped to one column unit wide
+(`summary.columnUnit` from the builder's return), so it never stretches
+across a wide matrix.
+
+The header shows:
 
 - **Component name** (the deterministic name, matching code).
 - **Short description** (what it is / when to use it).
@@ -293,9 +312,11 @@ shows:
   `components.meta[name].status`. **Name the chip frame `Status` and its label
   text node `Status Label`** so the finalize write-back (below) can find and
   update them later — a chip with no deterministic name can't be promoted.
-- **Last updated** — a date, from `components.meta[name].updatedAt`, refreshed
-  whenever the component is rebuilt. **Name this text node `Last Updated`** for
-  the same reason.
+- **Last updated** — a date, from the doc record's `updatedAt` field
+  (`record.updatedAt` — the single source for the header date; not
+  `components.meta[name].updatedAt`, which is separate manifest bookkeeping),
+  refreshed whenever the component is rebuilt. **Name this text node
+  `Last Updated`** for the same reason.
 
 **Always separate the header from the component area with a division element.** The
 header block (name, description, status, date) and the component/variant area below
@@ -341,8 +362,11 @@ re-describing it:
    Figma: flip the status chips amber → green and set Last Updated to today.
    Confirm?"* One confirmation covers the whole batch; don't ask per card.
 1. Set `components.meta[name].status` to the new status (`stable` on finalize) and
-   `components.meta[name].updatedAt` to today (ISO date). The manifest is the
-   source of truth.
+   `components.meta[name].updatedAt` to today (ISO date) — this is manifest
+   bookkeeping, separate from the header date. Also set `updatedAt` to today in
+   the component's `.doc.json` record: `record.updatedAt` is the single source
+   the doc card's header renders its date from, so this is the write that
+   actually moves the date the user sees.
 2. If Figma is connected (use `figma.mechanism`), locate the component's doc card
    by its deterministic name (script the write-back per
    `${CLAUDE_PLUGIN_ROOT}/references/figma-scripting.md` — `getNodeByIdAsync`, and
@@ -351,14 +375,20 @@ re-describing it:
    - set the `Status Label` text to the new status (e.g. `stable`);
    - re-bind the `Status` chip fill to the matching semantic color variable
      (`stable` → success, `draft`/`beta` → warning, `deprecated` → neutral/danger)
-     — re-bind the variable, don't hardcode a hex, so it stays mode-aware;
-   - set the `Last Updated` text to today's date.
-   Then run the visual-validation loop (screenshot → confirm the chip recolored
-   and the date changed → re-screenshot).
+     — re-bind the variable, don't hardcode a hex, so it stays mode-aware.
+   Then re-run the canonical doc-card builder
+   (`${CLAUDE_PLUGIN_ROOT}/references/doc-card-builder.md`) against the same card
+   to refresh the header date from the `record.updatedAt` just set in step 1 — the
+   builder locates the date node under either header shape (legacy label/value
+   frame, or the to-spec `Last Updated` text node) and writes it there, so this
+   step never hand-stamps today's date onto a guessed node. Then run the
+   visual-validation loop (screenshot → confirm the chip recolored and the date
+   changed → re-screenshot).
 3. If Figma is **not** connected, still do step 1, and tell the user the card will
-   reconcile to the manifest the next time a Figma session runs (the doc card
-   always renders from `components.meta[name]`). Offer to reconnect and update it
-   now if they want it reflected immediately.
+   reconcile the next time a Figma session runs — its status chip renders from
+   `components.meta[name].status` and its header date from `record.updatedAt`,
+   both already updated by step 1. Offer to reconnect and update it now if they
+   want it reflected immediately.
 
 **Icons are the one exception:** the whole icon set lives on a *single* doc card
 holding the icon grid — one card for all icons, not one card per icon.
@@ -410,6 +440,10 @@ The doc card is a **vertical, top-to-bottom auto-layout** frame
 overlapping text is almost always absolutely-positioned or mis-sized nodes, and
 proper auto layout eliminates it.
 
+The `Usage` band's internal layout (rows, wrapping, block widths) is entirely
+the builder's job — these auto-layout rules apply to the header band and any
+hand-built chrome, not to nodes inside `Usage`.
+
 ### Arrange cards in a parent container (fixes overlapping artboards)
 
 Never drop cards onto blank canvas at coordinates that can collide. Place all doc
@@ -486,6 +520,11 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
 3. **Variables bound** — every fill, stroke, text color, corner radius,
    `itemSpacing`, and padding resolves to a **bound variable** (`boundVariables`
    present), not a raw hex/px. No hardcoded values anywhere in the doc-card chrome.
+   **Two documented exceptions inside the `Usage` band** (layout chrome, not
+   design values, both produced by the builder): the computed column-unit width
+   on blocks, and the derived eyebrow type (size/case/tracking/weight). All
+   other `Usage` properties — padding, gaps, text colors, dividers — must still
+   resolve to bound variables.
    **Check container and component-set background fills specifically** — a paint bind
    that didn't stick renders the placeholder color instead (a pure-black placeholder
    reads as accidental dark mode), so read back `fills[0].boundVariables.color` on
@@ -522,9 +561,17 @@ For each generated artboard / doc card / icon grid, read the nodes back (via
    be retrofitted to the current recipe (see "State handling").
 10. **Visual** — the screenshot (from the validation loop) shows no overlaps,
    misalignment, lopsided hug/fill sizing, or clipped strokes/focus rings.
+11. **Usage band rendered by the builder** — the card's `Usage` frame was
+   created by `renderDocCard`
+   (`${CLAUDE_PLUGIN_ROOT}/references/doc-card-builder.md`) in this session, and
+   the returned summary matches the record: `rowsRendered` and `blocksCreated`
+   line up with the record's populated blocks, `cardWidth` is a whole multiple
+   of `columnUnit` (minimum 3), and the frame contains the deterministic names
+   (`Usage`, `Usage Row 1..3`, `Block: …`, `Doc Fingerprint`). Verify from the
+   summary, not a screenshot. A hand-assembled usage body is a fail.
 
 If any item fails, **fix and re-audit** — don't hand off a partial pass. Iterate
-with the same ~3-pass budget as the visual loop. Only when all ten pass is the
+with the same ~3-pass budget as the visual loop. Only when all eleven pass is the
 build done.
 
 ## Naming

package/references/guide-voice.md

@@ -0,0 +1,96 @@
+# Guide Voice
+
+ThroughLine walks someone through building a design system. That framing is the
+whole product. Every skill should sound like a guide standing next to you, not a
+tool printing status. This file is the source of truth for that voice, and
+specifically for how a flow **closes** — the moment a skill finishes a unit of
+work and hands back to the user.
+
+Skills that end a flow point here. Do not restate the rules inline; reference this
+file and follow it.
+
+## The principle
+
+A guide has a point of view and shares it. A config wizard lays out options and
+makes you choose. The difference the user feels is whether they leave a step with
+a clear next move or with homework.
+
+The failure this corrects: closing a flow with a flat menu of unlike options, each
+ranked for the user to adjudicate, with no recommendation. It reads as cold and it
+pushes the thinking back onto the person you were supposed to be guiding.
+
+## The flow-close pattern
+
+When a skill finishes, close in four beats, in prose. Not a table. Not an option
+card. Prose.
+
+**1. Outcome.** One line. What got done, and whether it is in sync.
+
+> "Button is documented. The canonical record is written, and the Figma
+> description and doc card are both projected and in sync."
+
+**2. What I set aside, and why.** Name any gap you deferred, in a clause, with the
+reason. Read existing state to know what is actually outstanding (for the docs
+flow, a component at `status: "draft"` with no code surface in
+`meta[name].doc.surfaces` means the code side is not built yet). Give the reason
+so the deferral reads as a decision, not an omission.
+
+> "I left the code-side render for later on purpose. It is a one-time,
+> system-wide scaffold that every future component rides, so it is worth doing
+> deliberately as its own step, not half-built mid-flow."
+
+**3. My recommendation.** A short, sequenced, reasoned plan. State it as the
+default. End on one clear next action the user can say yes to.
+
+> "My take: document Input and Card next to pressure-test the model on
+> higher-surface-area components, then stand up the code side once, against all
+> three at once. Want me to start on Input?"
+
+**4. Or.** At most one genuinely comparable alternative, demoted to a light aside.
+If there is not a real alternative, leave this out entirely. Do not manufacture
+one for symmetry.
+
+> "(If you would rather lay the code rails first so everything after Button rides
+> them, say the word and I will do that instead.)"
+
+## The hard rule
+
+**Never present a decision point as a grid of co-equal options.** At the close of
+a flow, an `AskUserQuestion`-style option menu is the anti-pattern itself. The
+whole point is that you have a recommendation. Lead with it.
+
+Use a real option list only when the choices are genuinely comparable, mutually
+exclusive, and you honestly have no basis to recommend one. That is rare at a flow
+close. It is common mid-flow (which component to build, which framework), and
+there an option list is fine.
+
+## What good looks like, versus what to avoid
+
+Avoid:
+
+> "Two honest notes. The JSDoc surface is untouched. Nothing is committed. Want me
+> to open a PR, or keep going and document the next batch?"
+
+Two unlike options, no recommendation, a respected boundary dressed up as a
+decision. That is the config wizard.
+
+Better:
+
+> "The JSDoc call was right. Leaving hand-written imported docs untouched is the
+> record model working as designed, not a gap. My take: open the PR now, before
+> the next batch. It is a clean, self-contained unit, and opening it is what
+> actually exercises the docs:check CI gate end-to-end. So: branch, PR, let CI
+> prove the gate, then document the next batch on landed foundations. (If you want
+> to keep momentum, batching the next few first is defensible, you are just
+> trading review clarity for it.)"
+
+Same facts. One affirms the boundary instead of dressing it as a choice, collapses
+the fork to one recommended path with the reason, and demotes the alternative to
+an aside.
+
+## Adoption
+
+`/document-component` is the first flow to adopt this. Every other flow picks it up
+when it is next touched, not in a speculative sweep. Persisting *why* a stage was
+allowed to advance as structured state is a separate, larger piece (the
+verification proof bundle) and is out of scope here.

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 5)
+## Schema (schemaVersion 6)
 
 ```json
 {
-  "schemaVersion": 5,
+  "schemaVersion": 6,
   "user": {
     "codingLevel": "new"
   },
@@ -42,7 +42,8 @@ bailing or running silently.
     "coverPageBuilt": false,
     "canPublish": null,
     "libraryPublished": false,
-    "publishedAt": null
+    "publishedAt": null,
+    "docCardVariables": null
   },
   "tokens": {
     "intakeMode": null,
@@ -189,6 +190,16 @@ bailing or running silently.
   discipline in `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`.**
 - `publishedAt` — ISO timestamp the user last confirmed a publish, for "you may
   need to re-publish after adding components" messaging.
+- `docCardVariables` — object mapping the doc-card builder's nine semantic
+  variable roles to the variable name each resolves to in this project's file:
+  `{ textDefault, textMuted, tonePositive, toneNegative, border, spacePadding,
+  spaceRowGap, spaceBlockGap, spaceItemGap }`. `null` until set. Written once,
+  on the first doc-card render in a project, and read by every render after
+  (see `${CLAUDE_PLUGIN_ROOT}/references/doc-card-builder.md`). Exists because
+  the roles are project-agnostic but the variable names are not — an
+  unrecorded mapping drifts between renders (different roles resolved to
+  different variables each time) and leaves cards visually inconsistent. E.g.
+  `{ "textDefault": "color/text/primary", "textMuted": "color/text/secondary", "tonePositive": "color/success/default", "toneNegative": "color/danger/default", "border": "color/border/default", "spacePadding": "space/inset/lg", "spaceRowGap": "space/gap/xl", "spaceBlockGap": "space/gap/lg", "spaceItemGap": "space/gap/sm" }`.
 
 ### `tokens`
 - `intakeMode` — how the user started: `"generative"` (seed expanded by AI),
@@ -253,10 +264,13 @@ bailing or running silently.
 - `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? } } }`,
+  `{ path, fingerprint, surfaces: { <surfaceName>: { src, render, file?, renderer? } } }`,
   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),
+  `renderer` (docCard only) is the layout version of the builder that last
+  rendered the card (`DOC_CARD_RENDERER_VERSION`); missing/lower is reported by
+  `docs:check` as the informational `layout-upgrade-available`, never as drift,
   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
@@ -361,3 +375,7 @@ retrofit stands so a later session can resume.
 **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.
+
+**v5 → v6 migration:** add `figma.docCardVariables` (default `null`), populated
+on the first doc-card render. Bump `schemaVersion` to `6`. No existing field
+changes.

package/scripts/README.md

@@ -14,6 +14,29 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `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` |
+| `docs-lint.mjs` | Copy lint for .doc.json records — warnings only, always exits 0 on a parseable record; the mechanical subset of `references/doc-writing-standard.md`. | `docs:lint` |
+| `lib/doc-record.mjs` | Canonical record load + `canonicalFingerprint` (sha256 over the record minus `provenance`). The fingerprint every surface is stamped with. | copied alongside docs-check.mjs |
+| `lib/doc-card-render.figma.js` | Figma renderer template for the doc card's `Usage` band and header. Inlined into `references/doc-card-builder.md`; never executed as a module. | plugin-internal (not installed) |
+| `lib/doc-card-plan.mjs` | Pure layout planner for the doc card's `Usage` band + `DOC_CARD_RENDERER_VERSION` (single source of the layout version). Inlined into `references/doc-card-builder.md`; imported by `docs-check.mjs`. | copied alongside docs-check.mjs; also inlined into the generated builder |
+| `build-doc-card-builder.mjs` | Generate `references/doc-card-builder.md` from the planner + the Figma renderer template (`lib/doc-card-render.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
+
+**Documentation scripts — install as a set.** Copying these files without
+registering them leaves a repo with a script on disk and no entry point, which
+is how a stale `docs:check` went unnoticed for a full release. Both
+`storybook-chromatic-builder` (first-time setup) and `/document-component`
+(freshness refresh) install the same five files and register the same three
+scripts:
+
+| File | npm script |
+| --- | --- |
+| `build-docs-digest.mjs` | `"docs:digest": "node scripts/build-docs-digest.mjs"` |
+| `docs-check.mjs` | `"docs:check": "node scripts/docs-check.mjs"` |
+| `docs-lint.mjs` | `"docs:lint": "node scripts/docs-lint.mjs"` |
+| `lib/doc-record.mjs` | — (imported by the above) |
+| `lib/doc-card-plan.mjs` | — (imported by the above) |
+
+A refresh that adds a file must also add its npm script; check `package.json`
+for all three every time, not just the file that changed.
 
 The crosswalk contract is documented in
 `${CLAUDE_PLUGIN_ROOT}/references/crosswalk-schema.md`.

package/scripts/build-doc-card-builder.mjs

@@ -0,0 +1,143 @@
+// Generates references/doc-card-builder.md — the canonical figma_execute
+// snippet that renders a doc card's Usage band — by inlining the pure planner
+// (lib/doc-card-plan.mjs) above the Figma renderer template
+// (lib/doc-card-render.figma.js). Mirrors the adapters generate.mjs idiom:
+// run bare to write, run with --check to gate CI. Zero dependencies.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PLANNER = join(REPO_ROOT, 'scripts', 'lib', 'doc-card-plan.mjs');
+const RENDERER = join(REPO_ROOT, 'scripts', 'lib', 'doc-card-render.figma.js');
+const OUT = join(REPO_ROOT, 'references', 'doc-card-builder.md');
+
+const HEADER = [
+  '# Doc-card Usage-band builder (GENERATED)',
+  '',
+  '> **GENERATED FILE — do not edit by hand.** Sources: `scripts/lib/doc-card-plan.mjs`',
+  '> (the pure planner, unit-tested in Node) + `scripts/lib/doc-card-render.figma.js`',
+  '> (the Figma renderer). Regenerate with `node scripts/build-doc-card-builder.mjs`;',
+  '> CI gates freshness with `--check`.',
+  '',
+  'The canonical `figma_execute` snippet that renders a component doc card\'s',
+  '`Usage` band from its `.doc.json` record. Every card is identical by',
+  'construction — never hand-build the usage body. The builder owns the `Usage`',
+  'band and the header\'s record-derived content (its short description and date);',
+  'it reads the specimen and never writes it. The status chip keeps its own owner',
+  '— the finalize write-back in `references/figma-component-standards.md`.',
+  '',
+  '## How to call it',
+  '',
+  '1. Load the record and compute its canonical fingerprint in Node',
+  '   (`canonicalFingerprint` in `scripts/lib/doc-record.mjs`).',
+  '2. Read `figma.docCardVariables` from `design-system.json`.',
+  '   - If present, resolve each of the nine roles to a Variable object **by',
+  '     the recorded name** — do not re-derive, do not substitute a similar',
+  '     name. Look each name up via `figma_get_variables`, then in the script',
+  '     fetch it as a Variable object with',
+  '     `figma.variables.getVariableByIdAsync(id)`. If a recorded name no',
+  '     longer resolves to exactly one variable in the file, **throw** rather',
+  '     than guess — the token was renamed or removed, and silently picking a',
+  '     neighbour is how cards drift apart.',
+  '   - If the field is absent (a project\'s first doc-card render, or any',
+  '     render after the field is cleared), do not resolve fresh by judgement',
+  '     yet — first check whether a doc card already exists in the file. If',
+  '     one does, recover all nine roles from it by resolving each bound',
+  '     variable id back to its name (`figma.variables.getVariableByIdAsync(id)`):',
+  '     - `spacePadding` ← the `Usage` frame\'s `paddingLeft`.',
+  '     - `spaceRowGap` ← the `Usage` frame\'s `itemSpacing`.',
+  '     - `spaceBlockGap` ← a `Usage Row *` frame\'s `itemSpacing`.',
+  '     - `spaceItemGap` ← a `Block: *` frame\'s `itemSpacing` (blocks are the',
+  '       children of a `Usage Row *`).',
+  '     - `border` ← a `Row Divider` frame\'s',
+  '       `fills[0].boundVariables.color`.',
+  '     - `tonePositive` ← the first TEXT child of the `Block: Do` frame\'s',
+  '       `fills[0].boundVariables.color`.',
+  '     - `toneNegative` ← the first TEXT child of the `Block: Don\'t` frame,',
+  '       same property.',
+  '     - `textMuted` ← the first TEXT child of any block other than',
+  '       `Block: Do` / `Block: Don\'t`, same property (tone blocks colour',
+  '       their eyebrow differently, so exclude them here).',
+  '     - `textDefault` ← the second child of that same block when it is a',
+  '       TEXT node — `Block: Overview` is reliable; definition blocks nest',
+  '       frames there instead, so skip those. Same property.',
+  '     A single-row card has no `Row Divider` (no `border`); a card without',
+  '     `Block: Do` / `Block: Don\'t` yields no `tonePositive` / `toneNegative`.',
+  '     Read another rendered card for the roles that specific card can\'t',
+  '     yield, or fall back to judgement for just those. Only when no',
+  '     rendered card exists at all does the caller choose every role by',
+  '     judgement — establishing the project\'s rhythm, not guessing at one.',
+  '   Either way, resolve the nine roles once, **write the mapping back to',
+  '   `design-system.json`** as `figma.docCardVariables`, then render. Every',
+  '   later render reads it.',
+  '   The nine roles: `textDefault`, `textMuted` (text colors), `tonePositive`,',
+  '   `toneNegative` (Do/Don\'t eyebrow colors — success/danger roles), `border`',
+  '   (row dividers), `spacePadding`, `spaceRowGap`, `spaceBlockGap`,',
+  '   `spaceItemGap` (spacing roles: band padding, row gap, block gutter,',
+  '   within-block gap).',
+  '3. Find the body text style: `(await figma.getLocalTextStylesAsync())',
+  '   .find((s) => s.name === \'Body/Default\')`. Missing variables or style =',
+  '   the builder throws (bind-or-throw — the gap is in the token set; fix it',
+  '   there, never hardcode around it).',
+  '4. Prepend the two slots, then the snippet below, then the call:',
+  '',
+  '```js',
+  'const RECORD = /* the parsed .doc.json object */;',
+  'const CANONICAL_FP = \'/* canonicalFingerprint(RECORD), 16 hex chars */\';',
+  '// … the generated snippet …',
+  'const card = await figma.getNodeByIdAsync(cardNodeId);',
+  'const summary = await renderDocCard({ card, record: RECORD, vars, bodyTextStyle });',
+  '```',
+  '',
+  '5. Pass an explicit `timeout` (30000 is right for one card; the ~30s',
+  '   `figma_execute` ceiling fits a single card comfortably — render cards one',
+  '   call at a time, never batched).',
+  '6. Verify from the returned summary — `rowsRendered`, `blocksCreated`,',
+  '   `cardWidth` — not from a screenshot, then stamp the manifest from it:',
+  '   `surfaces.docCard = { src: summary.fingerprint, render: summary.renderHash,',
+  '   renderer: summary.rendererVersion }`. Never re-read the card to stamp.',
+  '',
+  '## The snippet',
+  '',
+  '```js',
+].join('\n');
+
+const FOOTER = [
+  '```',
+  '',
+  'Layout contract and rationale:',
+  '`docs/superpowers/specs/2026-08-09-doc-card-layout-and-voice-design.md`.',
+  '',
+].join('\n');
+
+export function buildDocCardBuilder({ plannerSource, rendererSource }) {
+  const inlined = plannerSource
+    .replace(/^export const /gm, 'const ')
+    .replace(/^export function /gm, 'function ');
+  for (const [name, src] of [['doc-card-plan.mjs', inlined], ['doc-card-render.figma.js', rendererSource]]) {
+    if (/^\s*(import|export)\b/m.test(src)) {
+      throw new Error(`${name} must stay import-free (only top-level \`export const\`/\`export function\` allowed in the planner) — it is inlined into the Figma snippet where no module system exists`);
+    }
+  }
+  return `${HEADER}\n${inlined}\n${rendererSource}${FOOTER}`;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const result = buildDocCardBuilder({
+    plannerSource: readFileSync(PLANNER, 'utf8'),
+    rendererSource: readFileSync(RENDERER, 'utf8'),
+  });
+  if (process.argv.includes('--check')) {
+    let onDisk = null;
+    try { onDisk = readFileSync(OUT, 'utf8'); } catch (e) { /* missing counts as drift */ }
+    if (onDisk !== result) {
+      console.error('✗ references/doc-card-builder.md out of date; run: node scripts/build-doc-card-builder.mjs');
+      process.exit(1);
+    }
+    console.log('✓ doc-card builder in sync');
+  } else {
+    writeFileSync(OUT, result);
+    console.log('✓ wrote references/doc-card-builder.md');
+  }
+}