@radicool/throughline 0.13.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 4)
+## Schema (schemaVersion 6)
 
 ```json
 {
-  "schemaVersion": 4,
+  "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,
@@ -87,7 +88,8 @@ bailing or running silently.
     "ranAt": null,
     "codeSurface": null,
     "figmaInventory": null,
-    "percentSemantic": null
+    "percentSemantic": null,
+    "docSurface": null
   },
   "tokenCrosswalk": {
     "path": null,
@@ -188,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),
@@ -249,6 +261,20 @@ 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?, 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
+  `${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 +318,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 +338,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 +371,11 @@ 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.
+
+**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

@@ -12,6 +12,31 @@ 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` |
+| `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`.
@@ -76,3 +101,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.