@radicool/throughline 0.12.0

package/adapters/generic/commands/start.md

@@ -0,0 +1,22 @@
+This is the **first step** for building a design system with ThroughLine. The
+user invoked it explicitly, so begin immediately — do **not** invoke any
+brainstorming or planning skill first. There is nothing to brainstorm until the
+environment exists: the local working folder must be created and Figma must be
+connected before any design work can happen.
+
+Invoke the `figma-environment-setup` skill now and follow it exactly. It will:
+
+1. Locate or create the project directory and scan what's already there.
+2. Create the local working folder and write the `design-system.json` manifest.
+3. Connect the agent to Figma and verify the connection.
+
+If `design-system.json` already exists in this folder, the setup skill will
+detect it and route the user to the right next step rather than starting over —
+let it make that call. That routing now covers brownfield systems too: an
+existing/mature repo or populated Figma file is sent to `design-system-audit`
+first, and an in-progress retrofit (`retrofit.phase` set) resumes at its phase
+via `retrofit-planner` — the setup skill makes that call.
+
+Scale all explanation to the user's coding level. Assume they may be
+design-fluent but new to developer tooling, terminals, and API tokens.
+

package/adapters/generic/commands/sync-figma-tokens.md

@@ -0,0 +1,22 @@
+Re-run the token sync pipeline to catch any updates made in Figma.
+
+Follow the `token-sync-layer` skill's pipeline using the settings already
+recorded in `design-system.json` (`sync.platforms`, `figma.mechanism`,
+`figma.fileKey`) — don't re-ask configuration that's already set. Specifically:
+
+1. Verify Figma is connected (cheap liveness read); if not, offer
+   `figma-environment-setup`.
+2. Re-extract Figma variables to DTCG JSON.
+3. Rebuild outputs through Style Dictionary for every platform in
+   `sync.platforms`.
+4. Run full-regeneration with **rename detection** — diff against the previous
+   output, flag probable renames (vanished + reappeared with identical
+   `$value`/`$type`) and plain deletions.
+5. Open a **reviewable PR** (or a reviewed branch diff if the repo is only
+   `local-git`) summarizing added / changed / deleted / probable-renames. Never
+   write silently.
+6. Update `sync.lastRun` and `tokens.lastSync` in the manifest.
+
+Scale explanation to `user.codingLevel`. This is the recurring loop of the whole
+system: tokens change in Figma → `/sync-figma-tokens` → review PR → merge.
+

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

@@ -0,0 +1,272 @@
+# 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/generic/skills/component-pipeline/SKILL.md

@@ -0,0 +1,81 @@
+# 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` skill 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/generic/skills/design-system-audit/SKILL.md

@@ -0,0 +1,122 @@
+# 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.
+