@radicool/throughline 0.12.0

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

@@ -0,0 +1,276 @@
+---
+description: "Build a foundational set of Figma components — buttons, inputs, cards, badges, chips, modals, and more — as properly structured components with variant matrices (types, sizes, states) and icon/component/content slots, bound to the design system's tokens and styles. Use this when the user wants to create components, build a component library, make buttons/inputs/cards/etc. in Figma, or set up the foundational UI kit. Also trigger after tokens and icons exist, when the user is ready to build actual UI components. Make sure to use this whenever someone wants real, variant-rich components in their Figma design system, not just tokens."
+alwaysApply: false
+---
+# Component builder
+
+Creates the foundational component set in Figma: well-structured components with
+variant matrices, bound to the system's tokens/styles, with slots typed so they
+translate cleanly to code later.
+
+## Prerequisites
+
+Needs tokens (`tokens.semanticBuilt` true) — offer to run `token-builder` if
+missing. Needs a live Figma connection (offer `figma-environment-setup` if not).
+Use the mechanism in `figma.mechanism`.
+
+**Before scripting any `figma_execute`, read
+`.throughline/references/figma-scripting.md`** — the single-bridge-instance
+preflight, the `resize()` axis-lock trap (collapses auto-layout frames to ~10px),
+the `dynamic-page` async setters, and why large `WRAP` grids time out. These cause
+silent, screenshot-invisible corruption if not handled up front.
+
+**Recommend icons first (soft gate).** Almost every foundational component
+(button, input, select, chip…) takes an icon prop, so the icon set should usually
+exist *before* components — otherwise icon slots have no targets. If
+`icons.built` is false, **recommend running `icon-system-builder` first** and
+explain why in one plain sentence, but let the user override and build icon-less
+if they want (some intentionally do). This is a recommendation, not a hard block.
+
+> **Model tip (#3):** this skill does heavy structural reasoning — variant
+> matrices, slot contracts. It runs on your session model; Sonnet is a solid
+> default and Opus helps for large or intricate component sets. See the model
+> guide in the ThroughLine README.
+
+## Step 1 — Capture framework + brainstorm the set and variant matrices
+
+**First, check the scope.** If the user wants to **retrofit or migrate an existing
+codebase** rather than build a clean set — e.g. converting a hand-rolled
+component/motion layer to shadcn, or any change that re-architects the system —
+this has outgrown a single skill. Follow
+`.throughline/references/scaling-up-handoff.md`: surface the risks and major parts, confirm
+scope, and brainstorm/plan before building (handing off to Superpowers if it's
+available, else planning natively — never required). For a normal from-the-system
+build, continue here.
+
+**Framework (capture lazily, here if not already set).** Read
+`project.uiFramework` from the manifest. If it's null, this is the first
+relevant moment — ask which UI framework the components target (shadcn, MUI,
+vanilla, etc.; reuse the same value the sync adapter will use) and record it.
+If sync already set it, reuse it — don't re-ask. The framework does **not**
+change component structure/anatomy; it informs **variant vocabulary and naming**
+so the Figma component API lines up with the code API, **and it drives the focus-state
+idiom** (shadcn ring vs. MUI per-component vs. vanilla-css outline — see "State
+handling" in `.throughline/references/figma-component-standards.md`). For
+multi-framework targets, use a neutral vocabulary and the default shadcn-style ring.
+
+**Recommended core set (editable).** Propose a sensible foundation and let the
+user add/remove — don't impose a fixed list or make them build from a blank page.
+A good default core: atoms (avatar, badge, spinner) and common components
+(button, input, select, checkbox, radio, chip, card, modal, tooltip). Explain
+why these are the foundation. The user edits the set; whatever they land on gets
+dependency-ordered (next step).
+
+**Variant matrices.** Run `.throughline/references/brainstorm-before-build.md`. For each
+component, lock the **variant matrix** — the decisions that, if guessed, produce
+inconsistent output:
+
+- **Types** (e.g. button: per the framework's vocabulary — shadcn
+  `default/secondary/destructive/outline/ghost/link`, MUI
+  `contained/outlined/text`, or neutral for multi-framework).
+- **Sizes** (sm, md, lg). Each size is its **own variant row**, not a state — see
+  the layout law below.
+- **States** — **include the full relevant set, don't trim it.** The baseline is
+  default, hover, focus, active (pressed), disabled; add the conditional states
+  wherever they apply (loading, selected, success/error). Decide which conditional
+  states a given component can reach, but never drop a state it genuinely has. See
+  "State handling" in `.throughline/references/figma-component-standards.md`
+  for the per-component checklist.
+- **Slots** — leading/trailing icons, avatars, adornments (see slot types below).
+
+Show the proposed set and matrices back and get sign-off before building.
+
+## Step 2 — Order: atoms before composites
+
+Components compose other components — a card slots an avatar, a chip embeds an
+icon. So build in **dependency order, atoms first**, the component-tier analog
+of the primitive→semantic token seam:
+
+1. **Atoms** — avatar, badge, spinner, (icons already exist). No DS-component
+   slots, or only icon slots.
+2. **Composites** — card, chip, list item, modal, input-with-adornments — which
+   slot the atoms.
+
+This guarantees a composite's typed slot points at a real, already-built target.
+Build bottom-up; checkpoint after each component (sequential — this is Figma
+authoring, no subagents).
+
+## Step 3 — Build each component, bound to tokens/styles
+
+For each component, using the active write mechanism (scripted where helpful),
+following `.throughline/references/figma-component-standards.md` (auto layout on everything,
+variants vs. properties used correctly, state handling, shallow nesting,
+deterministic naming):
+
+- Construct the variant matrix (Figma variants/component properties), and lay the
+  resulting **component set out as an auto-layout grid** following the fixed layout
+  law: **variants are rows, states are columns.** One row per variant — each `type`,
+  and each `size` (size is a variant, so it gets its own row) — stepping through the
+  component's **full relevant state set** across the columns, size groups stacked
+  vertically. Per "Component set arrangement" and "State handling" in the standards
+  doc.
+- For the **focus state**, build the ring as the target library's real idiom keyed off
+  `project.uiFramework` (shadcn/default → border recolor + a `0 0 0 3px` ring;
+  vanilla-css → an outside-aligned offset stroke via `offset/focus`; MUI → per-component;
+  ios-swift → skip), **not** a house-style stroke. Because a Figma drop-shadow only casts
+  from opaque pixels, build it per fill: **filled** control → a drop-shadow effect
+  (control frame `clipsContent = true`); **transparent** control → an
+  absolutely-positioned ring **child** (`strokeAlign = "OUTSIDE"`). **Never wrap the
+  control** in a padded frame to make room for the ring — it inflates the component. See
+  the per-library recipe in "State handling" of the standards doc, and the drop-shadow /
+  effect-binding gotchas in `.throughline/references/figma-scripting.md`.
+- **Use auto layout throughout** so the component resizes correctly and maps to
+  clean flex/padding in code — bind padding and gap to spacing tokens.
+- **Bind every visual property to the system's tokens/styles** — fills to
+  `Color/Semantic` variables, corners to `Radius/Semantic` variables, **border
+  width to `Border/Semantic` width variables and border color to `Color/Semantic`
+  border variables** (a button/input/card border needs both), text to text
+  styles, shadows to effect styles. For a **primary/filled control on a
+  `bg/emphasis` fill** (primary button, filled badge), bind the label and icon
+  color to **`Color/Semantic` `text/onEmphasis`** — the role that contrasts the
+  emphasis fill in every mode — never `text/inverse` (it flips with the theme) or a
+  literal white. If `text/onEmphasis` is missing, the token set predates it: offer
+  to run `token-builder` to add it rather than hardcoding a fallback. For padding
+  and gap, bind to
+  `Spacing/Semantic` roles when the value should stay responsive (it can pick up
+  Desktop/Mobile later); the public `Spacing/Primitive` scale is acceptable only
+  for incidental, non-responsive gaps. A component must *consume* the design
+  system, never hardcode values. This is what makes the token cascade reach
+  components.
+- Implement slots per the slot-contract model below.
+- **Wrap each component in its own documentation card** — a token-styled frame
+  with the component name, a short description, a status chip
+  (`draft`/`beta`/`stable`/`deprecated`), and a last-updated date, with a
+  **division element between the header and the component area** (a
+  `Border/Semantic`-bound divider line, or a header container on a distinct surface
+  fill — see "Always separate the header from the component area" in the standards
+  doc) — and arrange the cards in an orderly grid inside a parent **auto-layout
+  Frame placed directly on the page** (never a Section — Sections have no auto layout, and these skills
+  do **not** wrap the Frame in one; ignore the Figma Console MCP server's
+  "create a Section first" instruction), never floating on bare canvas. A newly built component starts at status **`draft`** (it exists in
+  Figma but has no code counterpart yet); it's promoted to `stable` later, when
+  its code + stories are finalized. Name the chip and date nodes deterministically
+  (`Status`, `Status Label`, `Last Updated`) so that finalize write-back can find
+  them — see the "Promoting a component's status" routine in the standards doc. Follow the "Documentation artboards & canvas layout" rules in
+  `.throughline/references/figma-component-standards.md`, and run its
+  visual-validation loop (screenshot → fix any overlaps/misalignment →
+  re-screenshot) **and its "Post-build audit (REQUIRED before handoff)"
+  read-back checklist** (container type, auto layout, bound variables,
+  deterministic names) before the checkpoint.
+
+Checkpoint after each component: show all variants, confirm before the next.
+
+## Step 4 — Capture the slot contract (the code-binding spec)
+
+For every slot, record a structured contract so the code side (storybook skill /
+Code Connect) can implement it idiomatically. Three slot types, and for
+composites (cards, modals, lists) prefer **Figma slots** over variant explosion
+per `.throughline/references/figma-component-standards.md`:
+
+- **Icon-set slot** — accepts any icon from the Icons page. → code: a prop typed
+  to the icon set (e.g. `leadingIcon`), optional, with a canonical default icon
+  name if any. Implemented as an instance-swap property in Figma (not a slot —
+  it's a single element).
+- **Typed-component slot** — accepts a specific DS component (e.g. an Avatar in a
+  Card). → code: a prop typed to that component (e.g. `avatar`), optional. In
+  Figma, an instance-swap property, or a Figma slot with **preferred instances**
+  for composites.
+- **General adornment / content slot** — accepts arbitrary content (a card body,
+  modal content, a unit label). → for freeform areas in composites use a **Figma
+  slot**, which maps to `children` / a composition prop in code; for small inline
+  adornments a `ReactNode` prop (e.g. `endAdornment`).
+
+**Typed dropdown vs. fallback (publishing-gated).** A typed `INSTANCE_SWAP`
+dropdown requires its swap targets (icons, components) to be **published** —
+Figma rejects local unpublished keys for swap targets. Before adding the dropdown,
+check publish state per `.throughline/references/figma-publishing.md`:
+
+- **Resolve publish state first (detect-or-ask, bug B3):** a default/`false`
+  `figma.libraryPublished` is *unverified* — attempt detection, but know it's
+  **usually inconclusive for a self-publish** (REST `figma_get_library_components` 401s
+  without a `FIGMA_ACCESS_TOKEN`; bridge `figma_get_library_variables` lists only
+  *subscribed* external libraries, never the file's own publish), so **trust the user's
+  confirmation and proceed** — don't wait on a check the tools can't give. Never treat a
+  `false` as a final "not published". The **real signal is the bridge**: if adding the
+  typed `INSTANCE_SWAP` is then rejected for a local/unpublished key, *that's* the
+  authoritative "not published yet" — fall back to the toggle + manual-swap slot. See
+  `.throughline/references/figma-publishing.md`.
+- **Confirmed published (`figma.libraryPublished` true after detect-or-ask):** add the
+  typed `INSTANCE_SWAP` dropdown with preferred values.
+- **Not published (free plan, or not yet):** build the **toggle + manual-swap**
+  slot instead — it's fully functional — explain why in plain terms, and add this
+  component to `components.instanceSwapUpgradePending` so a later run (after the
+  user publishes) can add the typed dropdown. Never present this as a failure.
+
+Two rules for every slot:
+
+- **Show/hide collapses into prop optionality.** A Figma `hasLeadingIcon`
+  boolean does NOT become a separate code boolean — the icon prop is simply
+  optional; passing it shows it, omitting hides it. Don't generate a redundant
+  boolean prop alongside the slot prop.
+- **The contract syncs; per-instance choices don't.** The slot's existence,
+  type, and default sync to code. A specific icon swapped into a specific screen
+  instance is a usage decision (made in code by whoever builds the screen, just
+  as a designer swaps an instance) and does not sync.
+
+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 5 — Naming as contract
+
+Name components deterministically so Figma↔code mapping is automatic: `Button` ↔
+`Button`, `Avatar` ↔ `Avatar`. This is what lets typed-component slots and the
+storybook build resolve the right imports. Same discipline as icon naming —
+without it, components silently diverge between Figma and code.
+
+## Step 6 — Checkpoint and hand off
+
+Update the manifest: add each built component to `components.built`, and record
+its `components.meta[name]` (`status: "draft"`, `updatedAt`) to match the doc
+card. (Finalize to `stable` happens later, in storybook-chromatic-builder.) Ensure
+any component built with the toggle + manual-swap fallback is listed in
+`components.instanceSwapUpgradePending`. Append `component-builder` to
+`completedSkills`.
+
+**Upgrade pass:** if `components.instanceSwapUpgradePending` is non-empty, re-resolve
+publish state (detect-or-ask per `.throughline/references/figma-publishing.md`);
+only when it is **confirmed published** (`figma.libraryPublished` true via a verified
+detect-or-ask, not a stale default) offer to add the typed `INSTANCE_SWAP` dropdowns to
+those components and clear each from the list.
+
+Offer next steps: build the code counterparts and stories
+(storybook-chromatic-builder), or build a single new component end-to-end later
+(the component-pipeline orchestrator).
+
+## What this skill must NOT do
+
+- Never hardcode values that should be token/style bindings — components consume
+  the system.
+- Never generate a redundant show/hide boolean alongside an optional slot prop.
+- Never build a composite before its atomic slot targets exist.
+- Never guess variant matrices — brainstorm and confirm them first.
+- Never claim to publish a Figma library — publishing is a manual user step;
+  instruct and verify only.
+- Never leave components floating on bare canvas — each goes on a token-styled
+  doc card arranged in an auto-layout Frame placed directly on the page (never a
+  Section), with the layout visually validated.
+- Never lay out a component set as scattered variants — the `ComponentSet` is an
+  auto-layout grid where **variants are rows and states are columns**: one row per
+  variant (each `type`, and each `size`, since size is a variant) stepping through
+  states across the columns, size groups stacked vertically (see the standards doc).
+- Never ship a component with only its `default` state — include the full relevant
+  state set (default/hover/focus/active/disabled plus applicable
+  loading/selected/success/error).
+- Never run the component header and the component area together with no division —
+  every doc card segments the header from the component area with a divider line or
+  a distinct header surface.
+- Never invent a house-style focus ring or wrap the control in a padded frame to make
+  room for one — derive the focus state from `project.uiFramework`'s real idiom, built
+  as a drop-shadow effect (filled controls) or an absolutely-positioned ring **child**
+  (transparent controls), per "State handling" in the standards doc.
+- Never rebuild a published/consumed component set with a delete-and-recreate without
+  re-instancing downstream — deleting and recreating a set (e.g. to change the Button's
+  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.
+

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

@@ -0,0 +1,85 @@
+---
+description: "Take a single new component from Figma to fully-built-and-storied code, end to end — build it in Figma, sync any new tokens it introduced, then build its code component and stories. This is an orchestrator that sequences the component-builder, token-sync-layer, and storybook-chromatic-builder skills with a human confirmation between each stage. Use this when the user wants to add a new component to an existing design system, ship a component end-to-end, or run the full new-component flow. Also trigger on \"/new-component\" or when someone says they want one component built all the way through to code. Make sure to use this when the design system foundations already exist and the user wants to add one more component through the whole pipeline."
+alwaysApply: false
+---
+# Component pipeline (orchestrator)
+
+Sequences a single new component through the whole flow: Figma → tokens →
+code/stories. This skill holds **zero domain logic of its own** — it is a
+sequencer that invokes the real skills and gates each stage on a human
+confirmation. All the actual work lives in the skills it calls; this keeps it
+from rotting when those skills improve.
+
+## When to use vs. the individual skills
+
+Use this for **one new component, end to end**, on a system that already has
+foundations (tokens, repo, sync, Storybook). For initial setup, the individual
+skills run directly. This is the "I have a system; add a Tooltip and take it all
+the way to a tested story" flow.
+
+## Prerequisites
+
+Read the manifest. The pipeline assumes foundations exist: tokens built, a repo
+at least `local-git`, sync configured, Storybook initialized. For any missing
+piece, offer to run the relevant skill — but note that if a lot is missing, the
+user probably wants the individual setup skills first, not this orchestrator.
+
+## The sequence (confirm between every stage)
+
+Confirm the goal first: "New `Tooltip` component, right? I'll build it in Figma,
+sync any new tokens, then build the code component and its stories — checking
+with you between each step." Then:
+
+### Stage 1 — Build in Figma (invoke component-builder)
+
+Invoke the `component-builder` rule for this one component: brainstorm its
+variant matrix and slots, build it bound to tokens following the component
+standards, capture its slot contract. **Checkpoint:** show the finished Figma
+component. Get explicit confirmation before continuing.
+
+If the build fails or the user wants changes, stop here — they still have a
+valid (or fixable) Figma component and a clean place to resume. Never push a
+half-built component down the pipeline.
+
+### Stage 2 — Sync new tokens (offer token-sync-layer)
+
+The new component may have introduced new tokens (a new semantic role, a new
+spacing step). Offer: "This component added a couple of new tokens — want me to
+sync them to code now?" If yes, invoke `token-sync-layer` (which lands a
+reviewable PR per its own rules). If the component introduced no new tokens, say
+so and skip. **Checkpoint:** confirm the sync PR before continuing.
+
+### Stage 3 — Build code component + stories (offer storybook-chromatic-builder)
+
+Offer: "Tokens are synced. Build the code component and its stories now?" If yes,
+invoke `storybook-chromatic-builder` for this one component: build the code
+counterpart implementing the captured slot contract, generate its stories
+(subagent-driven), wire Code Connect if available. **Checkpoint:** confirm the
+component renders and stories build. On approval, that skill **finalizes** the
+component — promoting its status from `draft` to `stable` and writing the new
+chip color + last-updated date back into its Figma doc card (its Step 6). Since
+Figma is still connected from stage 1, the card updates live; the chip should no
+longer read `draft` once the pipeline finishes.
+
+## Resumability
+
+Because each stage is gated and invokes a real skill, a failure at any stage
+leaves a clean resume point: the Figma component exists after stage 1, the token
+PR after stage 2, the code/stories after stage 3. The user can stop after any
+stage and pick up later — the manifest reflects what's done.
+
+## After completion
+
+Confirm the component went all the way through. Update nothing the sub-skills
+didn't already update (they own their manifest fields). Note the ongoing loops:
+more components via this pipeline, token changes via `/sync-figma-tokens`.
+
+## What this skill must NOT do
+
+- Never reimplement what the sub-skills do — only sequence them. If you find
+  yourself writing component-building or sync logic here, stop and invoke the
+  real skill instead.
+- Never skip a confirmation between stages — the gates are what make it
+  resumable and prevent half-updated state.
+- Never push a half-built or unconfirmed component to the next stage.
+

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

@@ -0,0 +1,126 @@
+---
+description: "Measure a pre-existing design system before retrofitting it onto tokens — size the code-side color surface and inventory the existing Figma file with verified per-class reads, then compute how semantic the system already is so the retrofit is right-sized. This is a PROCESS skill and the brownfield front door. Use this when retrofitting a design system onto a mature codebase and an already-populated Figma file, when the user wants to audit an existing system, size a retrofit, count existing tokens/variables/bindings, or figure out how much work a migration is. Also trigger when figma-environment-setup detects a brownfield situation (existing repo or populated Figma file), before any building. Make sure to use this whenever someone is converging two mature, drifted artifacts rather than building greenfield."
+alwaysApply: false
+---
+# Design-system audit (brownfield front door)
+
+Measures **both sides** of a pre-existing system so a retrofit can be right-sized,
+before anything is built or changed. It is the brownfield analog of
+`/design-system-status`: where status reports a *local* manifest, this assesses an
+*external, mature* system — a real codebase and an already-populated Figma file.
+
+This is a brownfield skill. **Before doing anything, read**
+`.throughline/references/brownfield-retrofit.md` — especially the
+read-discipline principle (never assert absence without a verified read) and the
+`audit` phase of the safe sequence. Greenfield builds skip this skill entirely.
+
+## Calibrate
+
+Read `user.codingLevel` (`.throughline/references/coding-level.md`) and scale
+explanation accordingly. The audit surfaces grep counts and a `percentSemantic`
+number — for `new` users explain what each means and why it matters (it decides
+rename-vs-rewrite); for `comfortable` users be terse. The measurements are identical
+across levels.
+
+## Prerequisites
+
+Read the manifest. This skill needs Figma connected (`figma.connected: true`) for the
+inventory step, and a repo path for the code-surface step (`workspace.localPath`). If
+Figma isn't connected, offer to run `figma-environment-setup` first. The code-surface
+step works on any repo regardless of `workspace.stage`.
+
+## Step 1 — Size the code surface
+
+Measure how many color decisions live in the codebase. Run the color-usage grep
+scaffold against the user's repo:
+
+```bash
+node .throughline/scripts/grep-color-usage.mjs --root <workspace.localPath>
+```
+
+It counts five categories: SCSS color vars, Tailwind color classes, `Colors.*` JS
+usages, raw hex + `rgba()` literals, and SVG hardcoded fills — producing the
+case-study worklist shape.
+
+**Tune the patterns to the actual repo, and say what you assumed (read discipline +
+§11).** The shipped patterns are *defaults*, not ground truth. Before trusting the
+counts:
+1. Look at the repo's real conventions — open a few SCSS/TS files, check the actual
+   color-variable prefixes (`$primary-*`, `$grey-*`, a custom prefix), the Tailwind
+   color-class names, and whether colors come through a `Colors.*` object or some other
+   accessor.
+2. If the defaults don't fit, write a `--config <patterns.json>` of
+   `{ "<category>": { "files": "<regex>", "pattern": "<regex>" } }` tuned to this repo
+   and re-run with it.
+3. **Report which categories used the assumed defaults vs. a tuned pattern** — never
+   present default-pattern counts as if they were measured. The script prints this; pass
+   it through to the user so partial coverage is visible, not hidden.
+
+**Don't assume the stack.** The categories are color-specific but framework-agnostic; a
+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 2 — Inventory the Figma file (verified per-class reads)
+
+Variables, text styles, and effect/paint styles are **different surfaces** — read each
+independently and report "none" only for the class whose own read came back empty
+(read discipline, fixes B2). Before counting variables, ensure all pages are loaded
+(`await figma.loadAllPagesAsync()`); treat a `0` on first read as suspect and re-read
+before reporting (fixes B1).
+
+- **Variables** — `figma_get_variables` (handles `dynamic-page`, resolves aliases).
+  Record the count.
+- **Bindings** — run the binding-survival audit snippet in
+  `.throughline/references/figma-scripting.md` to count consuming bindings.
+  This is the load-bearing number: it's what a careless rename would destroy.
+- **Text styles** — `figma_get_text_styles`. Record the count.
+- **Effect/paint styles** — `figma_get_styles`. Record the count.
+- **Modes** — record the mode names per collection (e.g. `["Light", "Dark"]`).
+
+Never report a count you didn't read. If a read genuinely returns empty after a
+reliable load, that's a real `0`; if it's suspect, re-read or ask the user once and
+persist — never guess.
+
+## Step 3 — Compute "% semantic"
+
+From the inventory, estimate how much of the existing system is already **semantic**
+(named by role — `text/default`, `surface/raised`) vs. **raw/primitive** (named by
+value — `grey-900`, or bare hex). Report it as an integer 0–100 (`audit.percentSemantic`).
+
+This single number right-sizes the retrofit: a largely-semantic system (~90%) is a
+**rename-in-place + cleanup** job; a low-semantic one is closer to a **rewrite**.
+Surface it early and plainly — "you're ~90% semantic, so this is mostly renames and a
+cleanup, not a rebuild" — so the user calibrates effort before committing.
+
+## Step 4 — Write the manifest and recommend the next step
+
+Write the `audit` section (this skill owns it):
+
+- `codeSurface` — the per-category counts from Step 1 (keys vary by what the repo uses;
+  omit categories that don't apply rather than reporting a misleading `0`).
+- `figmaInventory` — `{ variables, bindings, textStyles, effectStyles, modes }` from
+  Step 2's verified reads.
+- `percentSemantic` — the integer from Step 3.
+- `ranAt` — the current ISO timestamp.
+
+Set `tokens.intakeMode: "retrofit"` (this skill establishes the brownfield path — it
+owns this transition). Append `design-system-audit` to `completedSkills`.
+
+Then recommend the next step:
+- 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
+  reads this `audit` section to seed its rows).
+
+## What this skill must NOT do
+
+- Never build, rename, or delete anything — this is a **measurement** skill. Changes
+  belong to `token-builder` (refine), the retrofit phases, and cleanup.
+- Never report a count without a verified read (read discipline). An unexpectedly-empty
+  read is a suspected error, not ground truth.
+- Never present default grep patterns as measured truth — say what was assumed.
+- Never assume the case-study stack (Tailwind/SCSS/Chromatic). Detect what the repo
+  actually uses and degrade gracefully.
+- Never write another skill's manifest fields (e.g. `tokenCrosswalk`, `retrofit.phase`).
+- Never overwrite `workspace.origin` — it is immutable after intake.
+