@event4u/agent-config 16.4.0 → 17.0.0

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -65,280 +65,20 @@ Design starts from project truth, not generic aesthetic memory.
 
 ## Procedure: Audit the existing UI surface
 
-### 0. Inspect stack and input
-
-1. Read `state.stack.frontend` — set by `scripts/work_engine/stack/detect.ts` (one of `blade-livewire-flux`, `react-shadcn`, `vue`, `plain`).
-2. Read `state.input` — the request being processed. The audit must answer: "what already exists that is similar to this request?"
-
-### 1. Enumerate components and templates
-
-| Stack | Where to look |
-|---|---|
-| `blade-livewire-flux` | `resources/views/components/`, `resources/views/livewire/`, `resources/views/partials/`, `resources/views/layouts/`, `app/View/Components/`, `app/Livewire/` |
-| `react-shadcn` | `components/`, `app/components/`, `src/components/`, `src/app/(routes)/`, plus any `app/**/page.tsx` for Next.js |
-| `vue` | `resources/js/components/`, `src/components/`, `pages/` |
-| `plain` | `resources/views/`, plus any `*.html` under `public/` |
-
-Capture each component/template as:
-`{path, name, kind: component|view|style|page, exports?: [props]}`.
-
-The `kind` set is the one `agent-config ui:audit` actually emits — its single
-definition is `AUDIT_KINDS` in `src/cli/commands/uiAudit.ts`, and a test asserts
-this line against that constant rather than restating it. It read
-`page|partial|component|layout` until 2026-08-26; only two of those four values
-existed in the code, so an artefact written by the command was being read here
-against a contract it did not satisfy.
-
-`partial` and `layout` are not in the set. Neither has an operational definition
-that survives contact with a real tree, and adding a branch for a category
-nobody can test is how the previous mismatch happened.
-
-`view` is the **Blade** classification — `*.blade.php` and `resources/views/`.
-It reads zero in a JavaScript tree by construction, which is not the same as
-unused.
-
-### 1b. Detect the component-granularity taxonomy the project already chose
-
-```bash
-npx tsx scripts/work_engine/taxonomy/detect.ts   # or import detect_component_taxonomy(root)
-```
-
-Returns the project's **own** tier names joined with `/` — `atoms/molecules/organisms`, `primitives/patterns/features`, whatever it actually uses — or `none`. Record it as `state.ui_audit.component_taxonomy`, with `state.ui_audit.component_root` for where the components live. `none` is a real answer, and leaves every downstream step behaving exactly as it did before this detection existed. Never write a taxonomy the project does not evidence, and never "tidy" a layout into one — this step *finds* the project's structure, it never supplies one. Detection rules, the declared-beats-inferred precedence and the two collision floors: [`references/component-taxonomy-detection.md`](references/component-taxonomy-detection.md).
-
-### 2. Identify the design system
-
-Detect markers, in order. **Stop at the first match** — projects rarely run more than one design system.
-
-| Marker | Signal | Where |
-|---|---|---|
-| Flux | `livewire/flux` in `composer.json`, `<flux:*>` tags in views | `composer.json`, grep `resources/views` |
-| shadcn/ui | `components.json` exists at the **workspace** root — the package that owns it; in a monorepo this is never the repository root | `components.json` |
-| Headless UI | `@headlessui/react` or `@headlessui/vue` in `package.json` | `package.json` |
-| Radix | `@radix-ui/*` in `package.json` (without shadcn marker) | `package.json` |
-| Material/Chakra/Mantine/Ant | their package names in `package.json` | `package.json` |
-| Custom / none | none of the above match | — |
-
-### 3. Detect design tokens
-
-Write into `state.ui_audit.design_tokens` (object, never null — empty object is fine):
-
-| Source | What to extract |
-|---|---|
-| **`tailwind-v3`** (`axes.css`) — `tailwind.config.{js,ts,cjs,mjs}` | `theme.colors`, `theme.spacing`, `theme.fontFamily`, `theme.extend.*` |
-| **`tailwind-v4`** (`axes.css`) — the `@theme` block in the entry CSS; **no config file exists**, and `components.json` `"tailwind": {"config": ""}` is the marker | every `--token: value` declared inside `@theme` / `@theme inline` |
-| `:root { --... }` blocks in `resources/css/`, `app/globals.css`, `src/app/globals.css` | every `--token-name: value` pair |
-| `theme.json` / `tokens.json` (any depth) | flat or nested token tree |
-| `app/css/variables.css`, `assets/scss/_tokens.scss` | SCSS `$var: value` and CSS custom properties |
-| **A supplied `design-system.json`** (handed over with a provided artifact) | `colors`, `typography`, `spacing`, `radius`, `shadow`, **and `motion`** (`durations`, `easings`) — read as the answer, never re-derived |
-| **A supplied artifact's own `:root { --… }` / inline `<style>`** (the handover file itself, e.g. `design.html`) | every `--token-name: value` pair, when no `design-system.json` accompanies it |
-
-Group output by category: `colors`, `spacing`, `radius`, `font`, `shadow`, `breakpoint`, `other`.
-
-**Branch on the axis, do not probe for a config file.** `detect_stack()` emits
-`axes.css` as `tailwind-v3` or `tailwind-v4`
-(`work_engine/stack/detect.ts:521-524`); reading it is how this step and
-`react-shadcn-ui` § Gotcha stay on the same key. Absence of
-`tailwind.config.*` is v4's normal state, never a missing file.
-
-**Artifact-sourced tokens stay distinguishable from project tokens.** Every
-group carries a `source` — `project` for the first four rows, `artifact` for the
-last two — because the mapping between them is the thing a port has to keep
-visible. Collapsing them loses the answer to "did this value come from what the
-user handed me, or from what the repo already had?", and that is exactly the
-question the apply coverage report has to answer per item. The two sets may
-disagree; when they do, surface the conflict rather than merging it (a supplied
-spec outranks house taste, but not a registered brand token — see
-[`brand-source-of-truth`](../../rules/brand-source-of-truth.md)).
-
-`motion` is new here: the block has existed in the `design-system.json` schema
-since capture shipped and **nothing consumed it**. On the port branch it is
-read, so easing and duration stop being values the brief silently regenerates.
-
-### 4. Detect shadcn inventory (only when `state.stack.frontend == "react-shadcn"`)
-
-Read `components.json` for the registered style + base color, then read the `package.json` **of the scope root** — `state.stack.scope_root`, relative to the project root, empty when the project root *is* the scope — for `@radix-ui/*` or the unified `radix-ui` package, plus any locally vendored `components/ui/*.tsx` files. In a monorepo the repository root carries neither the marker nor the dependency, so reading it finds nothing. Write into `state.ui_audit.shadcn_inventory`:
-
-```
-{
-  version: <from package.json shadcn registry CLI version, or null>,
-  style: "default" | "new-york" | <other>,
-  base_color: "slate" | "zinc" | ...,
-  primitives: ["Button", "Dialog", "Form", "Table", ...],   // names of files in components/ui/
-  installed_radix: ["@radix-ui/react-dialog", ...]          // raw radix list
-}
-```
-
-### 4b. Prefer a live Storybook read over the hand-read inventory — when one is running
-
-When the project carries `@storybook/addon-mcp` **and** a Storybook is running, query it
-instead of reading files: `docs-list` for the inventory, then `docs-show` for the components
-that matter. **The live read wins; the hand-read inventory of step 4 is the fallback and is
-never removed** — an agent that cannot reach a running Storybook must still be able to
-inventory the library. The channel disappearing is normal, not an error.
-
-**The names are version-bound, and these are the current ones.** Own derivation, from a
-throwaway `npm install` on 2026-09-13, not from any document: at `@storybook/addon-mcp@10.6.0`
-the docs tools are registered by `storybook`'s own `createDocsToolset` under the method ids
-`docs.list` / `docs.show` / `docs.showStory`, and `toMcpToolName` renders those as `docs-list`,
-`docs-show` and `docs-show-story`. The older `list-all-documentation` / `get-documentation` were
-the literal names at `@storybook/addon-mcp@0.7.0` (via `@storybook/mcp@0.8.0`); at 10.6.0 they
-survive only as the tools' human-readable **titles**. There is no 10.5.x of the addon — it goes
-0.7.0 → 10.6.0 — so a project on the current scaffold gets the `docs-*` names. If a live
-`tools/list` disagrees, the live read wins over this paragraph.
-
-**React-only while the toolset is in preview.** Storybook's own MCP FAQ (docs **10.5**,
-`docs/ai/mcp/overview` § FAQ) states the documentation toolset supports React only during
-preview, so Vue, Angular, and Web Components take the file-read path. Stated here rather than
-discovered at runtime, because the failure otherwise looks like a broken MCP server.
-
-Discipline for what the live read returns is [`storybook-workshop`](../storybook-workshop/SKILL.md)'s
-— in particular: never use a prop the manifest does not document, and fetch the project's
-story instructions before writing a story.
-
-### 5. List reusable patterns
-
-Categorize what already exists. Empty arrays are valid, never omit the keys.
-
-```
-state.ui_audit.patterns = {
-  forms: [<component path:str>, ...],     // any component with <form>, useForm, <flux:input>, <Input> + <Button type=submit>
-  tables: [...],                          // <table>, <flux:table>, DataTable, headless table primitives
-  modals: [...],                          // <flux:modal>, <Dialog>, AlertDialog, Sheet
-  empty_states: [...],                    // components matching grep "no results"|"empty"|"keine"|"nothing yet"
-  navigation: [...],                      // sidebar, breadcrumb, tabs
-  data_display: [...]                     // cards, lists, stat tiles
-}
-```
-
-### 6. Match candidates for the current input
-
-For each item in `state.ui_audit.components`, score similarity to `state.input.data` (fuzzy on filename + props/slots + co-occurring terms). Keep top 5 with `score >= 0.3`. Write into `state.ui_audit.candidates`:
-
-```
-[{path, name, score, reason: "matches 'settings' + 'toggle' in props"}, ...]
-```
-
-If `candidates` is empty, the user is building net-new. That is normal — record the empty list, do not halt.
-
-#### 6b. Conformance gate — when a provided artifact is the spec
-
-Similarity above is scored against `state.input.data`. That answers *"is this
-component like the thing being asked for"* and it does **not** answer *"does
-this component satisfy the artifact"* — which is a different question with a
-different answer, because a candidate can be an excellent name-and-props match
-and still use the wrong type scale, the wrong control, or a colour the artifact
-never states. Until this step existed nothing anywhere asked the second
-question, while `ui-audit-gate` carried *"reuse
-beats duplication"* as unqualified prose. Reused on an artifact port, an
-unconforming candidate is a fidelity deviation dressed as good hygiene.
-
-So when a provided design artifact is the spec
-([`design-fidelity`](../../rules/design-fidelity.md)), each candidate carries a
-**conformance verdict** alongside its score, and reuse is conditional on it:
-
-```
-[{path, name, score, reason,
-  conformance: {verdict: "conforms|deviates|unknown",
-                dimensions: {structure, values, behaviour, responsive},
-                refused_by: "values"}}, ...]
-```
-
-- **`conforms`** → reuse it. This is the ordinary case and nothing changed.
-- **`deviates`** → do **not** reuse silently. Name the dimension that refused
-  it — *"`Card` deviates on `values`: type scale 14/20 against the artifact's
-  16/24"* — and surface reuse-with-adaptation versus build-new as a choice.
-  A bare "candidate rejected" is not a discharge; the caller cannot act on it.
-- **`unknown`** → the candidate was not scored against the artifact (no
-  extraction yet, or a subtree the audit could not read). Treat as `deviates`
-  for the purpose of not reusing silently, and say which of the two it is —
-  "did not conform" and "was not checked" are different facts.
-
-**And the decision moves after extraction, not before it.** A conformance
-verdict needs the artifact's own values, so a reuse decision taken before
-extraction is taken without the evidence that decides it. Where the run has an
-artifact, order is: extract → audit → score → conform → decide. The unqualified
-reuse-first ordering stands only where there is no artifact to conform to.
-
-**Scope:** this is a gate on REUSE, not a license to rewrite the incumbent. A
-candidate that deviates is left alone; the choice is whether *this* work builds
-on it.
-
-### 7. Greenfield branch
-
-If **all** are true:
-- `state.ui_audit.components` is empty
-- `state.ui_audit.design_system == "custom-or-none"`
-- `state.ui_audit.design_tokens` is empty (no Tailwind config customizations, no `:root`)
-
-then set `state.ui_audit.greenfield = true` and emit a halt:
-
-```
-> No existing UI surface detected — this looks like greenfield.
->
-> 1. Scaffold a minimal token set + a base component primitive folder
->    before building (recommended for projects with >1 planned screen)
-> 2. Proceed bare with Tailwind defaults (recommended for one-off prototypes)
-> 3. Point me at an external design-system reference (URL or file)
-> 4. Scaffold + a granularity convention — as 1, and new components go into
->    named granularity folders you pick the names for; rename or drop it later
->    and nothing here objects
-
-**Recommendation: 1 — Scaffold tokens + primitives** — even one extra screen
-benefits from a shared base; the scaffold cost is ~10 min and saves
-re-doing every primitive on screen 2. Caveat: flip to 2 if this is a
-demo or single-page prototype that will not grow.
-```
-
-Option 4 is an **offer**, and the only one made anywhere: a project that already exists is never asked (§ 1b reads what it chose), and a greenfield project picking any other number has declined terminally, because the halt is a no-op once any decision is recorded. It stays one more number in the same block rather than a second question — a single number still answers it, which is what the reply-shape rule requires.
-
-Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `bare` | `external_reference` | `granularity_convention`). Re-running the skill on the same state-file with `greenfield_decision` set is a no-op for the halt (audit findings stay). `granularity_convention` takes the same scaffold path as `scaffold` — it adds the convention, it does not replace the scaffolding.
-
-### 8. (Optional) Capture an a11y baseline
-
-The R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline`
-when present; the review gate then filters incoming
-`state.ui_review.a11y.violations` against it so pre-existing
-violations stay informational and only NEW or CHANGED entries block
-the polish loop. Without a baseline the gate sees every violation as
-actionable — fine for greenfield, noisy for legacy surfaces.
-
-Capture the baseline when:
-
-- The audit covers components with known a11y debt the project does
-  not intend to fix in this run (legacy templates, third-party
-  embeds, vendor widgets).
-- The user says "don't block on existing a11y issues" or similar.
-
-Skip the baseline (omit the key, leave `state.ui_audit.a11y_baseline`
-unset) when:
-
-- The surface is greenfield — the review gate should treat every
-  violation as new.
-- The project's a11y posture is "zero known violations" and any
-  finding is by definition actionable.
-
-Shape (each entry must carry at least `rule` + `selector`; severity
-is optional but recommended so the review gate's severity-floor
-filter behaves the same on replay):
-
-```
-state.ui_audit.a11y_baseline = [
-  {rule: "color-contrast", selector: ".legacy-tab", severity: "moderate"},
-  {rule: "label",          selector: "form#search input[type=search]"},
-  ...
-]
-```
-
-Producer parity: the review skill that writes
-`state.ui_review.a11y.violations` MUST use the same `(rule, selector)`
-shape, otherwise the engine's de-dup will miss matches and pre-existing
-violations will surface as new findings on every run.
-
-### 9. Validate and write findings
-
-1. Verify every key in the **Output format** below is present in `state.ui_audit` (empty arrays/objects allowed; `null` only for `shadcn_inventory` outside the react-shadcn stack).
-2. Verify `state.ui_audit.greenfield == true` implies `state.ui_audit.greenfield_decision` is set.
-3. Write the full object back into the state-file. Audit completes with outcome `done` — the dispatcher's audit gate now passes.
+The order is held by [`procedure.yaml`](procedure.yaml). Open the steps one at a time, in order, and start a step only after the one before it has met its exit. A `judgement` exit is sequenced, not verified: state what you decided before moving on.
+
+1. [0. Inspect stack and input](references/steps/00-inspect-stack-and-input.md) — exit: `judgement`
+2. [1. Enumerate components and templates](references/steps/01-enumerate-components.md) — exit: `check: ui-audit-components-in-tree`
+3. [1b. Detect the component-granularity taxonomy](references/steps/01b-detect-component-taxonomy.md) — exit: `check: ui-audit-taxonomy-root-in-tree`
+4. [2. Identify the design system](references/steps/02-identify-design-system.md) — exit: `judgement`
+5. [3. Detect design tokens](references/steps/03-detect-design-tokens.md) — exit: `judgement`
+6. [4. Detect shadcn inventory (react-shadcn only)](references/steps/04-detect-shadcn-inventory.md) — exit: `judgement`
+7. [4b. Prefer a live Storybook read when one is running](references/steps/04b-live-storybook-read.md) — exit: `judgement`
+8. [5. List reusable patterns](references/steps/05-list-reusable-patterns.md) — exit: `check: ui-audit-patterns-in-tree`
+9. [6. Match candidates for the current input (with the 6b conformance gate)](references/steps/06-match-candidates.md) — exit: `check: ui-audit-candidates-from-inventory`
+10. [7. Greenfield branch](references/steps/07-greenfield-branch.md) — exit: `check: ui-audit-greenfield-consistent`
+11. [8. (Optional) Capture an a11y baseline](references/steps/08-a11y-baseline.md) — exit: `judgement`
+12. [9. Validate and write findings](references/steps/09-validate-and-write.md) — exit: `check: ui-audit-complete`
 
 ## Section index — load on demand
 
@@ -347,8 +87,6 @@ Load on demand once the audit needs the pitfall catalog:
 - [`references/anti-slop-cross-reference.md`](references/anti-slop-cross-reference.md) — Anti-slop cross-reference
 - [`references/component-taxonomy-detection.md`](references/component-taxonomy-detection.md) — Component-taxonomy detection rules
 
-- [`references/output-and-pitfalls.md`](references/output-and-pitfalls.md) — Output format · Gotcha · Anti-slop cross-reference
-
 ## Output format
 
 1. **`state.ui_audit.components`** — array of component/template descriptors (path, name, kind, exports)

package/dist/agent-src/skills/existing-ui-audit/procedure.yaml

@@ -0,0 +1,44 @@
+schema_version: 1
+brief:
+  goal: Inventory the existing UI surface into state.ui_audit so design and apply reuse what exists.
+  inputs:
+  - state.stack.frontend
+  - state.input
+  done_when: state.ui_audit carries every Output format key and the tree agrees with its inventory.
+steps:
+- id: inspect-stack-and-input
+  file: references/steps/00-inspect-stack-and-input.md
+  exit: judgement
+- id: enumerate-components
+  file: references/steps/01-enumerate-components.md
+  exit: 'check: ui-audit-components-in-tree'
+- id: detect-component-taxonomy
+  file: references/steps/01b-detect-component-taxonomy.md
+  exit: 'check: ui-audit-taxonomy-root-in-tree'
+- id: identify-design-system
+  file: references/steps/02-identify-design-system.md
+  exit: judgement
+- id: detect-design-tokens
+  file: references/steps/03-detect-design-tokens.md
+  exit: judgement
+- id: detect-shadcn-inventory
+  file: references/steps/04-detect-shadcn-inventory.md
+  exit: judgement
+- id: live-storybook-read
+  file: references/steps/04b-live-storybook-read.md
+  exit: judgement
+- id: list-reusable-patterns
+  file: references/steps/05-list-reusable-patterns.md
+  exit: 'check: ui-audit-patterns-in-tree'
+- id: match-candidates
+  file: references/steps/06-match-candidates.md
+  exit: 'check: ui-audit-candidates-from-inventory'
+- id: greenfield-branch
+  file: references/steps/07-greenfield-branch.md
+  exit: 'check: ui-audit-greenfield-consistent'
+- id: a11y-baseline
+  file: references/steps/08-a11y-baseline.md
+  exit: judgement
+- id: validate-and-write
+  file: references/steps/09-validate-and-write.md
+  exit: 'check: ui-audit-complete'

package/dist/agent-src/skills/existing-ui-audit/references/anti-slop-cross-reference.md

@@ -24,7 +24,7 @@ wrong about one of them:
 
 A corrective direction change against a supplied spec is not a design
 improvement, it is overriding a decision the user already made — the failure
-[`design-fidelity`](../../rules/design-fidelity.md) exists to prevent, arriving
+[`design-fidelity`](../../../rules/design-fidelity.md) exists to prevent, arriving
 through the audit's side door. Precedence and its exact scope:
 [`design-fidelity-mechanics`](../../../guidelines/design-fidelity-mechanics.md)
 § Provided-artifact precedence. Where the two sources disagree, surface the

package/dist/agent-src/skills/existing-ui-audit/references/steps/00-inspect-stack-and-input.md

@@ -0,0 +1,4 @@
+# 0. Inspect stack and input
+
+1. Read `state.stack.frontend` — set by `scripts/work_engine/stack/detect.ts` (one of `blade-livewire-flux`, `react-shadcn`, `vue`, `plain`).
+2. Read `state.input` — the request being processed. The audit must answer: "what already exists that is similar to this request?"

package/dist/agent-src/skills/existing-ui-audit/references/steps/01-enumerate-components.md

@@ -0,0 +1,26 @@
+# 1. Enumerate components and templates
+
+| Stack | Where to look |
+|---|---|
+| `blade-livewire-flux` | `resources/views/components/`, `resources/views/livewire/`, `resources/views/partials/`, `resources/views/layouts/`, `app/View/Components/`, `app/Livewire/` |
+| `react-shadcn` | `components/`, `app/components/`, `src/components/`, `src/app/(routes)/`, plus any `app/**/page.tsx` for Next.js |
+| `vue` | `resources/js/components/`, `src/components/`, `pages/` |
+| `plain` | `resources/views/`, plus any `*.html` under `public/` |
+
+Capture each component/template as:
+`{path, name, kind: component|view|style|page, exports?: [props]}`.
+
+The `kind` set is the one `agent-config ui:audit` actually emits — its single
+definition is `AUDIT_KINDS` in `src/cli/commands/uiAudit.ts`, and a test asserts
+this line against that constant rather than restating it. It read
+`page|partial|component|layout` until 2026-08-26; only two of those four values
+existed in the code, so an artefact written by the command was being read here
+against a contract it did not satisfy.
+
+`partial` and `layout` are not in the set. Neither has an operational definition
+that survives contact with a real tree, and adding a branch for a category
+nobody can test is how the previous mismatch happened.
+
+`view` is the **Blade** classification — `*.blade.php` and `resources/views/`.
+It reads zero in a JavaScript tree by construction, which is not the same as
+unused.

package/dist/agent-src/skills/existing-ui-audit/references/steps/01b-detect-component-taxonomy.md

@@ -0,0 +1,7 @@
+# 1b. Detect the component-granularity taxonomy the project already chose
+
+```bash
+npx tsx scripts/work_engine/taxonomy/detect.ts   # or import detect_component_taxonomy(root)
+```
+
+Returns the project's **own** tier names joined with `/` — `atoms/molecules/organisms`, `primitives/patterns/features`, whatever it actually uses — or `none`. Record it as `state.ui_audit.component_taxonomy`, with `state.ui_audit.component_root` for where the components live. `none` is a real answer, and leaves every downstream step behaving exactly as it did before this detection existed. Never write a taxonomy the project does not evidence, and never "tidy" a layout into one — this step *finds* the project's structure, it never supplies one. Detection rules, the declared-beats-inferred precedence and the two collision floors: [`references/component-taxonomy-detection.md`](../component-taxonomy-detection.md).

package/dist/agent-src/skills/existing-ui-audit/references/steps/02-identify-design-system.md

@@ -0,0 +1,12 @@
+# 2. Identify the design system
+
+Detect markers, in order. **Stop at the first match** — projects rarely run more than one design system.
+
+| Marker | Signal | Where |
+|---|---|---|
+| Flux | `livewire/flux` in `composer.json`, `<flux:*>` tags in views | `composer.json`, grep `resources/views` |
+| shadcn/ui | `components.json` exists at the **workspace** root — the package that owns it; in a monorepo this is never the repository root | `components.json` |
+| Headless UI | `@headlessui/react` or `@headlessui/vue` in `package.json` | `package.json` |
+| Radix | `@radix-ui/*` in `package.json` (without shadcn marker) | `package.json` |
+| Material/Chakra/Mantine/Ant | their package names in `package.json` | `package.json` |
+| Custom / none | none of the above match | — |

package/dist/agent-src/skills/existing-ui-audit/references/steps/03-detect-design-tokens.md

@@ -0,0 +1,35 @@
+# 3. Detect design tokens
+
+Write into `state.ui_audit.design_tokens` (object, never null — empty object is fine):
+
+| Source | What to extract |
+|---|---|
+| **`tailwind-v3`** (`axes.css`) — `tailwind.config.{js,ts,cjs,mjs}` | `theme.colors`, `theme.spacing`, `theme.fontFamily`, `theme.extend.*` |
+| **`tailwind-v4`** (`axes.css`) — the `@theme` block in the entry CSS; **no config file exists**, and `components.json` `"tailwind": {"config": ""}` is the marker | every `--token: value` declared inside `@theme` / `@theme inline` |
+| `:root { --... }` blocks in `resources/css/`, `app/globals.css`, `src/app/globals.css` | every `--token-name: value` pair |
+| `theme.json` / `tokens.json` (any depth) | flat or nested token tree |
+| `app/css/variables.css`, `assets/scss/_tokens.scss` | SCSS `$var: value` and CSS custom properties |
+| **A supplied `design-system.json`** (handed over with a provided artifact) | `colors`, `typography`, `spacing`, `radius`, `shadow`, **and `motion`** (`durations`, `easings`) — read as the answer, never re-derived |
+| **A supplied artifact's own `:root { --… }` / inline `<style>`** (the handover file itself, e.g. `design.html`) | every `--token-name: value` pair, when no `design-system.json` accompanies it |
+
+Group output by category: `colors`, `spacing`, `radius`, `font`, `shadow`, `breakpoint`, `other`.
+
+**Branch on the axis, do not probe for a config file.** `detect_stack()` emits
+`axes.css` as `tailwind-v3` or `tailwind-v4`
+(`work_engine/stack/detect.ts:521-524`); reading it is how this step and
+`react-shadcn-ui` § Gotcha stay on the same key. Absence of
+`tailwind.config.*` is v4's normal state, never a missing file.
+
+**Artifact-sourced tokens stay distinguishable from project tokens.** Every
+group carries a `source` — `project` for the first four rows, `artifact` for the
+last two — because the mapping between them is the thing a port has to keep
+visible. Collapsing them loses the answer to "did this value come from what the
+user handed me, or from what the repo already had?", and that is exactly the
+question the apply coverage report has to answer per item. The two sets may
+disagree; when they do, surface the conflict rather than merging it (a supplied
+spec outranks house taste, but not a registered brand token — see
+[`brand-source-of-truth`](../../../../rules/brand-source-of-truth.md)).
+
+`motion` is new here: the block has existed in the `design-system.json` schema
+since capture shipped and **nothing consumed it**. On the port branch it is
+read, so easing and duration stop being values the brief silently regenerates.

package/dist/agent-src/skills/existing-ui-audit/references/steps/04-detect-shadcn-inventory.md

@@ -0,0 +1,13 @@
+# 4. Detect shadcn inventory (only when `state.stack.frontend == "react-shadcn"`)
+
+Read `components.json` for the registered style + base color, then read the `package.json` **of the scope root** — `state.stack.scope_root`, relative to the project root, empty when the project root *is* the scope — for `@radix-ui/*` or the unified `radix-ui` package, plus any locally vendored `components/ui/*.tsx` files. In a monorepo the repository root carries neither the marker nor the dependency, so reading it finds nothing. Write into `state.ui_audit.shadcn_inventory`:
+
+```
+{
+  version: <from package.json shadcn registry CLI version, or null>,
+  style: "default" | "new-york" | <other>,
+  base_color: "slate" | "zinc" | ...,
+  primitives: ["Button", "Dialog", "Form", "Table", ...],   // names of files in components/ui/
+  installed_radix: ["@radix-ui/react-dialog", ...]          // raw radix list
+}
+```

package/dist/agent-src/skills/existing-ui-audit/references/steps/04b-live-storybook-read.md

@@ -0,0 +1,26 @@
+# 4b. Prefer a live Storybook read over the hand-read inventory — when one is running
+
+When the project carries `@storybook/addon-mcp` **and** a Storybook is running, query it
+instead of reading files: `docs-list` for the inventory, then `docs-show` for the components
+that matter. **The live read wins; the hand-read inventory of step 4 is the fallback and is
+never removed** — an agent that cannot reach a running Storybook must still be able to
+inventory the library. The channel disappearing is normal, not an error.
+
+**The names are version-bound, and these are the current ones.** Own derivation, from a
+throwaway `npm install` on 2026-09-13, not from any document: at `@storybook/addon-mcp@10.6.0`
+the docs tools are registered by `storybook`'s own `createDocsToolset` under the method ids
+`docs.list` / `docs.show` / `docs.showStory`, and `toMcpToolName` renders those as `docs-list`,
+`docs-show` and `docs-show-story`. The older `list-all-documentation` / `get-documentation` were
+the literal names at `@storybook/addon-mcp@0.7.0` (via `@storybook/mcp@0.8.0`); at 10.6.0 they
+survive only as the tools' human-readable **titles**. There is no 10.5.x of the addon — it goes
+0.7.0 → 10.6.0 — so a project on the current scaffold gets the `docs-*` names. If a live
+`tools/list` disagrees, the live read wins over this paragraph.
+
+**React-only while the toolset is in preview.** Storybook's own MCP FAQ (docs **10.5**,
+`docs/ai/mcp/overview` § FAQ) states the documentation toolset supports React only during
+preview, so Vue, Angular, and Web Components take the file-read path. Stated here rather than
+discovered at runtime, because the failure otherwise looks like a broken MCP server.
+
+Discipline for what the live read returns is [`storybook-workshop`](../../../storybook-workshop/SKILL.md)'s
+— in particular: never use a prop the manifest does not document, and fetch the project's
+story instructions before writing a story.

package/dist/agent-src/skills/existing-ui-audit/references/steps/05-list-reusable-patterns.md

@@ -0,0 +1,14 @@
+# 5. List reusable patterns
+
+Categorize what already exists. Empty arrays are valid, never omit the keys.
+
+```
+state.ui_audit.patterns = {
+  forms: [<component path:str>, ...],     // any component with <form>, useForm, <flux:input>, <Input> + <Button type=submit>
+  tables: [...],                          // <table>, <flux:table>, DataTable, headless table primitives
+  modals: [...],                          // <flux:modal>, <Dialog>, AlertDialog, Sheet
+  empty_states: [...],                    // components matching grep "no results"|"empty"|"keine"|"nothing yet"
+  navigation: [...],                      // sidebar, breadcrumb, tabs
+  data_display: [...]                     // cards, lists, stat tiles
+}
+```

package/dist/agent-src/skills/existing-ui-audit/references/steps/06-match-candidates.md

@@ -0,0 +1,52 @@
+# 6. Match candidates for the current input
+
+For each item in `state.ui_audit.components`, score similarity to `state.input.data` (fuzzy on filename + props/slots + co-occurring terms). Keep top 5 with `score >= 0.3`. Write into `state.ui_audit.candidates`:
+
+```
+[{path, name, score, reason: "matches 'settings' + 'toggle' in props"}, ...]
+```
+
+If `candidates` is empty, the user is building net-new. That is normal — record the empty list, do not halt.
+
+## 6b. Conformance gate — when a provided artifact is the spec
+
+Similarity above is scored against `state.input.data`. That answers *"is this
+component like the thing being asked for"* and it does **not** answer *"does
+this component satisfy the artifact"* — which is a different question with a
+different answer, because a candidate can be an excellent name-and-props match
+and still use the wrong type scale, the wrong control, or a colour the artifact
+never states. Until this step existed nothing anywhere asked the second
+question, while `ui-audit-gate` carried *"reuse
+beats duplication"* as unqualified prose. Reused on an artifact port, an
+unconforming candidate is a fidelity deviation dressed as good hygiene.
+
+So when a provided design artifact is the spec
+([`design-fidelity`](../../../../rules/design-fidelity.md)), each candidate carries a
+**conformance verdict** alongside its score, and reuse is conditional on it:
+
+```
+[{path, name, score, reason,
+  conformance: {verdict: "conforms|deviates|unknown",
+                dimensions: {structure, values, behaviour, responsive},
+                refused_by: "values"}}, ...]
+```
+
+- **`conforms`** → reuse it. This is the ordinary case and nothing changed.
+- **`deviates`** → do **not** reuse silently. Name the dimension that refused
+  it — *"`Card` deviates on `values`: type scale 14/20 against the artifact's
+  16/24"* — and surface reuse-with-adaptation versus build-new as a choice.
+  A bare "candidate rejected" is not a discharge; the caller cannot act on it.
+- **`unknown`** → the candidate was not scored against the artifact (no
+  extraction yet, or a subtree the audit could not read). Treat as `deviates`
+  for the purpose of not reusing silently, and say which of the two it is —
+  "did not conform" and "was not checked" are different facts.
+
+**And the decision moves after extraction, not before it.** A conformance
+verdict needs the artifact's own values, so a reuse decision taken before
+extraction is taken without the evidence that decides it. Where the run has an
+artifact, order is: extract → audit → score → conform → decide. The unqualified
+reuse-first ordering stands only where there is no artifact to conform to.
+
+**Scope:** this is a gate on REUSE, not a license to rewrite the incumbent. A
+candidate that deviates is left alone; the choice is whether *this* work builds
+on it.

package/dist/agent-src/skills/existing-ui-audit/references/steps/07-greenfield-branch.md

@@ -0,0 +1,29 @@
+# 7. Greenfield branch
+
+If **all** are true:
+- `state.ui_audit.components` is empty
+- `state.ui_audit.design_system == "custom-or-none"`
+- `state.ui_audit.design_tokens` is empty (no Tailwind config customizations, no `:root`)
+
+then set `state.ui_audit.greenfield = true` and emit a halt:
+
+```
+> No existing UI surface detected — this looks like greenfield.
+>
+> 1. Scaffold a minimal token set + a base component primitive folder
+>    before building (recommended for projects with >1 planned screen)
+> 2. Proceed bare with Tailwind defaults (recommended for one-off prototypes)
+> 3. Point me at an external design-system reference (URL or file)
+> 4. Scaffold + a granularity convention — as 1, and new components go into
+>    named granularity folders you pick the names for; rename or drop it later
+>    and nothing here objects
+
+**Recommendation: 1 — Scaffold tokens + primitives** — even one extra screen
+benefits from a shared base; the scaffold cost is ~10 min and saves
+re-doing every primitive on screen 2. Caveat: flip to 2 if this is a
+demo or single-page prototype that will not grow.
+```
+
+Option 4 is an **offer**, and the only one made anywhere: a project that already exists is never asked (§ 1b reads what it chose), and a greenfield project picking any other number has declined terminally, because the halt is a no-op once any decision is recorded. It stays one more number in the same block rather than a second question — a single number still answers it, which is what the reply-shape rule requires.
+
+Record the user's pick in `state.ui_audit.greenfield_decision` (`scaffold` | `bare` | `external_reference` | `granularity_convention`). Re-running the skill on the same state-file with `greenfield_decision` set is a no-op for the halt (audit findings stay). `granularity_convention` takes the same scaffold path as `scaffold` — it adds the convention, it does not replace the scaffolding.

package/dist/agent-src/skills/existing-ui-audit/references/steps/08-a11y-baseline.md

@@ -0,0 +1,40 @@
+# 8. (Optional) Capture an a11y baseline
+
+The R4 visual-review-loop contract reads `state.ui_audit.a11y_baseline`
+when present; the review gate then filters incoming
+`state.ui_review.a11y.violations` against it so pre-existing
+violations stay informational and only NEW or CHANGED entries block
+the polish loop. Without a baseline the gate sees every violation as
+actionable — fine for greenfield, noisy for legacy surfaces.
+
+Capture the baseline when:
+
+- The audit covers components with known a11y debt the project does
+  not intend to fix in this run (legacy templates, third-party
+  embeds, vendor widgets).
+- The user says "don't block on existing a11y issues" or similar.
+
+Skip the baseline (omit the key, leave `state.ui_audit.a11y_baseline`
+unset) when:
+
+- The surface is greenfield — the review gate should treat every
+  violation as new.
+- The project's a11y posture is "zero known violations" and any
+  finding is by definition actionable.
+
+Shape (each entry must carry at least `rule` + `selector`; severity
+is optional but recommended so the review gate's severity-floor
+filter behaves the same on replay):
+
+```
+state.ui_audit.a11y_baseline = [
+  {rule: "color-contrast", selector: ".legacy-tab", severity: "moderate"},
+  {rule: "label",          selector: "form#search input[type=search]"},
+  ...
+]
+```
+
+Producer parity: the review skill that writes
+`state.ui_review.a11y.violations` MUST use the same `(rule, selector)`
+shape, otherwise the engine's de-dup will miss matches and pre-existing
+violations will surface as new findings on every run.