@radicool/throughline 0.13.0 → 0.14.0

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

@@ -227,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` ↔
@@ -284,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/generic/skills/design-system-audit/SKILL.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/generic/skills/repository-builder/SKILL.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/generic/skills/retrofit-planner/SKILL.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/generic/skills/storybook-chromatic-builder/SKILL.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
@@ -170,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
@@ -193,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/package.json

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

package/references/component-doc-archetypes.md

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

package/references/component-doc-schema.md

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

package/references/manifest-schema.md

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

package/scripts/README.md

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

package/scripts/build-docs-digest.mjs

@@ -0,0 +1,74 @@
+// docs:digest — aggregates every component doc record into two AI-facing
+// artifacts: index.json (machine map) and llms.txt (narrative index).
+// Zero dependencies.
+//
+// Usage: node build-docs-digest.mjs [--root <dir>]
+import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { loadRecord } from './lib/doc-record.mjs';
+
+const DOCS_DIR = join('design-system', 'docs');
+const COMPONENTS_DIR = join(DOCS_DIR, 'components');
+
+export function buildIndex(records) {
+  return {
+    generatedFrom: 'design-system/docs/components/*.doc.json',
+    components: records.map((r) => ({
+      name: r.name,
+      summary: r.summary ?? '',
+      description: r.description ?? '',
+      whenToUse: r.whenToUse ?? [],
+      whenNotToUse: r.whenNotToUse ?? [],
+      variants: r.variants ?? {},
+      states: r.states ?? {},
+      dos: r.dos ?? [],
+      donts: r.donts ?? [],
+      accessibility: r.accessibility ?? {},
+      tokensUsed: r.tokensUsed ?? [],
+      status: r.status ?? 'draft',
+    })),
+  };
+}
+
+export function buildLlmsTxt(records) {
+  const lines = ['# Design system — component usage guide', ''];
+  lines.push('Generated documentation for AI and human consumers. One section per component.', '');
+  for (const r of records) {
+    lines.push(`## ${r.name}`, '');
+    if (r.summary) lines.push(r.summary, '');
+    if (r.description) lines.push(r.description, '');
+    if ((r.whenToUse ?? []).length) lines.push('**When to use:** ' + r.whenToUse.join('; '));
+    if ((r.whenNotToUse ?? []).length) lines.push('**When not to use:** ' + r.whenNotToUse.join('; '));
+    if ((r.dos ?? []).length) lines.push('**Do:** ' + r.dos.join('; '));
+    if ((r.donts ?? []).length) lines.push("**Don't:** " + r.donts.join('; '));
+    if ((r.tokensUsed ?? []).length) lines.push('**Tokens:** ' + r.tokensUsed.join(', '));
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+export function loadAllRecords(root) {
+  const dir = join(root, COMPONENTS_DIR);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((f) => f.endsWith('.doc.json'))
+    .sort()
+    .map((f) => loadRecord(join(dir, f)));
+}
+
+function main() {
+  const { values } = parseArgs({ options: { root: { type: 'string', default: '.' } } });
+  const root = values.root;
+  const records = loadAllRecords(root);
+  const outDir = join(root, DOCS_DIR);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  writeFileSync(join(outDir, 'index.json'), JSON.stringify(buildIndex(records), null, 2) + '\n');
+  writeFileSync(join(outDir, 'llms.txt'), buildLlmsTxt(records));
+  console.log(`✓ docs:digest — ${records.length} component(s) → design-system/docs/{index.json,llms.txt}`);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main();
+}