@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/references/changelog-archive/CHANGELOG-v3.md

@@ -0,0 +1,1899 @@
+# adia-ui-kit Changelog — v3.x archive
+
+> Historical entries rolled out of the live [`CHANGELOG.md`](../../CHANGELOG.md), which keeps only the most recent 3. Newest-first.
+
+## 3.9.2 (2026-05-29)
+
+**PATCH** — Figma `styles.md`: bless structural-layout inline CSS as the one exception (corpus-grounded).
+
+Followed up the v3.9.1 "attributes-first / avoid inline styles" guidance with a corpus audit (adia-ui-a2ui mode 3+6): traced every inline-style chunk to its source HTML and classified what the styles set. Finding — the large majority is **legitimate structural layout** (`height:100vh` page frames, `flex:1` scroll panes, `grid-template-columns` custom grids, fixed sidebar widths) that **no primitive/attribute expresses**; genuine attribute-replaceable violations are ~9 `font-size` occurrences, all in `playground-*` demo-infra chunks (tool chrome, not product patterns). A flat "never inline style" would be unfollowable for a full-height app frame.
+
+- **`../../assets/figma-make/guidelines/styles.md`** — new "Structural layout is the one inline-style exception" section: the test is *"does a primitive/attribute already do this?"* — yes (`gap`/`size`/`variant`/`color`/row/col/grid/stack) → use it, never inline; no (`height:100vh`, scroll panes, custom grid) → inline structural CSS OK, still token-based, content inside primitives. Consistent with `tokens.md` rule 2 (token overrides still go in a scoped CSS rule, never inline).
+- **No corpus rewrite.** The investigated "convert shell-scaffold chunks to shell primitives" campaign was found unwarranted — the scaffolds are legit custom layouts with no conversion target; forcing primitives would cargo-cult + risk the eval floors for ~zero gain. Recorded so it isn't re-litigated.
+- `skill.json` 3.9.1 → 3.9.2.
+
+## 3.9.1 (2026-05-29)
+
+**PATCH** — Figma Make guidelines: attributes-first, no inline-style examples (operator feedback).
+
+The v3.9.0 `tokens.md` showed `<button-ui style="--button-bg: var(--a-primary)">` as a component-override example. That is wrong twice over: (1) `<button-ui>` has a first-class `variant`/`color` API, so a token override is never the right tool there; (2) inline `style="--token: …"` examples train Make to emit inline-style pollution into generated markup.
+
+- **`tokens.md`** — replaced the inline button-override example with an **attributes-first** section (`<button-ui variant="primary" color="danger">` is the recommended danger button) + a clearly-labeled WRONG inline example. Component-token overrides now shown only for the no-attribute case (region card tint), in a **scoped CSS rule on an ancestor**. Converted the `--a-density` example from inline `style=` to a CSS rule. Rules list gains "prefer attributes" + "never set tokens inline with `style=`" as #1/#2.
+- **`components.md`** — the `<button-ui>` danger example now uses `variant="primary" color="danger"` (solid danger) instead of bare `color="danger"`, modeling variant+color composition.
+- **`Guidelines.md`** — critical rule 7 strengthened: restyle via attributes first, then tokens in a scoped CSS rule, never inline `style=` per instance.
+- Net: zero recommended inline-style examples across the Figma assets (the only `style=` left is prose + one labeled-WRONG demo).
+
+## 3.9.0 (2026-05-29)
+
+**MINOR** — Structured Figma Make design-system-guidelines kit (the 4-file `guidelines/` folder Figma's codegen reads) + two token-fact corrections.
+
+- **`assets/figma-make/guidelines/`** (NEW, 4 files) — matches Figma's documented Make-kit `guidelines/` layout (auto-discovered; "multiple short files beat one large file"):
+  - `Guidelines.md` — read-first: what AdiaUI is, the CDN-rollup setup block, the `<name>-ui` naming rule, reading order, and the 7 critical usage rules.
+  - `components.md` — pick-a-component decision tree, grouped tag vocabulary (verified against the live 119-primitive + 4-shell inventory), per-component CORRECT/WRONG examples, the `<admin-shell>` skeleton.
+  - `styles.md` — load the rollup CSS (one file, not 119), theming as TWO axes (`theme` palette {default/ocean/forest/sunset/midnight/lavender/rose/slate} + `data-scheme` {light/dark/system}), layout primitives, no-utility-CSS rule.
+  - `tokens.md` — `--a-*` token families, parametric `--a-density` / `--a-radius-k` knobs, semantic color roles, `--<component>-*` override chain.
+- **Token-fact corrections (verified against `styles/tokens.css` + `components/button/button.css`):**
+  - Primary-action fill is **`--a-primary`** + **`--a-chrome-light`** text — NOT `--ui-primary` / `--ui-primary-fg` (that naming predates the `--ui-* → --a-*` migration). Fixed in `tokens.md`.
+  - Theming is **two separate attributes** — `theme` (palette) and `data-scheme` (light/dark). The earlier `assets/templates/figma-make-guidelines.md` (v3.8.1) conflated them as `data-scheme="ocean"`; corrected.
+- **`../figma-make.md`** — added "Two artifacts" subsection: single paste-in block (`templates/figma-make-guidelines.md`) vs structured kit folder (`figma-make/guidelines/`), with the pick-by-usage guidance.
+- **`skill.json`** — added the 4 files to `files[]`; bumped 3.8.1 → 3.9.0.
+- Companion memory `feedback_token_semantics` updated (`--ui-*` → `--a-*` migration + the `--a-primary`/`--a-chrome-light` pair).
+
+## 3.8.1 (2026-05-29)
+
+**PATCH** — Completes the 3.8.0 §FigmaMake feature with the actual paste-in artifact + corrects the integration mechanism.
+
+- **`assets/templates/figma-make-guidelines.md`** (NEW) — ready-to-paste guidelines block for Figma Make's **Provide guidelines** field (the AI-instruction box revealed in the Make UI). Addressed to Make's generator: the CDN setup block, the `<name>-ui` naming rule, the grouped tag vocabulary (verified against the live 119-primitive + 4-shell inventory — not invented), the 9 usage rules (the common-mistake list: `text=` labels on button/badge, `<section>` card bodies, presence-based booleans, `class` not `className`, `nav-ui` not `menu-ui`, `stack-ui` is z-axis, field-ui multi-input col-wrap, theme-via-tokens-not-Tailwind, Phosphor icon names), and a worked `<admin-shell>` example.
+- **`../figma-make.md`** — added "The Guidelines field (primary path)" section pointing at the template, and reframed the old "Where to paste" as "Where the loads actually land" (the Guidelines field is how you *steer* Make; the head/React-entry is where the emitted loads *land*).
+- **`skill.json`** — added the template to `files[]`; bumped 3.8.0 → 3.8.1.
+
+## 3.8.0 (2026-05-29)
+
+**MINOR** — New `§FigmaMake` reference: using AdiaUI in Figma Make (and Bolt / Lovable / v0 / StackBlitz) via CDN.
+
+- **`../figma-make.md`** (NEW) — CDN integration guide for prompt-to-app / web-container codegen tools where there's no `npm install`. Covers: the 90-second kitchen-sink default (`web-components.min.css` + shell CSS + `everything.min.js`); **all CDN options** as two tables (every CSS + JS bundle URL with current `@0.6` sizes + when-to-load); where to paste in Make (document `<head>` vs a React-entry inject snippet that `<link>`s CSS + dynamic-`import()`s JS); JSX usage caveats (`class` not `className`, presence-based booleans, `text=` content contract, CustomEvent binding); the `@0.6` minor-range pin policy; and a verification block. Sister to `setup.md` §Step 0.5; bundle sizes captured live at v0.6.45.
+- **`SKILL.md`** — added the `§FigmaMake` stub (placed after §Setup) pointing at the new reference.
+- **`../loading-protocol.md`** — added the `figma-make.md` row to the reference manifest (the on-demand discovery surface).
+- **Hygiene:** `skill.json` `version` was stale at `3.7.10` (behind CHANGELOG `3.7.13`); corrected to `3.8.0` alongside adding `../figma-make.md` to the `files` array.
+
+## 3.7.13 (2026-05-28)
+
+**PATCH** — Two 0.6.44-upgrade doc fixes from the claims-ui-v17 session (FEEDBACK-86, FEEDBACK-87).
+
+- **§Setup Step 5 + checklist: `optimizeDeps.exclude` callout for 0.6.44** (FB-86). Step 5 said "no special Vite config needed" — false on 0.6.44, where `<canvas-ui>`'s relative lazy import breaks Vite dep pre-bundling (FB-85) and the app won't boot. Added a version-scoped callout + checklist item to add `optimizeDeps.exclude: ['@adia-ai/web-components','@adia-ai/web-modules']`, marked removable on 0.6.45+ (where the bare-specifier fix lands). `../setup.md` only.
+- **`patterns-data.md` `fill()` helper: drop the `[slot="text"]` textContent mirror** (FB-87). Both `fill()` variants mirrored `[slot="text"].textContent` after setting `value`. On 0.6.44, input-ui toggles `data-empty` only inside its `textContent !== display` guard (`input.class.js`), so pre-writing textContent makes the guard false → `data-empty` stays → the placeholder renders over the value. Changed both variants to set `el.value = val` only (input-ui/textarea-ui sync `[slot="text"]` + `data-empty` from `value`). `../patterns-data.md` only.
+
+## 3.7.12 (2026-05-28)
+
+**PATCH** — Two cold-start doc fixes from the claims-ui-v17 build session (FEEDBACK-83, FEEDBACK-84).
+
+- **§Setup icon-loader recipe now loads the `bold` weight** (FB-83). The recipe loaded only `regular`, but primitives stamp icons at other weights — `<select-ui multiple>`'s chip-remove glyph is `<icon-ui name="x" weight="bold">` — so a regular-only map rendered them blank + warned (`[icon-ui] … weight="bold" not found`). Added a `bold` glob to both the Step 2 and Step 3 recipes + a §Setup checklist item, with a note on Phosphor's `<name>-<weight>.svg` naming and the other weights primitives use (`fill`/`thin`). `../setup.md` only.
+- **`admin-page-header` action-cluster examples corrected to `<div data-actions>`** (FB-84). `../patterns-recipes.md` (Route-fragment example + authoring bullet) and `../patterns-data.md` (Dashboard Layout example) showed `<span slot="action">` inside `admin-page-header`'s `<header>` — but the substrate only right-aligns via a title-row `<div>` + `[data-actions]` (`[slot="action"]` is topbar/statusbar-scoped), so the bare span stacks under the `<h1>`. Rewrote to the canonical `<header><div><h1/><div data-actions>…</div></div></header>`. The ticket also named `patterns-shells.md`, but that file was already canonical (line-205 rule + correct markup); the drifting authoring bullet was actually in `patterns-recipes.md`. `slot="action"` left intact where valid (card-ui / drawer-ui / pane-ui / admin-topbar).
+
+## 3.7.11 (2026-05-28)
+
+**PATCH** — §Setup clarification (FEEDBACK-82). Documents that `@adia-ai/web-modules` is required for `<canvas-ui>` (the A2UI render surface the default `web-components` barrel registers), not only for shells. On `@adia-ai/web-components` ≤ 0.6.43 the barrel's static cross-package import of `a2ui-root` made `web-modules` non-optional even for primitives-only apps — omitting it produced a hard `UNRESOLVED_IMPORT` build failure (FEEDBACK-81, fixed framework-side by lazy-loading the renderer). Added a Step 1 callout + §Setup checklist item so cold-start readers don't trim `web-modules` (Step 6) and hit the break. `../setup.md` only.
+
+## 3.7.10 (2026-05-27)
+
+**MINOR** — Cycle 18 + 19 substrate landings. Six substrate gaps surfaced by the gen-review v2.7-2.8 visual review were closed at SoT, plus three new chunk-authoring patterns documented for consumers. The substrate changes are transparent to recipe authors but materially change what the corpus pipeline can carry, so consumer guidance is updated to match.
+
+### Substrate fixes that change consumer-visible behavior
+
+**(1) Transpiler now preserves `slot=` universally.** `packages/a2ui/compose/transpiler/transpiler-maps.js` `extractProps()` only extracted yaml-declared props. `slot=` is HTML-standard, not a component prop, so it never survived to the rendered DOM — every `<row-ui slot="action">` / `<p slot="description">` / `<avatar-ui slot="icon">` was silently stripped. Fixed with a universal preserve at the top of `extractProps()`. Consequence: card-ui slot grammar now works in corpus chunks the same way it works in hand-authored HTML. The `<span slot="…">` wrapper antipattern that v2.7.0 documented is no longer load-bearing — direct slot children on elements is the canonical form.
+
+**(2) Transpiler now recurses leaf-type element children.** `Text`/`Button`/`Badge`/`Code`/`Kbd` were marked LEAF_TYPES in `transpiler.js` and silently dropped element children. Two real shapes broke: trailing icons on buttons (`<button-ui><icon-ui slot="trailing">`) and container-shaped slotted spans (`<span slot="heading"><text-ui>Title</text-ui> <badge-ui>...`). The transpiler now recurses element children of leaf types AND replaces concatenated-descendant `textContent` with the element's DIRECT text nodes — so `<text-ui>$49<text-ui>/month</text-ui></text-ui>` keeps "$49" on the outer and "/month" on the inner instead of "$49/month" twice.
+
+**(3) card.css heading/description rules now match transpiled `text-ui` variants only when unslotted.** Native `<h1>`–`<h6>`/`<p>`/`<small>` are transpiled to `<text-ui variant="display|title|heading|subsection|body|caption">` via `HTML_TAG_MAP`. The v3.7.9 fix extended card.css to match those variants — but the description rule (`text-ui[variant="body|caption"]`) ALSO matched slotted-heading elements (since `<span slot="heading">` becomes `<text-ui variant="body" slot="heading">`), causing cascade-order overlap. v3.7.10 adds `:not([slot])` to the variant matchers so explicit `slot="heading"` / `slot="description"` always wins.
+
+**(4) card.css unslotted-children rule guarded with `:has(> [slot])`.** The rule applied `justify-self: center` to unslotted children — modern browsers honor this for block-level in-flow elements, so a single `<row-ui>` direct child of `<header>` (no slots in use anywhere) got centered, breaking role-management header alignment. Guard ensures the rule only fires when the header is actually in grid mode.
+
+**(5) alert.css `[slot="close"]` now inherits the variant fg color.** The dismiss button was muted/grey by default (button-ui ghost variant), disconnected from the alert's variant-text color. Added `--button-fg-ghost: var(--alert-fg, var(--alert-fg-default))` so the X reads as part of the alert chrome (success-text on success, danger-text on danger).
+
+**(6) button-ui gains `icon-trailing` prop.** The existing `[slot="trailing"]` is kbd-pill styled (for shortcut indicators like `<kbd-ui slot="trailing">⌘K`). For forward-affordance carets ("Next →"), there was no clean path. Added `icon-trailing="caret-right"` (parallel to leading `icon=`) — stamps `<icon-ui slot="icon-trailing" name="...">` with proper icon CSS. button.yaml + button.class.js + button.css + button.a2ui.json updated in lockstep.
+
+### Consumer patterns updated
+
+| Pattern | Pre-v3.7.10 (v2.7.0 guidance) | v3.7.10 canonical |
+|---|---|---|
+| Header inline title + controls | `<header><row-ui align="center"><col-ui grow>title+desc</col-ui>controls</row-ui></header>` (workaround for stripped slots) | `<header><h3>Title</h3><p slot="description">Sub</p><button-ui slot="action">…</button-ui></header>` — slots now survive transpilation; canonical works everywhere |
+| Header inline title + inline badge | `<span slot="heading"><text-ui>Title</text-ui><badge-ui>…</badge-ui></span>` | Either: `<h3>Title <badge-ui>…</badge-ui></h3>` (inline badge inside h3) OR `<span slot="heading"><text-ui>Title</text-ui><badge-ui>…</badge-ui></span>` (also works post-fix). Inline-in-h3 is shorter; span-wrapper is needed if heading column needs explicit flex container styling. |
+| Trailing button caret | (no clean path; `slot="trailing"` was kbd-styled) | `<button-ui text="Next" icon-trailing="caret-right">` |
+| List items with icon + text + action | Various ad-hoc shapes via single `<row-ui>` wrapping everything | Canonical list-item-ui slot grammar: `<list-item-ui><avatar-ui slot="icon"><span slot="text"><text slot="description"><row-ui slot="action">` |
+| `<section bleed>` for list dividers | Recommended for edge-to-edge lists inside cards | Use only when content genuinely needs to extend past the card's content inset (tables, charts). For list-item-ui rows, plain `<section>` keeps content aligned with the header inset and dividers within the card-inset boundary. |
+
+### What v3.7.10 absorbs (skill files)
+
+- `../common-gotchas-consumer.md` — gains §12 trailing-icon-on-button (use `icon-trailing` not `<icon-ui slot="trailing">` for arrows/carets) and §13 span-wrapper-in-slot (now optional; only needed for explicit flex-container styling). §11 wrong-attribute table extended with `button-ui slot="trailing"` (kbd-only) vs `icon-trailing` (icon).
+- `../patterns-recipes.md` — Card-ui header section gets a third sub-section: "Choosing inline-h3 vs slot=heading wrapper for title+badge"; "When NOT to use `<section bleed>`" callout near the existing bleed mentions in patterns-data.md.
+- `SKILL.md` frontmatter version: 3.7.9 → 3.7.10
+- `skill.json` version: 3.7.9 → 3.7.10 (lockstep)
+
+### Why MINOR (not PATCH)
+
+Two-fold scope:
+
+1. **New substrate prop** (`button-ui[icon-trailing]`) — a new public component API, fresh prop in yaml + class.js + sidecar. Consumer recipes can now reach for it; documented in `patterns-recipes.md`. New capability surface = MINOR.
+
+2. **Behavior change for span-wrapper authoring** — pre-v3.7.10, `<span slot="heading">` with element children silently dropped its children at transpile time. Post-v3.7.10, those children are preserved. Existing chunks that worked around the bug (by NOT using span-wrappers) keep working; chunks that DID use span-wrappers now render their full content. This is a positive behavior change with no breakage, but enough of a semantic shift to warrant MINOR.
+
+### Verify
+
+- `node scripts/build/components.mjs --verify` — clean (179 files)
+- `npm run smoke:engines` — green (mono / zettel / free-form retrieval-quality probes ok)
+- `npm run test:a2ui` — 22 passed / 0 failed / 1 skipped
+- `npm run check:skills` — all clean
+- Visual probe of 16 cycle-18 + RL2 chunks: all render correctly with canonical slot grammar
+
+### Cross-references
+
+- **Sister skill**: `adia-ui-gen-review` v2.9.0 (`.agents/skills/adia-ui-gen-review/CHANGELOG.md`) — closed the loop that surfaced these six substrate gaps. The split: corpus-pipeline mechanics (transpiler, harvest, gallery) stay in `adia-ui-gen-review`; consumer-visible patterns + canonical recipes cross to `adia-ui-kit` (this bump)
+- **Predecessor**: v3.7.9 (commit `01987e94d`) — wrong-attribute gotchas table + row-ui in header sub-section
+- **Substrate commits**: `3227adc30` (transpiler slot + card.css text-ui variants), `b88af22fc` (card.css :has guard + transpiler leaf children + button icon-trailing), `8e85e98c3` (gallery canvas-surface-max), `ff3f9b413` (transpiler leaf children direct-text + card.css :not(slot) + alert.css close color), `87883b40b` (drop redundant bleed + role-management anatomy)
+
+---
+
+## 3.7.9 (2026-05-26)
+
+**PATCH** — Absorbs eight patterns surfaced by the `adia-ui-gen-review` v2.7.0 gallery cycle (cycle 17, 2026-05-26). Same axis as v3.7.4-v3.7.8: consumer composition traps that pass audits but break rendering, captured from a closed-loop visual review of 59 pre-hydrated A2UI gallery prompts.
+
+### What v3.7.9 absorbs
+
+**(1) §11 — Wrong attribute name on a primitive — silent no-op** (`common-gotchas-consumer.md`). Seven recurring "wrong attribute name = silent no-op" cases collapsed into a single gotcha entry with a table:
+
+- `<accordion-item-ui label="…">` → `text="…"` (yaml prop is `text`, matching `<button-ui>` / `<nav-item-ui>` family convention)
+- `<col-def field="…">` → `key="…"` (`<table-ui>` parser at `table.class.js:358-365` reads `el.getAttribute('key')`)
+- `<nav-group-ui text="…">` (without `open`) → `<nav-group-ui text="…" open>` (default `open: false`; sidebar groups typically want expanded)
+- `<chat-input-ui></chat-input-ui> + <button-ui>Send</button-ui>` → `<chat-input-ui></chat-input-ui>` alone (stamps its own paper-plane send button; sibling Send produces a double)
+- `<card-ui><code-ui></code-ui><footer><button-ui icon="copy">Copy</button-ui></footer></card-ui>` → `<code-ui language="…">…</code-ui>` (code-ui ships its own language label + copy button unless `[bare]` is set)
+- `<progress-row-ui value="0.42">` → `value="42"` (0–100 percent, not 0.0–1.0 fraction; mirrors `<progress-ui>`)
+- `<integration-card-ui><button-ui slot="action">Connect</button-ui></integration-card-ui>` → `<integration-card-ui status="available">` (button is derived from `[status]` enum; slotting one creates a double)
+
+Each row cites the yaml provenance. All seven were visible at canvas/runtime, none at HTML-author time — silent no-op class. Component Literacy gate (`component-literacy.md`'s `embed_gotchas` field) is the upstream defense; per-primitive `console.warn('did you mean [text]?')` heuristics are forward work.
+
+**(2) Card-ui header — inline title + controls without `slot=action`** (`patterns-recipes.md`). Existing "Card-ui header — slotted children, NOT `<div>` wrapper" section extended with a sub-section covering the unslotted-siblings failure mode. Two unslotted siblings (`<text-ui>` + `<button-ui>`) fall into the unslotted fallback row (`display: block`) and stack vertically instead of sharing one row. Two right shapes documented:
+
+- **Right A** (canonical): `<h3>` + `<span slot="action">…</span>` activates the 1fr/auto grid
+- **Right B** (`<row-ui>` fallback): for contexts that strip `slot=` (notably the A2UI transpiler for gen-UI corpus authoring), wrap header content in `<row-ui justify="space-between" align="center">`
+
+The two-shape doc closes the consumer-vs-corpus split: hand-authored HTML uses the slot-grid path; corpus HTML (which feeds the A2UI gen-UI pipeline) needs the row-ui shape to survive transpilation.
+
+**(3) Card-ui vs `<card-ui raw>` — surface-vs-chrome decision** (`patterns-recipes.md`, new section after "Card-ui header"). Distinguishes the two card modes:
+
+- `<card-ui>` (default): chromed surface — bg + border + shadow; the card IS the visible boundary
+- `<card-ui raw>`: layout wrapper without chrome; parent owns the surface
+
+Plus two recurring anti-patterns from the cycle-17 review:
+
+1. **Defaulting to `raw` when chromed is intended** — content floats against the page background with no visible boundary. Symptom of "missed default" (agent reached for `raw` to skip thinking about surface)
+2. **Non-raw card without explicit `<header>`** — the first visible content element (a `<field-ui label="…">`, a list item's primary text, the first paragraph) becomes the de-facto heading. Reads as "two-title card" visually. Always include `<header>` with explicit title on non-raw cards.
+
+Worked example included (`invite-members` chunk that rendered "Email addresses" twice because the field's label was promoted as section heading).
+
+### Why these matter
+
+The cycle-17 review surfaced eight demos (`invite-members`, `contact-form`, `billing-overview`, `role-management`, `status-dashboard`, `audit-log`, `integrations-grid`, `webhook-config`) where structural-only audits passed but visual review caught defects. The defect class is "primitive received an attribute that isn't its declared prop name, so the prop silently no-op'd; the rendered output looked plausible but missed the intended behavior." This class isn't catchable by `audit:card-structure` / `audit:shell-composition` / etc. because the markup is valid HTML; only `embed_gotchas` literacy or visual review surfaces it.
+
+### Files
+
+- `../common-gotchas-consumer.md` — added §11 wrong-attribute table; updated §Meta-pattern title from "ten" to "eleven"; extended §What-substrate-catches table with §11 forward-work entry
+- `../patterns-recipes.md` — extended "Card-ui header" with row-ui fallback sub-section; added "Card-ui vs `<card-ui raw>` — surface-vs-chrome decision" section
+- `SKILL.md` frontmatter version: 3.7.8 → 3.7.9
+- `skill.json` version: 3.7.8 → 3.7.9 (lockstep)
+
+### Verify
+
+- All seven §11 rows source-grounded against yaml — accordion-item.yaml (props.text), table.class.js:358-365 (parseColDefs key= read), nav-group.yaml (props.open default false), chat-input.yaml (description + a2ui.rules + anti_patterns[0]), code.yaml (description + props.bare), progress-row.yaml (props.value range), integration-card.yaml (props.status enum + a2ui.rules + anti_patterns)
+- `node scripts/build/components.mjs --verify` → unchanged (skill-only change; no substrate edit)
+- `npm run check:skills` → audit-roster currency expected to pick up the version bump
+
+### Why PATCH (not MINOR)
+
+Same rationale as v3.7.4-v3.7.8. No new SKILL.md modes, no new capability surface, no new required artifacts. The content is one new common-gotchas entry + two new pattern sub-sections — same shape as v3.7.4's §5/§6 absorption and v3.7.8's §7-10 absorption.
+
+### Cross-references
+
+- **Sister skill**: `adia-ui-gen-review` v2.7.0 (`.agents/skills/adia-ui-gen-review/CHANGELOG.md`) — cycle 17 gallery review that surfaced these patterns. The split: corpus-HTML specifics (transpilation slot-drops, `style=` survives on A2UI custom elements, image-ui lazy-loading) stay in `adia-ui-gen-review`; component-API + composition patterns universal to consumer HTML cross to `adia-ui-kit` (this bump)
+- **Predecessor**: v3.7.8 (commit family `46296e90a` + table-toolbar + cell-types)
+- **Source of cycle-17 demos**: `apps/saas/app/admin-dashboard/admin-dashboard.contents.html` + `catalog/ui-patterns/app/*` (where the wrong-attribute fixes landed)
+
+---
+
+## 3.7.8 (2026-05-25)
+
+**PATCH + substrate co-fix** — Closes three new tickets from a claims-ui-v15 cold-start session (FEEDBACK-72/73/74). Two are recipe-vs-yaml drift in the same family as v3.7.4-v3.7.7 (load-bearing substrate capability exists, consumer-facing recipe is partial); one is a substrate-side silent-failure class (router-ui provider not in barrel). The substrate side ships at `@adia-ai/web-components@0.6.40`; the skill side is this PATCH.
+
+### Substrate co-fix (FB-72 Finding 1 — root-cause class)
+
+**`<router-ui>` registers from the main barrel at @adia-ai/web-components@0.6.40+**. The barrel side-effect-imports `core/provider.js` alongside `core/icons-phosphor.js`. Standard cold-start path (`import '@adia-ai/web-components'` + `import '@adia-ai/web-modules/shell'`) now registers `<router-ui>` automatically — no extra import required.
+
+Pre-fix state: `<router-ui>` rendered as `HTMLUnknownElement`, `router.routes = [...]` silently no-op'd, route content area stayed empty. No console error, no warning, no network activity. Worst-class silent failure (resolution time ~30 min without yaml-spelunking).
+
+Verified-the-output: a probe importing the barrel into a happy-dom window confirms `customElements.get('router-ui')` returns `UIRouter` (the class), not `undefined`. Subpath-import consumers still need the explicit `import '@adia-ai/web-components/core/provider';` — documented as a callout in patterns-recipes.md.
+
+### What v3.7.8 absorbs (skill-side)
+
+**(1) Router-provider import requirement** (`patterns-recipes.md` §Route setup + `common-gotchas-consumer.md` §7). Two-tier callout: ✅ "auto-registered from the barrel at v0.6.40+" for the default cold-start; ⚠️ "subpath-imported consumers must register the provider explicitly" with the exact import line.
+
+**(2) `<table-toolbar-ui>` canonical paired shape** (`patterns-data.md` §Data Table + `common-gotchas-consumer.md` §8). Yaml-canonical: `<col-ui gap="3"><table-toolbar-ui for="X"></table-toolbar-ui><card-ui>...</card-ui></col-ui>` — toolbar OUTSIDE the card (per `table-toolbar.yaml` a2ui.rules "Place the toolbar ABOVE the `<card-ui>` containing the table-ui"). Anti-patterns documented: hand-rolled filter children → double chrome; parallel filter buttons in card-header → also double chrome. `slot="actions"` is the legitimate use case for slotted children (trailing primary buttons like New / Invite / Export).
+
+**(3) Two-`<section>` split for in-card toolbar** (`patterns-data.md` §Data Table + `common-gotchas-consumer.md` §9). Alternative composition when the consumer wants the toolbar inside the card-ui (already has a card-header with title + page-level actions): toolbar in normal-inset `<section>`, table in `<section bleed>`. Both in one bleed section → toolbar controls touch card edge (FB-73's symptom). Both in one bare section → table rows waste horizontal real estate.
+
+**(4) Table cell-types catalog + render escape hatch** (`patterns-data.md` §Data Table + `common-gotchas-consumer.md` §10). The 12-type catalog (text / number / currency / percent / date / datetime / boolean / badge / avatar / link / progress / actions) as a table with value-shape × renders-as × align × sort columns, source-grounded from `node_modules/@adia-ai/web-components/components/table/cell-types.js`. Custom-render section documents the four constraints (cell-element-write, memoize-per-row, `sortable: false` for non-scalar cells, `format()` text-export fallback). Worked example pulls together status (badge) + amount (currency, right-aligned) + submitted (date) + tags (custom render of `<tag-ui>` chips).
+
+**(5) FB-69 fix propagation** (`patterns-recipes.md` route-fragment template + `patterns-data.md` Dashboard Layout). v3.7.4 fixed `<admin-page-body>` → inner `<section>` in `patterns-shells.md`; the same pattern in `patterns-recipes.md` and `patterns-data.md` stayed un-touched until now. v3.7.8 closes the propagation gap — route-fragment template at lines 477-496 + Dashboard Layout fragment at lines 173-209 both gain inner `<section>` wrappers + cross-reference callouts to `patterns-shells.md §Wrapper-vs-column`.
+
+### Why this matters
+
+These four findings ALL share the v3.7.4-v3.7.7 family root cause: **the load-bearing contract lives in the component yaml; the recipe shows partial markup; consumer follows the recipe and hits silent failure.** FB-72 Finding 3 (FB-69 propagation gap) is the **second-order failure** that the FB-65 audit-gate forward-work was meant to catch — a fix lands in one recipe file, the same pattern in another recipe file goes un-touched, future cold-starts re-hit the bug.
+
+### Files
+
+- `packages/web-components/index.js` — barrel side-effect-imports `core/provider.js` (will ship at @adia-ai/web-components@0.6.40 via the next release skill cut)
+- `../patterns-recipes.md` — Route setup gains router-provider callout; route-fragment template gains inner `<section>` wrapper + FB-69 cross-reference callout
+- `../patterns-data.md` — Data Table rewritten with two canonical shapes (toolbar-outside + toolbar-inside-two-sections), anti-pattern callout, column descriptors using cell-types, 12-type catalog table, custom-render section, toolbar opt-out table; Dashboard Layout wrapped in `<admin-page-body>` + `<section>` + nests table block in toolbar-outside pattern
+- `../common-gotchas-consumer.md` — §7 router-provider, §8 table-toolbar double-chrome, §9 toolbar in same bleed section, §10 cell-types not engaged; §Meta-pattern renamed "all ten"; §What-substrate-catches table extended with 4 new forward-work entries
+- `SKILL.md` frontmatter version: 3.7.7 → 3.7.8
+- `skill.json` version: 3.7.7 → 3.7.8 (lockstep)
+
+### Verify
+
+- Substrate probe (happy-dom): `customElements.get('router-ui').name === 'UIRouter'` after barrel import → **PASS**
+- `node scripts/build/components.mjs --verify` → clean (179 files up-to-date)
+- `npm run smoke:engines` → all green (mono / zettel / free-form retrieval-quality probes ok)
+- `npm run verify:traits` → 56/56 traits (100% coverage)
+- `npm run check:skills` → audit-roster clean (versionLiteralParity matches 3.7.8 after this commit; pre-existing missing-design-plan WARNINGs are unrelated authoring-skill noise)
+
+### Why PATCH (not MINOR)
+
+Same rationale chain as v3.7.4-7. No new SKILL.md modes, no new capability surface, no new required artifacts. The new content is recipe-shape documentation + 4 new common-gotchas entries (same axis as v3.7.4's §5/§6 absorption). Substrate co-fix is a one-line barrel import; ships separately via the substrate release skill.
+
+### Why this might (or might not) hold
+
+**Hits the load-bearing teaching surface** — patterns-data.md "Data Table" was the consumer-facing first stop and previously showed `[{key, label}]` columns + pre-formatted strings as the canonical. The v3.7.8 rewrite makes raw-values-plus-cell-types the canonical default, with a worked example. An LLM building from the new recipe will pass raw numbers to `currency` columns, raw ISO strings to `date` columns, and reach for `render` when it sees multi-element cells.
+
+**Risk: the new "Data Table" section is long** (~150 lines after the rewrite). LLMs sometimes truncate at the first matching pattern. The mitigation: the canonical shapes (toolbar-outside-card + raw-values-plus-cell-types) are in the FIRST ~40 lines, before the anti-patterns / catalog / render section. Skim-readers will get the right shape; deep readers get the full contract.
+
+**Forward work captured in §What-substrate-catches table** — four new forward-work entries (lint for hand-rolled toolbar children; HTML scan for toolbar-in-bleed; dev-only runtime warning for cell-types-not-engaged; subpath-import substrate detection). None of these blocks v3.7.8; all are mechanization opportunities for follow-up sprints.
+
+### Cross-references
+
+- Predecessor: v3.7.7 (commit `46296e90a` family) — drop-the-scaffolding anti-patterns (`<span>` vs `<div data-actions>`; `gap="md"` vs `gap="4"`)
+- Sister tickets: FB-72/73/74 (claims-ui-v15, 2026-05-25); FB-69 propagation (claims-ui-v11, 2026-05-25)
+- Substrate co-fix: `packages/web-components/index.js` barrel import (will ship at @adia-ai/web-components@0.6.40)
+- The "anatomy-vs-callout-mismatch" meta-rule from v3.7.6 also fired here, in a sister form: the FB-69 fix landed in patterns-shells.md but didn't propagate to patterns-recipes.md OR patterns-data.md, so consumers entering through the route-fragment recipe (NOT the shell-anatomy recipe) STILL hit the bug after v3.7.4. v3.7.8 closes both recipe-files in lockstep.
+
+### Drift class observation (consolidating across v3.7.4-v3.7.8)
+
+The v3.7.4 → v3.7.8 arc covers **two distinct drift classes** that both manifest as "recipe says X, yaml says Y, consumer hits Y":
+
+1. **Anatomy-vs-callout mismatch** (v3.7.4-7): canonical example in the anatomy block teaches Y, but a downstream §Brand chrome / §Composition recipe H3 calls out X. LLMs read the anatomy first and build from Y. **Fix**: flip the anatomy default + name the anti-pattern in the surrounding prose.
+
+2. **Recipe-vs-yaml mismatch** (v3.7.8): yaml documents a load-bearing capability (cell-types catalog, table-toolbar `for=` binding, router-provider import requirement); recipe shows only a partial form that drops the load-bearing piece. **Fix**: hoist the capability into the canonical recipe + name the anti-pattern in a common-gotchas entry + (where possible) substrate co-fix that retires the silent-failure mode.
+
+The meta-rule from v3.7.7 ("markup teaches structure; prose teaches the contract; both must agree") applies to both classes. The forward-work meta-rule from v3.7.8: **when a feedback ticket fixes a recipe-vs-yaml drift, the maintainer-side fix protocol must include a "grep for every other occurrence of this pattern across all recipe files" pass before promoting the fix** — i.e., the FB-65 audit gate forward-work, now firing on its second predicted incident.
+
+---
+
+## 3.7.7 (2026-05-25)
+
+**PATCH** — Fourth bump of the day. Absorbs two additional anti-patterns visible in the same consumer DOM dump that triggered v3.7.6. These are smaller-class than v3.7.6's anatomy-vs-callout root cause, but they recur for the same reason: agents drop named-attribute scaffolding when simplifying a canonical example.
+
+### Two anti-patterns absorbed
+
+**(1) `<span>` vs `<div data-actions>` for action clusters.** Consumer wrapped `<button-ui text="New Claim">` in a bare `<span>` inside `<admin-page-header>`'s `<header>` title row, instead of the canonical `<div data-actions>`. The canonical example USES `<div data-actions>` but the §Key affordances bullet was too brief — just "wrapping `<div data-actions>` for the trailing action cluster" — without naming the anti-pattern. v3.7.7 expands the bullet to:
+- Cover BOTH the admin-topbar action cluster AND the admin-page-header `<header>` title row
+- Name the anti-pattern explicitly: "bare `<span>` (or `<div>` without the attribute) doesn't match the CSS rule"
+- Show the rendering failure: "buttons fall into the title column instead of right-aligning"
+
+`patterns-shells.md` `[data-actions]` bullet expanded ~3x; canonical examples already used `<div data-actions>` correctly.
+
+**(2) `gap="md"` vs `gap="4"` on layout primitives.** Consumer wrote `<grid-ui columns="3" gap="md">` — the `md` keyword is a `<button-ui size="md">` / `<badge-ui size="lg">` convention; layout primitives (`grid-ui`, `col-ui`, `row-ui`) use NUMERIC density tokens that map to `--a-space-N`. Invalid token silently falls back to default (0 or browser default), producing a no-gap render.
+
+`patterns-layout.md` Grid section gets a ⚠️ callout right after the canonical ratios:
+- Valid: `gap="3"`, `gap="4"`, `gap="2 4@md"`
+- Invalid: `gap="md"`, `gap="lg"`, `gap="small"`, `columns="auto"`
+- Explanation: numeric tokens map to `--a-space-N`; size keywords are for primitive `size=` only
+- Anti-pattern citation from consumer DOM
+
+### Files
+
+- `../patterns-shells.md` — `[data-actions]` Key affordance bullet expanded
+- `../patterns-layout.md` — Grid section gets gap-numeric-token callout
+- `SKILL.md` frontmatter version: 3.7.6 → 3.7.7
+- `skill.json` version: 3.7.6 → 3.7.7 (lockstep)
+
+### Verify
+
+- `npm run check:skills` → all clean (versionLiteralParity matches 3.7.7)
+- `npm run check:brand-chrome` → still clean
+- `npm run check:admin-page-structure` → still clean
+
+### Why PATCH
+
+Pattern-clarification class. No new SKILL.md modes, no new capability surface, no new artifacts. Same as v3.7.6 — recipe / anti-pattern documentation refinement.
+
+### Meta-pattern (consolidating from v3.7.4 → v3.7.7)
+
+**Drop-the-scaffolding anti-pattern**: agents simplify canonical examples by dropping named-attribute decorations (`data-actions`, `slot="heading"`, the inner `<header>` / `<section>`). The naked structure renders, but the CSS rules that depend on those attributes don't match, so styling falls back to defaults. This produces a "renders, but looks slightly off" failure mode that audits without visual checks miss.
+
+The 4-cycle fix arc (v3.7.4–v3.7.7) traces this meta-pattern across 4 specific instances:
+- v3.7.4 (FB-67): bare `[slot]` siblings instead of `<admin-entity-item>` in brand chrome
+- v3.7.4 (FB-68): bare `<h1>` instead of `<header><h1></header>` column-owner
+- v3.7.4 (FB-69): bare `<card-ui>` instead of `<section><card-ui></section>` column-owner
+- v3.7.5 (FB-71): same as 3.7.4 FB-67 but with primitive citation (admin-entity-item.yaml a2ui rule)
+- v3.7.6: anatomy taught the broken shape → flip canonical to teach the right shape
+- v3.7.7: `<span>` instead of `<div data-actions>`; `gap="md"` instead of `gap="4"`
+
+Forward-work meta-rule: **when a recurring pattern drops a named-attribute decoration, audit the canonical example to verify the decoration is named explicitly in the surrounding prose, not just present in the markup**. Markup alone teaches structure; prose teaches the contract. Both must agree.
+
+### Cross-references
+
+- Predecessor: v3.7.6 (commit `264a7069a`) — root-cause anatomy fix
+- Sister consumer DOM dump: same dump that triggered v3.7.6 (claims-ui-v11 post-v3.7.5)
+- Audit backstops: `audit:brand-chrome` (v3.7.5), `audit:admin-page-structure` (v3.7.4) — both still clean; the v3.7.7 issues are smaller-scope and not currently audit-gated (`data-actions` correctness + numeric-gap-token validation are speculative forward-work)
+
+---
+
+## 3.7.6 (2026-05-25)
+
+**PATCH** — Third bump of the day. Closes the **anatomy-vs-callout mismatch** that caused FB-71's anti-pattern to RECUR after v3.7.5 supposedly fixed it. Diagnosed from a consumer DOM dump (claims-ui-v11 post-v3.7.5) that STILL produced bare `<span slot="heading">Claims</span>` brand chrome despite v3.7.5's §Brand chrome H3 + audit gate. Root cause: the fix landed in a downstream H3, but the canonical anatomy code block (line 36-39) still taught multi-tenant `<select-ui workspace-switcher>` as THE canonical — LLMs read the anatomy, infer "this is the canonical," and for single-product apps simplify by dropping `<select-ui>` → bare span. Never reach the §Brand chrome H3 because their intent funnel never crosses "look up brand patterns."
+
+Same failure class as FB-68/69 (anatomy taught wrong shape → fix landed in callout → consumers built from anatomy → bare reduction). For FB-68/69 we fixed both layers; for FB-71 we only fixed the callout layer in v3.7.4/v3.7.5. v3.7.6 fixes the anatomy.
+
+### What v3.7.6 changes
+
+**Canonical anatomy (`patterns-shells.md:36-49`)** — sidebar brand chrome now defaults to `<admin-entity-item>` (Pattern A, single-product, the majority case) with multi-tenant `<select-ui workspace-switcher>` documented as a comment alternative. Single-product is the default because:
+1. Most consumer apps are single-product (chat-ui IS multi-tenant — an exception, not the norm).
+2. The "single source of truth is chat-ui:site/index.html" framing was misleading consumers — the anatomy teaches STRUCTURE (the 13 parts), not a specific brand-chrome SHAPE. The shape is parametric per §Brand chrome.
+3. LLMs reaching for a single-product shape MUST start from a single-product anatomy — they won't navigate to §Brand chrome on their own.
+
+The comment block above the new canonical explicitly forbids bare-span fallback ("Do NOT use bare `<span slot="icon">` + `<span slot="heading">` here") so even an LLM that doesn't read all the way through has the constraint in-line at the use site.
+
+**Companion update at sidebar footer (`patterns-shells.md:55-63`)** — clarifies the two-shape rule for user identity (interactive `<select-ui>` for menu / static `<admin-entity-item>` for display).
+
+**New slot-vocabulary summary table (`patterns-shells.md` between canonical and 13-part table)** — explicit mapping of element + position → slot attribute requirement. Closes the secondary issue visible in the same consumer DOM dump: `<admin-topbar slot="header">` was placed inside `<admin-content>` (slot="header" only positions inside `<admin-sidebar>`; the content-area topbar takes no slot and is positioned by being first-child via CSS). The table makes the disambiguation explicit:
+
+| Element | Position | `slot=` attribute |
+|---|---|---|
+| `<admin-topbar>` | Inside `<admin-sidebar>` | **REQUIRED**: `slot="header"` |
+| `<admin-topbar>` | Inside `<admin-content>` | **No slot** |
+| `<admin-statusbar>` | Inside `<admin-sidebar>` | **REQUIRED**: `slot="footer"` |
+| `<admin-statusbar>` | Inside `<admin-content>` | **No slot** |
+
+(Plus 5 more rows covering sidebar / content / command / page / page-header-body.)
+
+A ⚠️ anti-pattern callout below the table names the specific failure mode: putting `slot="header"` on a content-area `<admin-topbar>`.
+
+**13-part table row for sidebar header topbar** rewritten — previously said "workspace/context switcher lives here" (multi-tenant-biased framing); now reads "brand chrome (single-product `<admin-entity-item>` OR multi-tenant `<select-ui workspace-switcher>`)" with explicit prohibition on bare-slot composition.
+
+**§Brand chrome H3 framing** updated — was "The 13-part anatomy above shows the **multi-product workspace** brand shape"; now "The canonical anatomy above shows the **single-product** brand shape (`<admin-entity-item>`) as the default — that's the majority case. For multi-tenant apps, swap to `<select-ui variant="ghost">`." Mirrors the inverted default.
+
+**§Brand chrome decision table** row order inverted — single-product is now the FIRST row, multi-tenant the second. Single-product gets the "(canonical in anatomy above)" pointer.
+
+**§Composition recipes Admin product page** — sidebar header updated to default to `<admin-entity-item>` with multi-tenant `<select-ui>` as a comment alternative. Statusbar footer gets a comment about the interactive-vs-static distinction.
+
+### Files
+
+- `../patterns-shells.md` — canonical anatomy fix (line 36-49 + 55-63) + new slot-vocabulary table + 13-part table row rewrite + §Brand chrome H3 framing + decision table re-order + §Composition recipes update
+- `SKILL.md` frontmatter version: 3.7.5 → 3.7.6
+- `skill.json` version: 3.7.5 → 3.7.6 (lockstep)
+
+### Verify
+
+- `npm run check:skills` → clean (versionLiteralParity matches 3.7.6; all gates green)
+- `npm run check:brand-chrome` → clean (the gate I authored in commit `fc6aa1891` would catch the bare-slot regression IF a consumer ran it locally — but the recurrence pattern shows consumers DON'T run substrate audits against their own HTML, so doc-side mental-model fix is the load-bearing intervention)
+- `npm run check:admin-page-structure` → clean
+
+### Why PATCH (not MINOR)
+
+Same rationale chain as v3.7.3/4/5. No new SKILL.md modes, no new capability surface, no new required artifacts. The slot-vocabulary table + anatomy default flip are pattern-recipe clarifications — same kind of edit that v3.7.4's §Wrapper-vs-column callout was (PATCH-class). Per §VersionBump policy: anatomy clarification + drift-class mechanization at the doc-mental-model layer = PATCH.
+
+### Why this might (or might not) hold
+
+**What this fix relies on**: LLMs anchor their mental model on the canonical anatomy code block. Flipping the default from multi-tenant to single-product means LLMs writing a basic admin shell will inherit `<admin-entity-item>` automatically without needing to look up brand patterns. The audit gate in `audit-brand-chrome.mjs` is the mechanical backstop if the doc fix fails.
+
+**What it doesn't fix**: consumers on STALE skill bundles. Skills don't auto-update; if a consumer's vendored copy of adia-ui-kit is pinned at v3.7.3 or earlier, the fixes don't reach them. Forward-work: skill-version-staleness detection (consumer-side check that warns when the skill they loaded is N versions behind the registry).
+
+**Meta-pattern visible across v3.7.4/5/6**: when a doc fix recurs, the fix landed at the wrong layer. The §Brand chrome H3 in v3.7.4/5 was a SECONDARY surface; the canonical anatomy is the PRIMARY surface that LLMs build from. Same lesson as FB-68/69 (the canonical example needed to change, not just the callout). Pattern worth absorbing into a meta-rule for future skill edits: **when adding a corrective callout for a recurring pattern, also verify the canonical example doesn't teach the broken pattern as the default**.
+
+### Cross-references
+
+- Consumer DOM dump (claims-ui-v11 post-v3.7.5) — not filed as a separate FB ticket; effectively a recurrence of FB-71 due to anatomy-layer miss
+- Predecessor: v3.7.5 (commit `bbe13df5f`) — landed §Brand chrome H3 but not the anatomy default flip
+- Sister fix: v3.7.4 (commit `c7238d34d`) — set the FB-67 → FB-71 → recurrence pattern in motion by landing the H3 without the anatomy
+- Audit backstop: `scripts/audit/audit-brand-chrome.mjs` (commit `fc6aa1891`) — mechanical gate; catches regressions when consumers run substrate audits against their HTML
+
+---
+
+## 3.7.5 (2026-05-25)
+
+**PATCH** — Same-day follow-on to v3.7.4: resolves FB-71 (claims-ui-v11) by rewriting §Brand chrome H3 to use `<admin-entity-item>` as the canonical Simple-tier brand-chrome primitive. v3.7.4's Pattern A canonized bare `[slot="icon"]` + `[slot="heading"]` siblings — but `<admin-entity-item>` already ships (since `@adia-ai/web-modules@0.6.20`, FB-38) explicitly for this use case, with a yaml a2ui rule that says *"Do NOT re-implement it with a bare `<span>` — those have no shared collapse boundary."* v3.7.4 missed the primitive; v3.7.5 closes the discovery gap. Per §VersionBump policy: same-class doc fix + primitive-discovery wiring + substrate sweep = PATCH.
+
+### FB-71 root cause — primitive discovery gap
+
+The skill had TWO parallel discovery paths that didn't cross-reference for brand chrome:
+1. `patterns-shells.md` §Admin shell + §Brand chrome (new in v3.7.4) treated brand chrome as topbar-slot-vocabulary composition. Pattern A used bare slots.
+2. `patterns-recipes.md:345-369` mentioned `<admin-entity-item>` BUT only as a FOOTER (statusbar) alternative — implying admin-entity-item was a user-menu thing, not a brand-header thing.
+
+But `<admin-entity-item>`'s own yaml description explicitly named BOTH use cases — *"workspace identity in `<admin-topbar slot="header">`, user identity in `<admin-statusbar>`, the leading item of a breadcrumb, a flyout header, or a user row."* The skill's brand-chrome H3 contradicted the primitive's a2ui rule by canonizing the re-implement-with-bare-span pattern.
+
+### Consumer impact verified
+
+claims-ui-v11 adopted v3.7.4's Pattern A verbatim. First-paint visual review caught 8px horizontal misalignment between brand icon and `<nav-item-ui>` icons below — DevTools `getBoundingClientRect`:
+- Pattern A brand icon: x=4px (topbar `--page-sidebar-px`)
+- nav-item-ui icon: x=12px (section-ui 4px + nav-item-ui 8px)
+- admin-entity-item brand icon: x=12px (mirrors `<select-ui>` trigger geometry) — **0px delta with nav**
+
+### What landed in kit v3.7.5
+
+**`../patterns-shells.md` §Brand chrome H3 (lines 208-262) rewritten:**
+- Pattern A: now uses `<admin-entity-item slot="heading">` as canonical static brand (with optional `slot="badge"` for environment chip)
+- Pattern B: clarified as "interactive workspace switcher" with explicit "do not use `<select-ui disabled>` to fake static brand" warning
+- Pattern C: wraps `<admin-entity-item>` in `<a>` (preserves collapse boundary)
+- Decision table updated: Pattern A = admin-entity-item; removed "single-product switcher-symmetric" row (was Pattern B disabled-shape, now anti-pattern)
+- Top-band callout cites primitive's own a2ui rule + adds verification recipe (`getBoundingClientRect().left` should be 12, not 4)
+
+**`../patterns-recipes.md:345-385` rewritten:**
+- "Read-only identity alternative" comment block now explicitly names BOTH use cases (header brand + footer user identity), cross-links to patterns-shells.md §Brand chrome H3
+- Includes both header (brand) AND footer (user identity) admin-entity-item recipes side-by-side
+- Final note clarifies admin-entity-item vs select-ui/menu-ui: read-only display vs interactive
+
+**`../common-gotchas-consumer.md`:**
+- New §6 (Bare-slot brand chrome instead of `<admin-entity-item>`): full pattern + example + detection (visual + DevTools probe) + fix + sister-ticket citation
+- §What the substrate-side audit currently catches table extended with §6 row (proposed forward-work gate)
+- §Meta-pattern updated to "across all six"
+
+**`SKILL.md` + `skill.json`** version 3.7.4 → 3.7.5 (lockstep).
+
+### Substrate-side companion (chat-ui infra)
+
+Brand chrome sweep across `*.examples.html` substrate files — 9 instances + 1 prose update + 1 codepen comment:
+- `packages/web-components/patterns/admin-shell/admin-shell.examples.html:278` — "Rounded borderless" demo (1 fix)
+- `packages/web-modules/shell/admin-shell/admin-shell.examples.html:241, 279, 313` — Simple / Minimal / states-demo (3 fixes + prose update at L311 documenting the collapse-rail authoring rule)
+- `site/pages/patterns/admin-sidebar.html:136, 161, 202, 224, 249` — Brand chrome figures + nav-variant figures (5 fixes)
+- `examples/codepen.html:54` — comment teaching "static brand via `<span slot="heading">`" → "static brand via `<admin-entity-item>`"
+
+User-identity footer sweep (FB-71 related observation #1) — same drift class, applied to the 5 admin-statusbar footers in the same files:
+- `packages/web-components/patterns/admin-shell/admin-shell.examples.html:237, 294` (Maya Chen, Kim Granlund)
+- `packages/web-modules/shell/admin-shell/admin-shell.examples.html:265, 332` (Guest, Maya Chen)
+- `site/pages/patterns/admin-sidebar.html:149` (Guest)
+
+**Visual delta noted:** admin-entity-item gives `<img slot="icon">` a circular crop (`border-radius: var(--a-radius-full)`) by default per its CSS (treats img as avatar). This overrides the demos' `.brand-logo` / `.ad-brand-logo` slight-square rounding (`--a-radius-sm`). The visual change is intentional per the primitive's design — brand logos in shell-tier chrome become circular, consistent with `<select-ui avatar>` treatment. Consumers wanting square brand logos can add a page-local CSS override (`admin-entity-item > img[slot="icon"].brand-logo { border-radius: var(--a-radius-sm) }`).
+
+### Verify
+
+- `npm run check:admin-page-structure` → still clean (admin-entity-item migration doesn't touch admin-page wrappers)
+- `npm run check:skills` → still clean
+- Manual verification of brand icon x-position pending consumer feedback (was Pattern A x=4 → expected admin-entity-item x=12)
+
+### Why PATCH
+
+Same rationale as v3.7.4 — pattern recipe extension + drift-class mechanization, no new SKILL.md modes, no new capability surface. Per §VersionBump policy: same-class follow-on = PATCH.
+
+### Cross-references
+
+- Sister ticket: FB-71 (claims-ui-v11, 2026-05-25) — primitive-discovery miss in v3.7.4 §Brand chrome
+- Predecessor: v3.7.4 (commit `c7238d34d`) — added the §Brand chrome H3 with bare-slot Pattern A
+- Recipient response: RESPONSE-71 (in chat-ui inbox + cross-delivered to claims-ui-v11)
+- Substrate sweep commits: TBD (this release commit + substrate sweep commit)
+
+---
+
+## 3.7.4 (2026-05-25)
+
+**PATCH** — resolves four claims-ui-v11 inbound feedback tickets (FB-67/68/69/70) about gaps in shell + drawer pattern guidance + mechanizes the corresponding drift class via a new substrate audit gate. Pattern-capture absorption + checklist-reference extension; no SKILL.md churn, no new modes, no new required artifacts. Per §VersionBump policy: pattern-capture / drift-class mechanization = PATCH.
+
+### FB-68 — `<admin-page-header>` silent-degrade fixed (P1)
+
+`patterns-shells.md` §Admin shell canonical example used bare `<h1>` as direct child of `<admin-page-header>`, which fails the `admin-page-header > :is(header, header-ui)` selector in `admin-shell.templates.css:39` → silent loss of padding + max-width + flex layout. Routing wrapper `<div>` around `<admin-page>` children was undocumented and breaks the direct-child selectors entirely (`<admin-page-body>` falls back to `display: inline`).
+
+- Fixed canonical example to wrap `<h1>` in the required `<header>` column-owner (+ added `<div data-actions>` + optional description paragraph)
+- Added `### Routing inside admin-shell` H3 documenting Pattern A (`<router-ui>`), Pattern B (sibling `<admin-page>` + `[hidden]`), Pattern C (anti-pattern: don't wrap in `<div>`)
+
+### FB-69 — `<admin-page-body>` missing inner `<section>` (P1)
+
+Same root-cause shape as FB-68 but for the body wrapper. `admin-page-body > :is(section, section-ui)` is where padding (40px), max-width, and section-gap rhythm live. Canonical + §Composition recipes both showed bare `<card-ui>` direct children → zero padding, content flush against viewport edge.
+
+- Fixed canonical example to wrap content in inner `<section>` column-owner
+- Fixed §Composition recipes — Admin product page to nest `<card-ui>` inside outer `<section>` (annotated the two-`<section>` distinction: outer is page-body column, inner with `[bleed]` is card content)
+- Added **Wrapper-vs-column rule** callout to §Admin shell with decision table covering standard / iframe / editor-shell / split-pane direct-child scenarios + `[data-content-full]` escape hatch
+- Added **§5 admin-page-{header,body} inner-column-owner missing** to `common-gotchas-consumer.md` (parallels existing §1-4 gotchas; substrate-audit forward-work noted)
+
+### FB-67 — Simple-tier brand chrome (P2)
+
+The 13-part anatomy single-sources from chat-ui's multi-product workspace (`<select-ui avatar workspace-switcher>`). Single-product (Simple-tier) admin apps had no documented brand-chrome pattern; consumers reach for bare `<span slot="heading">` which renders as a sub-styled label.
+
+- Added `### Brand chrome in <admin-topbar slot="header">` H3 with three patterns: (A) `slot="icon"` + `slot="heading"` static brand, (B) degenerate workspace switcher (`<select-ui disabled>`), (C) `<a href="/">` brand-anchored nav-home
+- Added brand-chrome decision table mapping tier → pattern → when
+
+### FB-70 — `<drawer-ui>` footer button sizing (P2)
+
+`patterns-recipes.md` §Entity list → detail drawer pattern showed OPEN side (list → drawer body) but NO footer. Agents extrapolating from neighbor recipes default to `size="sm"` (matching topbar/card-header chrome convention), producing visually-undersized terminal commit/cancel/delete affordances.
+
+- Extended recipe to include canonical header (with close button) + dual-cluster footer (`slot="action-leading"` destructive + `slot="action"` commit/cancel) with default-size buttons
+- Added callouts for button density, dual-cluster layout, and drawer slot vocabulary
+- Added **§Button density by surface** table mapping surface → `size=` → why (chrome-band gets `sm`, content-band terminal actions get default)
+
+### Files touched
+
+- `../patterns-shells.md` — canonical fixes + §Wrapper-vs-column callout + §Brand chrome H3 + §Routing inside admin-shell H3 + §Composition recipes Admin product page fix
+- `../patterns-recipes.md` — extended §Entity list → detail drawer pattern + §Button density by surface table
+- `../common-gotchas-consumer.md` — new §5 gotcha + audit-coverage row now pointing at the new gate (no longer "None; visual review only")
+- `SKILL.md` frontmatter version: 3.7.3 → 3.7.4
+- `skill.json` version: 3.7.3 → 3.7.4 (lockstep with SKILL.md per v3.7.3 drift-fix discipline)
+
+### Substrate-side companion (chat-ui infra)
+
+- `scripts/audit/audit-admin-page-structure.mjs` — new audit gate mechanizing the FB-68/69 drift class. Scans HTML for `<admin-page-{header,body}>` whose direct child isn't a canonical column-owner (`:is(header, header-ui, section, section-ui, iframe, editor-shell, pane-ui)`). Modeled on `audit-card-structure.mjs`; 315 lines. Smoke-tested with known-bad fixture (catches bare-h1 + bare-card-ui; accepts iframe escape hatch).
+- `package.json` — wired `audit:admin-page-structure` / `:strict` and `check:admin-page-structure` (latter added to master `check` cascade).
+- 5 substrate `*.examples.html` brand-chrome fixes (separate commit `654019359`) — `packages/web-components/patterns/admin-shell/admin-shell.examples.html:223,275` + `site/pages/patterns/admin-sidebar.html:202,223,247`. The patterns/admin-shell file's data-chunk-description claimed "leading sidebar with workspace switcher" but code had bare `<span slot="heading">` — description LIED. Now Pattern A (icon + heading) or workspace-switcher canonical, per description.
+
+### Verify
+
+- Doc-only kit edits; no audit thresholds affected. SKILL.md body unchanged (no byte-budget impact). Discovery paths intact (existing cross-references continue to point at amended sections).
+- `npm run check:admin-page-structure` → clean (18 substrate elements audited, 0 violations; confirms substrate was already correct on this axis — the FB-68/69 drift was skill-doc only).
+- `npm run check:skills` → clean (the 3 pre-existing broken-section-references in sibling skills closed by the companion `check-skill-frontmatter.mjs` allowlist update — see commit `dde704c79`).
+
+### Sister-skill ripple (closed in same cycle)
+
+- `scripts/skills/check-skill-frontmatter.mjs` EXTERNAL_SECTION_REFS allowlist gained 2 entries (`vision-extensibility`, `mandatory skill-invocation gates`) to dismiss false positives in adia-ui-a2ui / adia-ui-authoring / adia-ui-ops SKILL.md citations of external docs (VISION-extensibility.md, AGENTS.md). Not strictly kit territory but unblocks the cascade and was discovered while running this cycle's verification.
+
+### Why PATCH (not MINOR)
+
+Same rationale as v3.7.2 (which also extended `common-gotchas-consumer.md` and was PATCH-framed):
+
+> *"No new capability surface, no new modes, no new required artifacts. Captures recurring patterns as a checklist reference that fires alongside existing literacy gate."*
+
+Pattern-coverage extensions (4 new H3 sections + 1 callout + 1 gotcha + 1 table) live in references/, not SKILL.md. The new audit gate is substrate-side infra (chat-ui scripts/audit/), cited by the kit but not bundled with it. Consumers on v3.7.3 → v3.7.4 gain richer pattern guidance for an existing topic (admin-shell composition) + the gate that mechanizes the drift class — not a new capability surface.
+
+### Cross-references
+
+- Sister tickets: FB-67/68/69/70 (inbound from claims-ui-v11, all flipped `submitted` → `responded`; archived under `inbound/archive/`)
+- Sister responses: RESPONSE-67/68/69/70 (in `inbox/` + cross-delivered to `/Users/kimba/Projects/adia/claims-ui-v11/.agents/team/tickets/inbox/`)
+- Commits: `a6c434b2c` (ticket resolution), `654019359` (substrate brand-chrome), `dde704c79` (audit gate + §-ref allowlist)
+
+---
+
+## 3.7.3 (2026-05-25)
+
+**PATCH** — Closes the discovery gap for v3.7.2's new `common-gotchas-consumer.md` reference + corrects v3.7.2's version-drift (skill.json bumped to 3.7.2 but SKILL.md frontmatter stayed at 3.7.1).
+
+### Discovery wiring
+
+v3.7.2 (peer commit `0d1708994`) shipped `../common-gotchas-consumer.md` and added it to skill.json's `linked_files` manifest, but **did NOT add discovery hooks** in any consumer-procedural location. A kit agent loading `component-literacy.md` (the closest sibling, the next-layer companion) had no semantic path to the gotchas reference. Per the SKILL DESC routing rule + "reference at bottom invisible to LLMs" memory, references that aren't pointed-at from procedural regions are effectively dark code.
+
+This PATCH adds 2 discovery hooks (no SKILL.md churn — body stays at ~50.9KB / ~230 bytes below 50KB fail):
+
+1. **`component-literacy.md` §When-to-load** — adds a top-band "Next-layer companion" callout pointing at `common-gotchas-consumer.md`, framing the relationship as "reading is not recognizing" — literacy fires CSS reads, but the four recurring traps recur even AFTER the read.
+2. **`component-literacy.md` §Cross-references** — `common-gotchas-consumer.md` added to the "Kit references that hand off to/from this gate" list with framing note + sister-skill citation.
+3. **`spec-to-ui-reasoning.md` §Bridges table** — new "Rung 13.5 Phase 4 author checklist" row pointing at `common-gotchas-consumer.md`. Positions it between Rung 13 (Component selection) and Rung 14 (DataBinding) — the natural firing point in the 19-rung pipeline.
+4. **`spec-to-ui-reasoning.md` Rung 13 row** — extended to include `component-literacy.md` (literacy gate) as a parallel handoff, surfacing the precondition explicitly in the bridges table (previously only mentioned in component-literacy.md's own narrative).
+
+### Latent broken-section-reference fixed
+
+`check-skill-frontmatter --strict` flagged `§PEV` at SKILL.md L417 as an unresolvable section reference (the actual heading is `## §Plan-Execute-Verify`, never `§PEV`). Defect was introduced in v3.7.0 (the §1 Catalog Lookup "Literacy gate" callout) and undetected by audits because `check-skill-frontmatter` is in the cascade-disabled set on this repo (see v3.7.1 detector-≠-enforcement framing — meta-irony noted). Fixed: `§PEV` → `§Plan-Execute-Verify` at L417.
+
+### Version drift correction
+
+v3.7.2's commit `0d1708994` updated `skill.json` to version 3.7.2 but did NOT update `SKILL.md` frontmatter (`version: 3.7.1` remained). Both fields must agree per the skill-frontmatter validator. v3.7.3 brings both to 3.7.3 in lockstep.
+
+### Why PATCH
+
+No new capability, no new modes, no new artifacts. Pure discovery + version-drift hygiene. SKILL.md body unchanged in this PATCH (no byte-budget impact).
+
+### Verify-target outputs at HEAD
+
+- `audit-kit-recipes` → 0 findings (164 substrate tags)
+- `audit-kit-recipes --strict` → exit 0
+- `npm run check:skills:audits:strict` → exit 0
+- `check-skills-seed-size` → 50,961 bytes (49.8KB) — unchanged from v3.7.2
+- Description length: 1017 chars (under 1024 limit, unchanged)
+- All adia-ui-kit individual gates green
+
+### What was NOT touched (deliberate)
+
+- **SKILL.md body** — discovery hooks live in `component-literacy.md` (the procedural cold-path that hits this material) + `spec-to-ui-reasoning.md` (the §SpecToUi-mode procedural path). Adding a SKILL.md pointer would trip the 50KB fail threshold; the reference-side hooks satisfy the "procedural region not bottom" rule because both files are loaded by the §SpecToUi and §1 cold-paths that consumers actually traverse.
+- **`adia-ui-authoring`'s SKILL.md discovery gap** — same omission exists in authoring's v1.8.2 (no SKILL.md pointer to `common-gotchas.md`). Not my lane; flag for authoring-side cleanup.
+
+### Cross-references
+
+- Peer commit: `0d1708994` (v3.7.2 absorption — this PATCH wires the discovery)
+- Sister-skill source: `adia-ui-authoring` v1.8.2 commit `62f57f973`
+- Sister handover: `.brain/handoffs/2026-05-25-session-handoff.md`
+
+---
+
+## 3.7.2 (2026-05-25)
+
+**PATCH** — Absorbs `adia-ui-authoring` v1.8.2's `common-gotchas` reference into kit's lane. The literacy gate (v3.7.0) forces CSS reads; this PATCH captures the four consumer-side patterns that recur even AFTER literacy is established — when reading isn't recognizing.
+
+### Sister-skill source
+
+`adia-ui-authoring` v1.8.2 commit `62f57f973` shipped its own `common-gotchas.md` reference with five concrete failure modes empirically discovered during the 2026-05-24 billing-overview rebuild + 8-demo grandfather-elimination cycle. Four are consumer-relevant; the fifth (nested `<!-- -->` in design-plan canonical-sketch blocks) is substrate-side authoring-specific and not absorbed.
+
+### What landed in kit v3.7.2
+
+**`../common-gotchas-consumer.md`** (~150 lines) — the four consumer-side gotchas with consumer-framing examples + how-to-detect + the right fix + sister-commit citation for each:
+
+1. **Composite used without using its composition grammar** — consumer wraps `<div>` children in card-ui/drawer-ui instead of using the canonical slot grammar. Audit: `audit:card-structure --strict` catches in substrate; consumer should run the same audit when they own substrate-adjacent code.
+2. **Parent CSS overriding child primitive's intrinsic display** — `.parent[state] > [data-empty] { display: block }` clobbers `empty-state-ui`'s `:scope { display: flex }`. Fix: invert toggle with `:not([state])`.
+3. **Mixed sizes across form/control groups** — toolbar with default `<button-ui>` + default `<search-ui>` + default `<tag-ui>` produces 3 different heights. Fix: set the SAME `size=sm` on every control; file substrate FB if a wrapper doesn't forward.
+4. **`minmax(<min>, 1fr)` inside `repeat()` fighting container queries** — minmax floor overflows BEFORE the container query collapses N. Fix: use plain `repeat(N, 1fr)` when container queries handle responsive.
+
+Each entry cites the sister chat-ui commit that fixed the pattern at substrate (`4e86400c9`, `4223a4147`, `1298fb064`, `94d497557`).
+
+### Meta-pattern captured
+
+**Defaults aren't contracts.** A primitive's default display/size/columns are starting points. When consumers override them, the override beats the default by specificity, NOT by correctness. Reading the primitive's `.css` end-to-end (the v3.7.0 literacy gate) catches the override-vs-default conflict at consumer-write time rather than visual-review time.
+
+### What was NOT absorbed (deliberate)
+
+- **Gotcha #5 — nested HTML comments in design-plan canonical-sketch blocks** — substrate-side authoring concern (Mode 8 protocol artifact format), not consumer-side. Kit consumers don't author design-plan comment blocks.
+- **The chat-ui audit-hardening commit `5f9ba216e`** — substrate-side audit script change. Kit cites the gate's existence; the script lives in chat-ui.
+
+### Why PATCH not MINOR
+
+No new capability surface, no new modes, no new required artifacts. Captures recurring patterns as a checklist reference that fires alongside existing literacy gate. Per §VersionBump policy: framing/pattern-capture absorption from sister skill = PATCH.
+
+### Cross-references
+
+- Sister skill: `adia-ui-authoring` v1.8.2 commit `62f57f973` (substrate-side common-gotchas + session handover)
+- Sister handover: `.brain/handoffs/2026-05-25-session-handoff.md`
+- Earlier kit absorptions: v3.7.0 (`da0439e69` — literacy + NAILED), v3.7.1 (`9940b39cb` — detector ≠ enforcement)
+
+---
+
+## 3.7.1 (2026-05-24)
+
+**PATCH** — Sibling-postmortem alignment with `adia-ui-authoring` v1.8.1. Closes the second-order failure mode the v3.7.0 absorption missed.
+
+### What v3.7.0 framed vs what v3.7.1 adds
+
+v3.7.0 absorbed authoring v1.8.0's CSS-illiteracy framing — agents treat components as APIs, don't read CSS, verify is structurally self-passable. That framing is correct but incomplete. Authoring v1.8.1 (commit `0564f6515` + `2778367e4`) ran the investigation forward and discovered: **the detector existed.** `audit-card-structure.mjs` was added 7 days before the breaking commit merged, was wired into `npm run check`, and was correctly exit-non-zero locally for the entire period the bypass shipped. The proximate failure was not authoring-context — it was **enforcement**.
+
+Two simultaneous failure modes:
+1. **Silent-by-omission** — `npm run check` is a chained `&&` pipeline of ~30+ scripts. An upstream gate failed first (`verify:exports-conditionals`), short-circuiting every downstream gate. 50/50 most-recent CI runs were RED with the card-structure audit never reached.
+2. **Silent-by-permission** — branch protection allowed merges despite red CI status.
+
+Net: the audit existed, was correct, was wired, exit-non-zero locally — and 38 violations still landed on `main` because neither the upstream chain nor branch protection was structurally sound.
+
+This is the same risk class kit faces. Kit's `audit-kit-recipes`, `audit-native-primitive-leak`, `audit-shell-composition`, `audit-demo-slot-vs-css` could pass locally for a kit consumer while never firing in CI for the same reasons. The v3.7.0 NAILED contract assumed local-pass = enforcement-pass. v3.7.1 closes that assumption.
+
+### Sister-skill source
+
+- `adia-ui-authoring` v1.8.1 commit `0564f6515` — sibling-postmortem version bump (skill itself: 2-line diff; the work is in the new postmortem + the chat-ui infra closures shipped in `2778367e4`)
+- Companion postmortem: `.brain/postmortems/2026-05-24-card-structure-audit-enforcement-gap.md`
+- Companion infra commit: `2778367e4` (audit-card-structure JS scan + `npm run audit:health` silent-failure surface + postmortem amendments)
+
+### What landed in kit v3.7.1
+
+**`../component-literacy.md` §NAILED contract extension:**
+
+- **New §Detector ≠ Enforcement subsection** with the v1.8.1 framing — the audit existing is not the same as the audit firing. Specific guidance for consumer repos vs substrate-adjacent work.
+- **Extended tier-claim discipline** — the `nailed` tier now requires THREE invariants: (1) literacy artifact EXISTS at expected path, (2) artifact is COMPLETE (no placeholders), (3) the verify session that produced the structurally-verified-only signals ACTUALLY RAN those audits (not assumed-to-have-run via a chained aggregate).
+- **New §Discovery: `npm run audit:health` subsection** — cites the chat-ui infra script (commit `2778367e4`) that runs every gate INDEPENDENTLY (not chained), producing a daily failure surface. Substrate-adjacent kit work should run it before claiming `nailed`.
+
+**Frontmatter `postmortem-precedent`:**
+
+- Promoted from single string to YAML list with both postmortems (v1.8.0 CSS-illiteracy + v1.8.1 enforcement-gap)
+
+**References section:**
+
+- Both postmortems now cited with framing notes for each
+
+**SKILL.md §PEV Mode 1-4 row** (tiny edit — net +15 bytes):
+
+- Reference to "v1.8.0–v1.8.1 NAILED contract incl. §Detector-≠-Enforcement framing"
+- "Verify each EXITED zero (don't trust `&& npm run check` — chains short-circuit; substrate consumers: `npm run audit:health`)"
+- Postmortem rationale row cites both postmortems instead of just v1.8.0's
+
+### What was NOT absorbed (deliberate)
+
+- **The `audit-card-structure.mjs` JS-scan extension** — substrate-side infra, not kit lane. Kit cites `audit-scripts.md` for what the bundled audits cover; the JS-scan extension is a chat-ui-substrate concern.
+- **The CI / branch-protection investigation** — chat-ui infra concern (the v1.8.1 postmortem explicitly scopes these as out-of-skill).
+- **The `audit-health-report.mjs` script** — substrate-side infra. Kit references its CLI surface (`npm run audit:health`) but doesn't ship the script.
+
+### Verify-target outputs at HEAD
+
+- `audit-kit-recipes` → 0 findings (164 substrate tags)
+- `audit-kit-recipes --strict` → exit 0
+- `npm run check:skills:audits:strict` → exit 0
+- `check-skills-seed-size` → **50,961 bytes (49.8KB)** — warn band, 239 bytes below 50KB fail (1 byte tighter than v3.7.0; net +15 bytes on SKILL.md body)
+- Description length: 1017 chars (under 1024 limit, unchanged from v3.6.0)
+- All adia-ui-kit individual gates green
+
+### Why PATCH not MINOR
+
+No new capability surface, no new modes, no new required artifacts. Refines the v3.7.0 NAILED contract with the v1.8.1 detector-vs-enforcement framing + extends the tier-claim discipline + adds `audit:health` cross-ref. Per §VersionBump policy, framing extension = PATCH.
+
+### Cross-references
+
+- Sister skill: `adia-ui-authoring` v1.8.1 commit `0564f6515` (sibling-postmortem version bump)
+- Sister infra commit: `2778367e4` (audit-card-structure JS scan + audit:health surface)
+- Companion postmortem: `.brain/postmortems/2026-05-24-card-structure-audit-enforcement-gap.md`
+- Original postmortem (v1.8.0 framing): `.brain/postmortems/2026-05-24-component-css-illiteracy.md`
+- Kit v3.7.0 commit: `da0439e69` (absorbed the v1.8.0 trio — this PATCH extends the third leg)
+
+---
+
+## 3.7.0 (2026-05-24)
+
+**MINOR** — Absorbs three disciplines from sister skill `adia-ui-authoring` v1.7.x–v1.8.0: level-boundary discipline (v1.7.1), Pre-flight Component Literacy gate (v1.8.0), and the NAILED status contract split (v1.8.0). Operator-driven: "review the recent changes made to adia-ui-authoring skill regarding design intent, decomposition, wireframing, understanding underlying CSS, etc. this also needs to be equally integrated into adia-ui-kit skill."
+
+The kit's central Goodhart-risk closed: kit §PEV Mode 1-4 verify-target ("render in playground + audit scripts pass") was structurally self-passable. Audits validate recipe markup against substrate yaml SoT but never measure visual proportions, never read primitive CSS, never check token contracts beyond name validity. A composition can pass every audit gate while shipping a visual defect because the agent never opened the components' `.css` files. The 2026-05-24 authoring CSS-illiteracy postmortem documented this is not a hypothetical — it is the default failure when verify metrics are author-designed and CSS reads are optional.
+
+### Sister-skill source
+
+`adia-ui-authoring` v1.7.0–v1.8.0 absorbed the same 3 disciplines at its Mode 8 composite-demo authoring tier. Kit v3.7.0 absorbs them at the composition tier. Both senior skills now share the literacy + NAILED disciplines; kit cites authoring as authoritative for the protocol shape and adds kit-specific operationalization.
+
+- v1.7.1 commit `57f688d2e` — level-boundary discipline (don't smuggle implementation tags into Level 1 region boxes)
+- v1.7.3 commit `1500a339e` — two-surface verify (QA isolation + site route) — kit-side SKIPPED (authoring-specific; consumer apps don't have a "site route" concept analogous to substrate demos)
+- v1.8.0 commit `5c86cd439` — Pre-flight Component Literacy gate + NAILED status contract split
+- Postmortem: `.brain/postmortems/2026-05-24-component-css-illiteracy.md`
+
+### New reference — `../component-literacy.md` (~16KB)
+
+The kit's analog of authoring's §Phase 2.5a Pre-flight Component Literacy. Fires in conjunction with kit §1 Catalog Lookup at the Rung 13 boundary when targeting the `nailed` tier of kit §PEV verify. Covers:
+
+- **3 invariants the gate enforces** — CSS-read-required fields (`default_render` / `slot_sizing_rules` / `exposed_tokens` / `embed_gotchas`), argued-choice fields (`why_chosen` + `alternatives_considered`), embedded-composite extra fields (`composite_renders_what` + `per_item_proportions.visual_note`)
+- **Output artifact shape** — full `<task>.preflight.yaml` schema with primitive entries + embedded-composite entries + patterns-referenced entries
+- **Worked-example reading** — real `<card-ui>` literacy entry showing what fabricable-vs-unfabricable looks like
+- **Verify-target checklist** — when the literacy gate is satisfied
+- **Cross-cycle-scope discipline** — embedded composites are NOT patchable from THIS task's cycle; surface visual-debt in `visual_note`, file substrate FB ticket, do not bypass embedded composite's own canonical verify
+- **NAILED status contract** — full split between `structurally-verified-only` (default; machine signals only) and `nailed` (above + literacy + visual ack)
+
+### Extended `../spec-to-ui-reasoning.md`
+
+- **Level-boundary discipline section** — per-level notation reference table (level 1 = semantic labels in boxes, level 5 = `<Thing>` tree in SEPARATE artifact below level 1; smuggling level 5 syntax into level 1 boxes = AP-07 Component collapse too early). Mirrors authoring's v1.7.1 protocol with kit-specific framing.
+- **Literacy gate precondition section** — explicit handoff between §SpecToUi (Rungs 0-12) and the new literacy gate (Rung 13 precondition). Forward-pointers to `component-literacy.md`.
+
+### SKILL.md changes (kept tiny — 50,946 bytes, 254 below 50KB fail)
+
+- **§SpecToUi bridges list** — Rung 13 literacy gate added: `component-literacy.md` cross-ref
+- **§PEV Mode 1-4 verify-target row** — split into two tiers (`structurally-verified-only` default + `nailed` opt-in). Postmortem rationale + tier-claim-honesty rule. Compressed prose so net SKILL.md delta is ~600 bytes.
+- **§1 Catalog Lookup section** — adds the literacy-gate-precondition callout. Forces the CSS read at primitive-selection time, not after-the-fact.
+
+### Verify-target outputs at HEAD
+
+- `audit-kit-recipes` → 0 findings (164 substrate tags)
+- `audit-kit-recipes --strict` → exit 0
+- `npm run check:skills:audits:strict` → exit 0
+- `check-skills-seed-size` → **50,946 bytes (49.8KB)** — warn band, **254 bytes below 50KB fail threshold** (very tight; next addition to SKILL.md body MUST be paired with a trim)
+- Description length: 1017 chars (under 1024 limit, unchanged from v3.6.0)
+- All adia-ui-kit individual gates green (frontmatter, patterns-sot 166 tags, extensibility, pev, seed-size, audits)
+
+### Why MINOR not PATCH
+
+Adds NEW capability (the literacy gate + NAILED tier contract is new ground; previously kit §PEV had a single verify path). Adds NEW required artifact for `nailed` tier (`<task>.preflight.yaml`). Per the kit's §VersionBump policy, new capability surface = MINOR.
+
+### What was NOT absorbed (deliberate scope discipline)
+
+- **Two-surface verify (authoring v1.7.3 §Phase 5.2)** — authoring-specific. Composite demos render in two surfaces (QA isolation harness + site route) at dev time; consumer apps don't have an analogous split. Conceptually similar (verify in the consumption context) but operational details don't transfer. If a kit consumer surfaces an analogous problem, revisit.
+- **The full `preflight.yaml` mechanical audit (authoring's forward `audit:preflight-completeness --strict`)** — not bundled in kit v3.7.0. Manual gate only. If consumer feedback shows skim-and-fabricate, build the mechanical check in v3.7.x.
+
+### Remaining open items at 2026-05-24
+
+The "Remaining open items" table in `REFACTOR-PROGRESS.md` shifts:
+- 🟡 **SKILL.md trim to <40KB warn-band exit** — re-tightened at 49.8KB (was 49.0KB at v3.6.1; v3.7.0 added ~600 bytes net to SKILL.md body for the literacy callouts). 254 bytes from fail. **Any further addition to SKILL.md MUST be paired with a trim of similar size.** Deferred until forced by next bump.
+- ⏰ DecisionModel hard-fail promotion — still calendar-blocked (eligible 2026-08-22)
+- 🟡 Mechanical preflight-completeness audit — new; ⏳ forward (when consumer feedback warrants)
+
+### Cross-references
+
+- Sister skill: `adia-ui-authoring` v1.7.1 (`57f688d2e`) + v1.7.3 (`1500a339e`) + v1.8.0 (`5c86cd439`)
+- Postmortem: `.brain/postmortems/2026-05-24-component-css-illiteracy.md`
+- Kit v3.6.0 commit: `7656e7751` (introduced §SpecToUi)
+- Kit v3.6.1 commit: `2861ad1a0` (tightened wireframe content discipline — established KP-04 anti-pattern this version extends)
+
+---
+
+## 3.6.1 (2026-05-24)
+
+**PATCH** — Tighten wireframe content discipline in `../spec-to-ui-reasoning.md` §Wireframe checkpoint. Operator concern: "make sure ASCII wireframes contents is crisp and concise and not include html etc."
+
+### What the v3.6.0 reference said vs what v3.6.1 makes explicit
+
+v3.6.0's §Wireframe checkpoint specified the 5 rubric levels + 6 gate dimensions but did not surface the **content boundary** of a wireframe artifact. A reader could (mis)interpret "Region wireframe with shell composition" as "use `<admin-shell>` boxes inside the wireframe." That collapses Rung 8 (AppShell) + Rung 13 (Component) into a single artifact — AP-07 (Component collapse too early) at the kit-protocol level.
+
+v3.6.1 makes the content boundary explicit with three additions:
+
+1. **Top-band callout** at §Wireframe checkpoint: *"Wireframes contain semantic labels, NOT AdiaUI primitive vocabulary. A wireframe with `<admin-shell>`, `<table-ui>`, or `<card-ui>` inside its boxes is collapsing Rung 8 (AppShell) + Rung 13 (Component) into a single artifact — that's AP-07 per the canonical rubric."*
+
+2. **"What goes INSIDE / What stays OUT" sub-sections**:
+   - INSIDE: rubric notation grammar (`+--+` regions, `[Control]`, `{State}`, `<Section>` semantic-component, `→`/`↓` flow, `[owns: ...]` ownership, `!` unresolved). Semantic labels ("Header" / "Sidebar" / "Lead Queue").
+   - OUT: AdiaUI tag names (`<admin-shell>`, `<table-ui>`), HTML markup (`<div>`, `<section>`, `<form>`, attributes), CSS/styling decisions (colors, typography, spacing), final density/pixel measurements.
+
+3. **CORRECT vs INCORRECT worked example** — ~25 lines of ASCII showing a clean wireframe (semantic labels + ownership annotations + state coverage) alongside an incorrect form that uses AdiaUI tag vocabulary (annotated with AP-07 callouts).
+
+4. **New KP-04 anti-pattern** — "AdiaUI tag vocabulary inside the wireframe" with symptom + root cause + correction. Joins KP-01 / KP-02 / KP-03 as kit-specific extensions of the canonical rubric's anti-patterns.
+
+5. **SKILL.md §SpecToUi callout** — adds KP-04 to the reference-section bullet list so the discipline appears at the cold-start fast-path layer, not buried in references/.
+
+6. **Region row trigger** — rewrote "Every Mode 1-4 composition with `<admin-shell>`, `<editor-shell>`, or any multi-area surface" → "Every Mode 1-4 composition with a shell/multi-area surface." Removes the AdiaUI tag from the trigger condition (wireframe is authored BEFORE shell is selected).
+
+### Why PATCH not MINOR
+
+No new capability surface; no new H2 sections in SKILL.md; refines existing §Wireframe checkpoint sub-section + extends KP anti-pattern enumeration by 1 entry. Per the kit's §VersionBump policy, clarification-class refinement = PATCH.
+
+### Verify-target outputs at HEAD
+
+- `audit-kit-recipes` → 0 findings (164 substrate tags)
+- `audit-kit-recipes --strict` → exit 0
+- `npm run check:skills:audits:strict` → exit 0
+- `check-skills-seed-size` → 49.0KB (warn band; **1,017 bytes below 50KB fail** — tight; future PATCH may need trim)
+- Description length: 1017 chars (under 1024 limit, unchanged from v3.6.0)
+- All adia-ui-kit individual gates green
+
+### Sister-skill alignment
+
+`adia-ui-authoring` v1.7.0 §Phase 2.5 already deferred to the canonical wireframing rubric for the same discipline. v3.6.1 brings the kit's reference into closer alignment — both senior skills now make the "wireframes are pre-component artifacts" boundary explicit in their own operationalizations.
+
+### Cross-references
+
+- Canonical rubric AP-07 (Component collapse too early): `~/.claude/skills/core-skills-best-practices/references/agents-ux-wireframing-ascii.md` §Anti-patterns
+- Canonical rubric AP-08 (Prose pretending to be wireframe): same file
+- v3.6.0 commit: `7656e7751` (introduced §SpecToUi mode + reference)
+
+---
+
+## 3.6.0 (2026-05-24)
+
+**MINOR** — New §SpecToUi mode (kit mode 15) for pre-composition reasoning from PRD/spec/intent input. Absorbs two canonical specs from `~/.claude/skills/` into the kit as **cited authoritative sources + AdiaUI-specific operationalizations**:
+
+1. **The 19-rung Generative UI Reasoning Ladder** (`ref-gen-ui-systems/references/reasoning-ladder.md`) — `InputContext → Intent → Domain → Role → Task → Decision → ExperiencePosture → InformationArchitecture → AppShell → Navigation → Surface → View → Section → Component → DataBinding → Interaction → State → Feedback → RenderPlan → Validation`.
+
+2. **The agents-ux-wireframing-ascii rubric** (`core-skills-best-practices/references/agents-ux-wireframing-ascii.md`) — 5 wireframe levels + 10 scoring dimensions + canonical notation grammar + 10 anti-patterns + 7-phase operating procedure.
+
+The kit's central pre-composition pitfall (AP-01 Premature Rendering) is now structurally prevented: when input is a PRD, spec, mockup, schema, role+user-story, or feature list, the §SpecToUi gate must resolve Rungs 0-5 + produce a wireframe artifact scored against the rubric's 6 [gate] dimensions BEFORE primitive emission.
+
+### Why this landed
+
+Operator request: "we desperately need some of these incorporated into adia-ui-kit workflows in order to properly comprehend what user might be asking for when reading specs or PRD documents that allude to UI or even very specific types of UI or UX flows."
+
+The kit's existing pipeline (`§Mission` → `§0 Reasoning Gate` → `§1 Catalog Lookup` → `§2 Composition` → `§3 Validation`) **starts at Rung 6 (ExperiencePosture)**. Rungs 0-5 (the pre-composition reasoning that converts ambiguous product intent into structured decisions) were implicit-or-missing. When the kit encountered a PRD it could pattern-match keywords to primitive vocabulary — "dashboard" → `<admin-shell>` + `<table-ui>` — without resolving the upstream user goal / domain / role / task / decision.
+
+The ladder + wireframing rubric IS the missing pre-composition pipeline. v3.6.0 adds it as §SpecToUi (the precondition gate for Modes 1-4 when input is unstructured product intent).
+
+### Sister skill alignment — adia-ui-authoring v1.7.0+
+
+Peer skill `adia-ui-authoring` (Mode 8 composite-demo authoring) absorbed the same canonical wireframing rubric at v1.6.0 + v1.7.0. The two senior skills now share the same authoritative spec for the wireframing discipline boundary. Both use the citation-not-duplication pattern: cite the canonical rubric, then add skill-specific operationalization. Cross-skill consistency is maintained.
+
+### New reference — `../spec-to-ui-reasoning.md` (~23KB)
+
+The kit-specific operationalization of the 2 canonical sources. Covers:
+
+- **The 19-rung pipeline with kit anchors** — Tier 4-5 of the ladder hands off to existing kit references (`decision-model.md`, `patterns-shells.md`, `state.md`, `catalog-lookup.md`, `composition.md`)
+- **Shell ↔ ExperiencePosture mapping (Rung 6 → Rung 8)** — 8 postures (monitoring / acting / analyzing / configuring / creating / reviewing / debugging / exploring) mapped onto 4 AdiaUI shells (admin / chat / editor / simple) with secondary-fit notes
+- **Decision ↔ Primitive mapping (Rung 5 → Rung 13)** — 8 decision archetypes (triage / comparison / status check / drilldown / assignment / creation / configuration / authentication) with primary primitive + verify-target
+- **Wireframe checkpoint** — when each rubric level is required + minimum-bar (Region + State levels for Mode 1-4); 6 [gate] dimensions all must score ≥ 3/5
+- **7 entry-point patterns** — PRD / vague brief / schema / mockup / role+user-story / feature list / component request (each with kit-specific process notes)
+- **3 kit-specific anti-patterns** — KP-01 Feature-as-task collapse; KP-02 Shell-vocabulary primacy; KP-03 Skipping the wireframe checkpoint
+- **Bridges** — explicit handoff tables from ladder rungs to existing kit references
+- **Verify-target checklist** — the gate's satisfaction criteria
+
+### SKILL.md changes
+
+- **Cold-start fast-path 14 modes → 15 modes** — adds Mode 15 §SpecToUi entry
+- **New §SpecToUi section** (between §Mission and §PEV; ~50 lines) — top-band stub with trigger phrases, full procedure pointer, canonical companion sources, verify-target
+- **§0 Reasoning Gate extended** — adds §SpecToUi precondition callout when input is unstructured product intent
+- **§PEV Mode 1-4 verify-target row** — adds "Precondition: §SpecToUi gate satisfied" prefix when applicable
+- **Frontmatter description** — extended to acknowledge §SpecToUi triggers (PRD/spec/mockup/schema/role+user-story/feature-list); slim to 1017 chars (under 1024 limit)
+- **Frontmatter trigger list** — adds ~80 PRD/spec/wireframing trigger phrases for routing eval coverage
+
+### Verify-target outputs at HEAD
+
+- `audit-kit-recipes` → 0 findings (164 substrate tags loaded)
+- `audit-kit-recipes --strict` → exit 0
+- `npm run check:skills:audits:strict` → exit 0
+- `check-skills-seed-size` → 48.6KB (warn band, fail at 50KB; up from 42.3KB at v3.5.2 — §SpecToUi added ~6.3KB)
+- Description length: 1017 chars (under 1024 limit)
+- All individual adia-ui-kit gates green (frontmatter, patterns-sot 166 tags, extensibility, pev, seed-size, audits)
+- Pre-existing peer-skill broken-section-references in adia-ui-a2ui, adia-ui-authoring, adia-ui-ops — NOT my lane
+
+### Why MINOR not MAJOR
+
+Adds a NEW capability mode (§SpecToUi) + a NEW precondition gate to Mode 1-4 verify-target. No breaking semantics of existing API; existing kit invocations that don't enter via PRD/spec input continue working unchanged. Per the kit's §VersionBump policy, new capability surface = MINOR.
+
+### Remaining open items at 2026-05-24
+
+The "Remaining open items" table in `REFACTOR-PROGRESS.md` shifts:
+- ✅ **PRD/spec → UI reasoning gap closed at v3.6.0** (new entry)
+- 🟡 **SKILL.md trim back to <40KB warn-band exit** — re-opens at 48.6KB (was 42.3KB at v3.5.2; §SpecToUi reclaimed ~6.3KB). Remaining trim would touch load-bearing sections (§Mission, §PEV, §SpecToUi); deferred.
+- ⏰ DecisionModel hard-fail promotion — still calendar-blocked (eligible 2026-08-22)
+- 🟡 Other deferrals unchanged
+
+### Cross-references
+
+- Canonical spec 1: `~/.claude/skills/ref-gen-ui-systems/references/reasoning-ladder.md` (19 rungs)
+- Canonical spec 2: `~/.claude/skills/core-skills-best-practices/references/agents-ux-wireframing-ascii.md` (wireframing rubric)
+- Sister skill: `adia-ui-authoring` v1.7.0 (Mode 8 §Phase 2.5 — same rubric, same citation pattern)
+- Sister-skill release commits: `5376cd14e` (authoring v1.7.0) + `53f26100a` (authoring v1.6.0) — established the citation pattern this kit version mirrors
+
+---
+
+## 3.5.2 (2026-05-24)
+
+**PATCH** — SKILL.md trim 47KB → 42.3KB (-4.8KB, 10% reduction). Closes two pre-existing broken-fence orphan-content defects from prior Phase 3 extractions where reference-file pointers were authored but the inline templates they were supposed to replace were never actually removed. New reference bundle for the bundled audit-scripts catalog.
+
+### Orphan-content defects closed
+
+Both defects were the same shape: a reference file was authored (Phase 3, v3.0.0), the SKILL.md was supposed to be trimmed to a pointer, but the trim was incomplete — the inline template content remained AND code-fence boundaries got broken. Each defect contributed ~2.5KB of orphan content + 1 unclosed fence to SKILL.md.
+
+**Defect #1 — `### §DiagnosticOutput` block (~3KB recovered)**
+
+The 7-section repo health report template (Repo identity & intent · State inventory · Gaps ranked by leverage · Recommended remediation plan · Out-of-scope exclusions · Verification gates · Overall posture assessment) was inline as a 4-backtick code fence (` ````markdown ... `) starting at line 216 of SKILL.md — but the closing ` ```` ` was missing. The 7 numbered H2 headings inside the orphan masqueraded as real SKILL.md sections (e.g. `## 1. Repo identity & intent`, `## 7. Overall posture assessment`). The full content already lives in [`../diagnostic-output.md`](../../references/diagnostic-output.md) (2,511 bytes). Trimmed to a thin pointer matching the established stub shape.
+
+**Defect #2 — `### Session log` + `### Feedback ticket` block (~2.5KB recovered)**
+
+Inside `## §Log & Tickets`, the session-log entry-format opened a 3-backtick fence (line 599) that never closed. Inside the unclosed fence: orphan `## N. <Title> (P<x>)` ticket-authoring template + Steps 5-6 + ANOTHER unclosed 3-backtick fence (line 663). All of it duplicated content already in [`../feedback-authoring.md`](../../references/feedback-authoring.md) (the canonical 6-step procedure with sub-templates) and [`../session-log-template.md`](../../references/session-log-template.md) (the entry format). Trimmed to two thin pointer paragraphs (session-log + ticket-authoring), matching the established stub shape.
+
+Fence count parity restored: 11 (odd, broken) → 10 (even, clean).
+
+### New reference — `audit-scripts.md` (-1.4KB from §PEV)
+
+Extracted the verbose audit-script enumeration from §Plan-Execute-Verify's Mode 1-4 row (a single table cell ballooned to ~1.6KB of inline prose describing 4 audit scripts inline). Replaced with a 1-line pointer + per-script tag. The new reference (`audit-scripts.md`, 3.4KB) covers:
+
+- When to run each script (table: 4 scripts × catches / triggers)
+- Severity classification (CRITICAL/HIGH/MEDIUM/INFO rubric)
+- Portability to consumer repos (cd into consumer; `--root=<substrate>` + `--kit=<skill-dir>`)
+- Wiring into the v3.5.0+ hard CI gate (`check:skills:audits` chain)
+
+Net §PEV size: 4,797 bytes → 3,429 bytes (-1.4KB).
+
+### Verify-target outputs at HEAD
+
+- `audit-kit-recipes` → 0 findings against v0.6.35 substrate (164 tags)
+- `audit-kit-recipes --strict` → exit 0
+- `npm run check:skills:audits:strict` → exit 0
+- `check-skills-seed-size` → `adia-ui-kit 43,362 bytes 42.3K ⚠ warn` (down from 45.7K; still warn band, fail threshold 50KB)
+- Fence count parity: 10 (even, clean)
+- 6/6 individual skill gates green for adia-ui-kit (frontmatter, patterns-sot 166 tags, extensibility, pev, seed-size, audits)
+
+### Why this is PATCH not MINOR
+
+No new capability surface; no new H2 sections in SKILL.md; one new reference file (`audit-scripts.md`) that absorbs already-present inline content. The trim is hygiene-class — restoring the original Phase 3 extraction intent. Per the kit's §VersionBump policy, hygiene-only is PATCH.
+
+### Remaining open items at 2026-05-24
+
+The "Remaining open items" table in `REFACTOR-PROGRESS.md` shifts:
+- 🟡 **SKILL.md trim 47KB → <40KB** — partial progress; recovered 4.8KB (47KB → 42.3KB), still ~2.3KB above 40KB warn threshold. Remaining trim would require touching load-bearing prose (§Mission, §PEV procedure) or further extracting bundle-map tables; deferred.
+- Other deferrals unchanged.
+
+---
+
+## 3.5.1 (2026-05-24)
+
+**PATCH** — Post-v0.6.35 housekeeping. Trims `KNOWN_*_DRIFT` allowlists in `audit-kit-recipes.mjs` against substrate fixes that shipped in the v0.6.35 lockstep cut. 4/7 entries removed; 3 remain because substrate documented the pattern in prose / sibling-yaml but didn't add a yaml `props:` entry on the target element.
+
+### Allowlist changes
+
+**`KNOWN_SUBSTRATE_YAML_DRIFT`** — 4 entries → 3 entries (1 removed):
+- ❌ `editor-sidebar|collapsible` — REMOVED. FB-61 resolved; `editor-sidebar.yaml` now declares `collapsible:` prop (substrate took Option A from the ticket — wire the observation). Audit now validates against yaml directly.
+- ✅ `chat-input-ui|submit-on-enter` — KEPT. RESPONSE-63 confirms substrate chose Option B (document Enter→submit as unconditional default; no opt-in/out attribute). The kit's recipe usage of the attribute remains a no-op convention; yaml has no prop to validate against.
+- ✅ `card-ui|span` — KEPT. Substrate added `[span="2..6"|"full"]` documentation in `grid-ui.yaml` (the parent that positions the attribute via CSS selectors). The attribute is still parent-driven; card-ui.yaml correctly does NOT declare it as its own prop. Recipes are valid; audit can't validate against card-ui yaml.
+- ✅ `otp-input-ui|autocomplete` — KEPT. Substrate documented `[autocomplete="one-time-code"]` in `otp-input.yaml` prose ("Always set [autocomplete=\"one-time-code\"] so iOS / Android..."). HTML-standard pass-through attribute is not added as a yaml prop (correct — it's not primitive-specific).
+
+**`KNOWN_PARENT_SLOT_DRIFT`** — 3 entries → 0 entries (all removed):
+- ❌ `popover-ui|trigger` — REMOVED. FB-62 resolved; `popover.yaml` `slots:` block now declares `trigger:` + `content:` (substrate took the exact Request from the ticket).
+- ❌ `popover-ui|content` — REMOVED (same fix).
+- ❌ `menu-ui|trigger` — REMOVED. FB-62 resolved; `menu.yaml` `slots:` block now declares `trigger:` (Required) + `default:` slots.
+
+`KNOWN_PARENT_SLOT_DRIFT` is empty for the first time since v3.4.2 introduced it — substrate's a2ui rules and yaml `slots:` block now agree. The empty Set + comments preserve the pattern for future drift entries.
+
+### Ticket lifecycle housekeeping
+
+All 5 ticket statuses flipped `responded → resolved` per the standard post-release flow:
+- FB-55 (admin-shell silent toggle fail) — RESPONSE-55 confirmed 8/8 + bonus delegation refactor
+- FB-57 (editor-shell demo slot-vocab drift) — RESPONSE-57 confirmed 7/7
+- FB-61 (editor-sidebar collapsible drift) — RESPONSE-61 confirmed 6/6
+- FB-62 (popover/menu slot vocab) — RESPONSE-62 confirmed 8/8
+- FB-63 (chat-input submit-on-enter) — RESPONSE-63 confirmed 7/7 + Option B chosen + bonus adjacent textarea/input prose lies
+
+REGISTRY rebuilt; all 5 tickets archived in `inbound/archive/` since `f31da1af2` (peer-agent commit).
+
+### Verify-target outputs at HEAD
+
+- `audit-kit-recipes` → exit 0, **0 findings** (against trimmed allowlist + v0.6.35 substrate)
+- `audit-kit-recipes --strict` → exit 0
+- `npm run check:skills:audits:strict` → exit 0
+- Manifest: 164 substrate tags loaded
+- All 9 packages lockstep at v0.6.35
+
+### Cross-references
+
+- v0.6.35 substrate release commits: `f13ee554e` (FB-55), `82c303153` (FB-57/61/62/63 yaml/demo/prose sweep), `f31da1af2` (RESPONSEs + archive), `e6883a4d2` (lockstep cut)
+- Substrate FB-tickets resolved this arc (v3.4.3 drafted, v0.6.35 shipped): FB-61, FB-62, FB-63
+- Inbound tickets resolved (claims-ui-v10 reports): FB-55, FB-57
+
+### Remaining open items at 2026-05-24
+
+The "Remaining open items" table in `REFACTOR-PROGRESS.md` shifts:
+- ✅ **Trim `KNOWN_*_DRIFT` allowlists** — closed at v3.5.1 (this commit). 4/7 entries trimmed; 3 documented as enduring substrate convention (not bugs).
+- ⏰ **DecisionModel hard-fail promotion** — still calendar-blocked (eligible 2026-08-22)
+- 🟡 Other deferrals unchanged (session-log retention, SKILL.md <40KB trim, v3.1.3 D4 audit upgrades).
+
+---
+
+## 3.5.0 (2026-05-24)
+
+**MINOR** — Promotes the v3.4.X-arc audits to **hard CI gates**. `npm run check:skills:strict` now invokes `audit-kit-recipes.mjs --strict` and `audit-shell-composition.mjs`, blocking PRs on any new kit recipe drift or substrate-side admin-shell composition regression. With v3.4.2/v3.4.3's baseline of **0 findings preserved**, this gate has zero ongoing maintenance cost while catching all known regression classes mechanically.
+
+### What changes
+
+`package.json` scripts:
+
+```diff
+- "check:skills": "...check-skill-frontmatter && ...check-skill-patterns-sot && ...check-extensibility && ...check-pev"
++ "check:skills": "...frontmatter && ...patterns-sot && ...extensibility && ...pev && npm run check:skills:audits"
+
+- "check:skills:strict": "...frontmatter --strict && ...patterns-sot --strict && ...extensibility --strict && ...pev --strict && ...seed-size --strict"
++ "check:skills:strict": "...frontmatter --strict && ...patterns-sot --strict && ...extensibility --strict && ...pev --strict && ...seed-size --strict && npm run check:skills:audits:strict"
+
++ "check:skills:audits": "node .agents/skills/adia-ui-kit/scripts/audit-kit-recipes.mjs && node .agents/skills/adia-ui-kit/scripts/audit-shell-composition.mjs"
++ "check:skills:audits:strict": "node .agents/skills/adia-ui-kit/scripts/audit-kit-recipes.mjs --strict && node .agents/skills/adia-ui-kit/scripts/audit-shell-composition.mjs"
+```
+
+### Design decisions
+
+**`audit-kit-recipes --strict` IS in the strict gate.** Exits 1 on any CRITICAL or HIGH finding (currently 0). With v3.4.2's mechanization + v3.4.3's hardening + 0-finding baseline, any new fictional tag in a recipe (e.g. `<form-container-ui>`, `<router-ui>`, `<dialog-ui>`) immediately blocks the PR.
+
+**`audit-shell-composition` is NOT in `--strict` mode**, but IS in the gate with default exit logic. The script's default-mode `process.exit(1)` only fires on CRITICAL findings (line 647: `if (counts.critical > 0) process.exit(1)`). `--strict` mode would additionally fail on info-level (advisory) findings, including the substrate's current 4 info findings on edge-case patterns. Including default-mode catches real regressions (broken shell composition) without false-positive blocking on substrate edge cases.
+
+**Strict pipeline scope is unchanged.** The new gate ONLY adds the two audit scripts. No skill files were touched. No reference content was edited. The strict-mode bar is the same one v3.4.2 + v3.4.3 already enforce manually — this commit just wires it into the existing `npm run check:skills:strict` chain so PR / pre-commit / CI invocations all run it automatically.
+
+### Regression catch matrix
+
+The gate now catches these classes mechanically (was: manual run only):
+
+| Regression class | Caught by | Exit |
+|------------------|-----------|------|
+| Fictional custom-element tag in a kit recipe (e.g. `<form-field>`, `<router-ui>`, `<dialog-ui>`, `<theme-ui>`) | audit-kit-recipes CRITICAL | 1 |
+| Unknown attribute on a known primitive (e.g. `<button-ui icon-leading>`, `<modal-ui show>`, `<tab-ui name>`) | audit-kit-recipes MEDIUM (in `--strict` it counts) | 1 in strict |
+| Stale slot-on-child (e.g. `<admin-sidebar slot="sidebar">` instead of `slot="leading"`) | audit-kit-recipes INFO + audit-shell-composition CRITICAL | 1 |
+| Missing canonical admin-shell parts (e.g. no `<admin-scroll>`, no `<admin-command>`, `<admin-topbar>` outside `<admin-content>`) | audit-shell-composition CRITICAL | 1 |
+| Substrate manifest empty (audit wrongly invoked) | audit-kit-recipes empty-substrate-manifest | 2 |
+| Kit references/ empty | audit-kit-recipes empty-kit-references | 2 |
+| 0 HTML files in audit-shell-composition (consumer-repo or empty-substrate) | audit-shell-composition zero-files-scanned | 1 |
+
+### Smoke-test verification
+
+Simulated regression test passed (run inline during v3.5.0 dev):
+
+```bash
+# Inject fictional tag into a kit recipe
+sed -i 's/<card-ui>/<fictional-tag-ui-test><\/fictional-tag-ui-test><card-ui>/' patterns-data.md
+
+# Gate should fail
+npm run check:skills:audits:strict
+# → audit-kit-recipes: CRITICAL <fictional-tag-ui-test>; exit 1
+
+# Revert and re-run
+git checkout -- patterns-data.md
+npm run check:skills:audits:strict
+# → 0 findings, exit 0
+```
+
+### Verify-target outputs at HEAD
+
+- `npm run check:skills:audits` → exit 0 (0 findings + 4 info-only)
+- `npm run check:skills:audits:strict` → exit 0 (audit-kit-recipes --strict 0 + audit-shell-composition default 0)
+- `npm run check:skills:strict` → my work clean; sibling skill `adia-ui-a2ui` has a pre-existing broken-section-reference from peer commit `7784e94f0` (NOT in my lane; the full pipeline shortcircuits on that error before reaching the audit gate). Once that peer issue is resolved, the audit gate will run and pass.
+- run-skill-evals.mjs --strict → routing F1 90.9%, teach-routing 9/9, exit 0
+- audit-kit-recipes manifest: 163 substrate tags loaded
+
+### Migration note for downstream consumers
+
+If a consumer repo runs `npm run check:skills:strict` (via the kit's bundled test pipeline), the v3.5.0 upgrade adds two more invocations to the chain. Both are zero-overhead at HEAD baseline but will block any kit recipe regression. No action required from consumers — the gate auto-detects substrate + kit dirs via the existing `--root` / `--kit` flags (defaulting to cwd).
+
+### What's next
+
+Three substrate FB tickets (FB-61, FB-62, FB-63) drafted in v3.4.3 are awaiting substrate-author-lane processing. When each resolves, the corresponding `KNOWN_*_DRIFT` allowlist entry in audit-kit-recipes.mjs can be removed and the audit will catch regressions naturally going forward.
+
+### Cross-references
+
+- `package.json` (gate wiring) — only file changed in v3.5.0
+- v3.4.0 (audit-kit-recipes.mjs initial ship)
+- v3.4.1 + v3.4.2 (recipe drift burndown 83 → 0)
+- v3.4.3 (FB-58/59/60 closure + audit hardening + FB-61/62/63 drafts)
+
+---
+
+## 3.4.3 (2026-05-24)
+
+**PATCH** — Closes 3 new kit-lane feedback tickets (FB-58, FB-59, FB-60) from claims-ui-v10's 2026-05-24 §CorrectionLoop session. Hardens both bundled audit scripts (audit-shell-composition.mjs + audit-kit-recipes.mjs) against silent 0-files false-negatives in consumer repos. Drafts three substrate FB tickets (FB-61, FB-62, FB-63) for the yaml drifts queued in v3.4.2's `KNOWN_*_DRIFT` allowlists.
+
+### Tickets closed (kit lane)
+
+**FB-58 (P2) — Pre-author bundle gate inconsistency.** SKILL.md stub listed `patterns-shells.md + patterns-recipes.md + loading-protocol.md` (wrong order, missing patterns-layout.md, listed loading-protocol.md as bundle 3 after generation would have started). Loading-protocol.md correctly says `patterns-recipes.md → patterns-shells.md → patterns-layout.md`. Three composition/fix turns in claims-ui-v10 loaded only `patterns-shells.md`. Root cause: SKILL.md stub authored before loading-protocol.md was extracted as standalone reference; the two diverged with no cross-ref enforcement.
+
+Fix (3 findings, all in §1):
+- **§1 — SKILL.md stub** now defers to `loading-protocol.md` as the authoritative bundle list; lists current order inline (recipes → shells → layout) but tags it as "currently" so updates flow naturally from loading-protocol.md without re-syncing here. Includes the "load patterns-recipes.md FIRST because its 'Advanced — full markup' is the start-here baseline" rationale.
+- **§2 — `<admin-topbar slot="header">` vs no-slot** canonical conflict. Both files now acknowledge both forms work (light-DOM per ADR-0033 makes slot= inert on `<admin-content>`; CSS positions by tag + DOM order regardless). Loading-protocol.md item 7 has the cross-ref note; patterns-recipes.md gets a footnote on the comparison table row + a callout in the SoT-alignment block. Code review noise eliminated; "do not 'fix' one to the other" is now explicit.
+- **§3 — `[data-actions]` vs `slot="action"` + missing CTA-placement rule.** Loading-protocol.md item 8 now declares `slot="action"` as new-code canonical (v0.6.13+) AND adds a 🚨 CRITICAL CONTENT RULE: page-scoped CTAs (`+ New Claim`, `Export CSV`) belong in `<admin-page-header>` as `<button-ui slot="action">`, NOT in the topbar trailing cluster (which is GLOBAL controls only — theme picker, notifications, sidebar toggles). The rule is now first-class instead of implicit-in-a-route-fragment.
+
+**FB-60 (P2) — flows-data.md missing `<section-ui>` wrappers inside `<admin-page-body>`.** admin-page-body.yaml a2ui rule says "Wraps an inner `<section-ui>` by default for centered reading-column rhythm; for full-bleed content (tables, canvas grids) use `[data-full-bleed]` on the section." Two flows-data.md recipes (Settings page line ~14, Dashboard + KPI line ~178) put `<article>` and `<col-ui>` directly inside `<admin-page-body>`, bypassing the reading-column CSS targeting.
+
+Fix:
+- Settings page recipe: wrapped `<article>` in `<section-ui>` (centered reading-column for text-heavy settings).
+- Dashboard + KPI recipe: wrapped `<col-ui>` in `<section-ui data-full-bleed>` (tables + charts want full content width; `[data-full-bleed]` opts out of the reading-column rhythm per yaml's escape hatch). Added a multi-line comment teaching the centered-vs-full-bleed decision so future authoring uses the right one.
+
+### Tickets closed (bundled-substrate-script lane: audit-shell-composition.mjs)
+
+**FB-59 (P2) — `audit-shell-composition.mjs` silent false-negatives in consumer repos.** The script ships in `.agents/skills/adia-ui-kit/scripts/` (bundled-as-skill-artifact = kit lane). Three bugs:
+
+- **Bug A: 0-files state masquerading as clean pass.** Default scan paths (`apps/`, `playgrounds/`, `catalog/`) are substrate-only; consumer repos don't have them. `walkHtml` would silently return `[]` and the script would report "0 critical, 0 warning, 0 info" + exit 0 — indistinguishable from a real clean pass. In claims-ui-v10 a broken admin-shell with 5 CRITICAL+WARNING defects passed the gate undetected across multiple composition turns. Fix: detect `filesScanned.length === 0` BEFORE entering the per-mode output branch; print a SCAN-COVERAGE warning + exit 1. Both human and `--json` modes emit the same signal (json mode emits `{error: "zero-files-scanned"}`).
+- **Bug B: `--include=index.html` plain filename treated as directory.** `walkHtml(root)` called `readdirSync(root)` which throws on file paths; the catch block silently returned `[]`. Fix: `statSync(root)` first; if it's a file, push it directly when it ends in `.html`. The `--include=index.html` invocation now correctly reads the file content.
+- **Bug C: no consumer-repo fallback.** When defaults yield 0 files AND no explicit `--include` was passed, auto-retry against `CONSUMER_FALLBACKS = ['index.html', 'src', 'public']`. Backward-compatible: substrate repos always find HTML files on the first pass and the fallback never fires. Consumer repos now get sensible defaults with zero configuration.
+
+Verification (all 4 scenarios pass):
+- Substrate (chat-ui) default scan: exit 0, finds expected info findings
+- Empty dir: exit 1 with "0 HTML files scanned" warning
+- Consumer repo broken shell (default scan): exit 1 via fallback, CRITICAL findings reported
+- Consumer repo broken shell (`--include=index.html`): exit 1, CRITICAL findings reported
+
+### Hardening — audit-kit-recipes.mjs (preemptive FB-59-class fixes)
+
+Same 0-files-class hardening applied preemptively to the v3.4.0 audit-kit-recipes.mjs:
+- Empty substrate manifest (e.g. `--root=/wrong-path`) → exit 2 with "empty-substrate-manifest" error
+- Empty kit references/ (e.g. `--kit=/non-skill-dir`) → exit 2 with "empty-kit-references" error
+- Both modes (human + `--json`) emit the same signal
+
+Verified 3 scenarios: happy path (exit 0), bad root (exit 2), empty refs dir (exit 2).
+
+### Substrate FB-ticket drafts (FB-61, FB-62, FB-63)
+
+Three substrate-author-lane tickets drafted in `.agents/team/tickets/drafts/` for the yaml drifts queued in v3.4.2's `KNOWN_*_DRIFT` allowlists. Each carries the substrate's verification trace + two options (A: wire the missing behavior; B: align .claude/docs/demos to actual JS):
+
+- **FB-61** — `editor-sidebar [collapsible]`: yaml omits, demos use, JS docstring documents, JS never observes. `.toggle()`/`.collapse()`/`.expand()` are unconditional. Sibling primitive `<admin-sidebar>` correctly observes `[collapsible]`. Pick: wire observation (A) or remove from docs+demos (B).
+- **FB-62** — `popover-ui` slots `{}` but CSS positions `[slot="trigger"]` + `[slot="content"]` (5 selectors) and a2ui rule says "trigger + content"; `menu-ui` slots only lists `default` but a2ui rule says trigger child is "MUST have exactly one." Fix: backfill `slots:` blocks from the a2ui rule vocabularies. ~15 yaml lines total.
+- **FB-63** — `chat-input-ui [submit-on-enter]`: kit recipes + substrate demos use it as opt-in; JS submits on Enter unconditionally; yaml doesn't declare it; JS doesn't observe it. Pick: add `[no-submit-on-enter]` opt-out (A) or remove from demos + update docs to "unconditional" (B).
+
+When substrate resolves any of these, the corresponding `KNOWN_*_DRIFT` allowlist entry gets removed and the audit catches regressions.
+
+### Audit baseline at HEAD
+
+```
+audit-kit-recipes              → 0 findings, exit 0
+audit-kit-recipes --strict     → exit 0
+audit-shell-composition        → 0 critical / 0 warning / 4 info, exit 0
+audit-shell-composition --strict (substrate)  → exit 0
+audit-shell-composition (consumer repo)       → now-functional (was silently false-negative)
+```
+
+### Verify-target outputs at HEAD
+
+- check:skills:strict → my changes clean; **adia-ui-a2ui** has a pre-existing broken-section-reference from peer commit `7784e94f0` (NOT in my lane; deferred to peer-agent fix)
+- run-skill-evals.mjs --strict → routing F1 90.9%, teach-routing 9/9, exit 0
+- audit-kit-recipes (default) → exit 0, 0 findings
+- audit-shell-composition: substrate scan exit 0; consumer-repo + 0-files paths newly functional + exit 1 correctly
+- Manifest: 156 → 163 (peer landed 7 new substrate primitives since v3.4.2; growth tracked via re-run)
+
+### What's coming in v3.5.0
+
+Per user request: promote `audit-kit-recipes --strict` to a hard CI gate (wire into `npm run check:skills:strict`). With v3.4.2's baseline of 0 findings — preserved at v3.4.3 — regressions in kit recipe drift will block PRs automatically.
+
+### Cross-references
+
+- FB-58 (closed): `.agents/team/tickets/inbound/FEEDBACK-58--adia-ui-skill--2026-05-24--*.md`
+- FB-59 (closed): `.agents/team/tickets/inbound/FEEDBACK-59--adia-ui-skill--2026-05-24--*.md`
+- FB-60 (closed): `.agents/team/tickets/inbound/FEEDBACK-60--adia-ui-skill--2026-05-24--*.md`
+- FB-61 (draft): `.agents/team/tickets/drafts/FEEDBACK-61--adia-ui--2026-05-24--editor-sidebar-collapsible-attr-yaml-js-demo-three-way-drift.md`
+- FB-62 (draft): `.agents/team/tickets/drafts/FEEDBACK-62--adia-ui--2026-05-24--popover-menu-slot-vocab-yaml-vs-css-drift.md`
+- FB-63 (draft): `.agents/team/tickets/drafts/FEEDBACK-63--adia-ui--2026-05-24--chat-input-submit-on-enter-recipe-convention-no-observation.md`
+
+---
+
+## 3.4.2 (2026-05-23)
+
+**PATCH** — Burns down the remaining 60 MEDIUM kit-recipe findings + 6 INFO. Kit recipes now have **ZERO drift** against substrate yaml/CSS/a2ui-rules SoT. `audit-kit-recipes` exits 0 with 0 findings (was 83 at v3.4.0 baseline). The v3.4.X recipe-staleness arc that started at v3.4.0 with the mechanization is now closed.
+
+### Findings closed (27 drift classes × 60 occurrences → 0)
+
+| Class | Occurrences | Resolution |
+|-------|-------------|------------|
+| `<button-ui icon-leading>` | 5× | Rename attr `icon-leading` → `icon` (substrate has only `icon`; no leading/trailing variant) |
+| `<input-ui icon-leading>` | 3× | Rename attr `icon-leading` → `prefix` (substrate convention: `prefix`/`suffix` are leading/trailing icon attrs on input-ui) |
+| `<input-ui icon-trailing>` | 2× | Rename attr `icon-trailing` → `suffix` |
+| `<input-ui icon>` | 1× | Rename attr `icon` → `prefix` |
+| `<modal-ui show>` | 1× | Rename attr `show` → `open` (substrate boolean reflected attr) |
+| `<drawer-ui show position>` | 1× | Rename `show` → `open`, `position` → `side` |
+| `<tab-ui name>` | 3× | Rename attr `name` → `value` (substrate uses `value` for identifier) |
+| `<tabs-ui active>` | 1× | Rename attr `active` → `value` |
+| `<tab-ui selected>` | 1× | Remove attribute — selection lives on parent `<tabs-ui value=...>`, not the tab itself |
+| `<segmented-ui name>` | 2× | Remove attribute — substrate has only `value`; `name=` was decorative |
+| `<pane-ui size>` | 9× | Rename attr `size` → `min-width` with numeric value (sm=200, md=320; substrate has `minWidth/maxWidth` with `attribute: min-width/max-width`) |
+| `<row-ui size>` | 1× | Remove — row-ui has `gap`/`align`/`justify`/`grow`/`wrap`, no `size`; the `sm` value was decorative |
+| `<otp-input-ui size>` | 1× | Remove — substrate has `length` (already present alongside); size was duplicative |
+| `<input-ui hint>` | 1× | Move `hint` to wrapping `<field-ui hint="...">` — field-ui owns label+hint, input-ui doesn't |
+| `<chat-input-ui grow>` | 1× | Replace with `style="flex:1"` — substrate has no `grow` prop |
+| `<avatar-ui color>` | 1× | Remove — substrate avatar-ui derives color from `name=` auto-hash; `color="danger"` was inert |
+| `<text-ui tracking>` | 2× | Replace with `style="letter-spacing:0.05em"` — substrate text-ui has no tracking prop |
+| `<chat-sidebar persist>` | 1× | Rename `persist` → `name` — chat-sidebar uses `name` for localStorage key (editor-sidebar uses both `persist` and `name` aliases; chat-sidebar only has `name`) |
+| `<pagination-ui page-size>` | 2× | Remove — substrate has `total/page/siblings`; `page-size` is a consumer-side state concept |
+| `<progress-ui max>` | 1× | Remove — substrate has only `value` (0-100 convention); no max prop |
+| `<badge-ui dot>` | 1× | Rewrite as `variant="info" size="xs"` — substrate has no `dot` prop |
+| `<table-toolbar-ui` slot misuse (`title|count|action`) | 1× | Rewrite to use props (`text=` + `count=` as table-toolbar-ui PROPS, plural `slot="actions"` per yaml) |
+
+### Audit script enhancements
+
+The 60→0 burndown also required several audit-script improvements caught during triage:
+
+**1. Framework template syntax suppression** (false-positive class fixed). `parseAttrs` was tokenizing `@change="..."` as a bare `change` attribute, producing a phantom MEDIUM finding on Vue template syntax. New regex anchors attribute names at whitespace boundaries, and `isGlobalishAttr` was extended to suppress:
+- Vue: `@click`, `:value`, `v-on:`, `v-bind:`, `v-if`, `v-for`, `v-model`, `v-show`, `v-html`, `v-text`, `v-slot`
+- Svelte: `on:click`, `bind:value`, `use:directive`, `class:foo`
+- Angular: `(click)`, `[value]`, `*ngIf`, `*ngFor`, `[(ngModel)]`
+- Alpine: `x-data`, `x-on:click`, `x-bind:value`
+- Lit: `@click`, `?disabled`, `.value`
+
+**2. `KNOWN_SUBSTRATE_YAML_DRIFT` allowlist** (substrate-author-lane drift recorded in-audit). Suppresses findings on attributes that the substrate's own canonical demos use but yaml doesn't declare:
+- `editor-sidebar|collapsible` — JS docstring + examples.html use `[collapsible]` but yaml omits it AND JS never observes it. `.toggle()`/`.collapse()`/`.expand()` are unconditional. Substrate ticket-worthy.
+- `chat-input-ui|submit-on-enter` — Enter-to-submit is default JS behavior; the attribute is a recipe convention with no observation.
+- `card-ui|span` — `<grid-ui>`'s CSS uses `> [span="N"]` selectors to position children. Same parent-driven positioning pattern as shell-tier slot CSS (ADR-0033). Not a card-ui prop; a grid-ui parent API.
+- `otp-input-ui|autocomplete` — HTML-standard attribute that passes through to the internal `<input>`. Required for OTP autofill (a11y/security).
+
+**3. `KNOWN_PARENT_SLOT_DRIFT` allowlist** (substrate yaml-vs-a2ui-rules drift). Suppresses INFO slot-mismatch findings when the parent's a2ui rules / CSS document a slot but yaml `slots:` block doesn't:
+- `popover-ui|trigger`, `popover-ui|content` — popover.css positions `[slot="trigger"]` and `[slot="content"]`; yaml says `slots: {}` while the a2ui rule explicitly documents "trigger + content".
+- `menu-ui|trigger` — menu.yaml's a2ui rule says "MUST have child slot='trigger'" but yaml `slots:` only lists `default`.
+
+### Audit baseline shift across v3.4.X arc
+
+| Version | Real findings | CRITICAL | HIGH | MEDIUM | INFO | --strict |
+|---------|---------------|----------|------|--------|------|----------|
+| v3.4.0  | 83            | 15       | 0    | 62     | 6    | exit 1   |
+| v3.4.1  | 69            | **0**    | 0    | 61     | 8    | exit 0   |
+| **v3.4.2** | **0**       | **0**    | 0    | **0**  | **0**| exit 0   |
+
+The kit's recipes are now provably aligned with substrate canon. The discovery instrument (audit-kit-recipes.mjs) shipped at v3.4.0 has paid off — every drift class detected then is now closed.
+
+### Substrate FB tickets to file (deferred)
+
+Three substrate drifts surfaced during this arc deserve substrate-author-lane attention. The kit's audit currently suppresses them via `KNOWN_SUBSTRATE_YAML_DRIFT` / `KNOWN_PARENT_SLOT_DRIFT`; substrate should harmonize yaml ↔ JS ↔ CSS:
+
+1. **`editor-sidebar [collapsible]`** — yaml omits, examples.html uses, JS docstring documents, JS never observes. Either wire observation (probably the intent) or remove from demos.
+2. **`popover-ui` + `menu-ui` slot vocab** — yaml `slots:` block is missing the canonical `trigger`/`content` slots that CSS positions and a2ui rules document.
+3. **`chat-input-ui [submit-on-enter]`** — recipe-only convention; substrate JS submits on Enter by default with no opt-in attribute. Decide: add the observed opt-out attr `[no-submit-on-enter]`, or remove the redundant attr from all recipes/docs.
+
+These would graduate from `KNOWN_*_DRIFT` allowlists to real substrate fixes (with the kit's audit then catching any regression).
+
+### What's coming next
+
+The v3.4.X recipe-staleness arc is closed. Next opportunities:
+1. **v3.5.0 (MINOR)** — promote `audit-kit-recipes --strict` to a hard CI gate (run in `npm run check:skills:strict`). Current baseline of 0 findings means it can't regress without a CI failure.
+2. **v3.4.3 (PATCH)** — file the three substrate FB tickets above, removing entries from `KNOWN_*_DRIFT` once substrate resolves.
+3. **Idle** — let the audit catch substrate drift as it lands. The kit is now in a steady-state where new substrate primitives + new recipe authoring trigger the audit naturally.
+
+### Verify-target outputs at HEAD
+
+- check:skills:strict → 5/5 senior, 0 P-failures
+- run-skill-evals.mjs --strict → routing F1 90.9%, teach-routing 9/9, exit 0
+- audit-kit-recipes (default) → exit 0, **0 findings**
+- audit-kit-recipes --strict → exit 0
+- Manifest grew 156 → 160 (peer landed 4 new substrate primitives during this turn)
+- SKILL.md size unchanged in this PATCH (version bump only)
+
+---
+
+## 3.4.1 (2026-05-23)
+
+**PATCH** — Burns down all 15 CRITICAL findings from the v3.4.0 audit baseline. Kit recipes no longer reference any non-existent custom-element tag. `audit-kit-recipes --strict` now exits 0 (was exit 1 at v3.4.0 due to CRITICAL findings).
+
+### Findings closed (9 unique tags × 15 occurrences → 0)
+
+Each fix grep-verified against substrate yaml before commit per the v3.4.0 register's verification contract.
+
+| Stale tag | Replacement | Files |
+|-----------|------------|-------|
+| `<form-field>` | `<field-ui>` (substrate primitive) | `../decision-model.md` (2×) |
+| `<breadcrumb-item-ui>` | plain `<a>`/`<span>` children inside `<breadcrumb-ui>` (separator auto via CSS `::before`; no item element) | `../patterns-shells.md` (2×) |
+| `<form-container-ui>` | raw `<form>` element with `action=` / `method=` attrs | `../patterns-forms.md` (2× + prose) |
+| `<datetime-ui>` | `<datetime-picker-ui>` (v0.6.34 new primitive) wrapped in `<field-ui label="...">` for labels (datetime-picker-ui has no `label` or `type` props) | `../patterns-forms.md` (1×) |
+| `<dialog-ui title="..." message="..." confirm-text="..." cancel-text="...">` | `<confirm-dialog-ui>` (web-modules/feedback) — same attrs except `message` → `description` | `../patterns-layout.md` (1×) |
+| `<theme-ui preset=... chroma=... space-scale=...>` | `<popover-ui>` containing `<theme-panel parametric presets scheme-toggle slot="content">`. Parametric tuning happens via CSS custom properties (`--a-density`, `--a-radius-k`, etc.) — `theme-ui` was a fictional element documenting parametric application as an attribute API. | `../patterns-layout.md` (1×) |
+| `<gen-ui-chat>` / `<gen-ui-thread>` / `<gen-ui-canvas>` / `<gen-ui-inspector>` / `<gen-ui-pipeline-status>` | Rewrote entire "Gen UI Chat System" section as "Chat Shell (canonical substrate composition)" using `<chat-shell>` + `<chat-header>` + `<chat-thread>` + `<chat-composer>` + `<chat-input-ui>` per ADR-0023. Cross-refs `flows-shells.md` and `chat-shell.examples.html`. | `../patterns-agent.md` |
+| `<a2ui-playground chat code>` | Removed. Pointed at real playground apps (`apps/genui/` and `playgrounds/composed-flow/`) which compose `<a2ui-root>` + dev panels — there is no dedicated playground primitive. | `../patterns-agent.md` (1×) |
+| `<router-ui>` (4 occurrences) | HTML comment placeholder — `<!-- your router outlet here -->`. The fictional element was a didactic placeholder for the SPA route-owner concept, but a comment makes the substitution-required intent clearer and stops the audit from flagging the kit's own recipes as drifted. Surrounding prose preserved (per-framework substitution table still teaches the routing-ownership pattern). | `../flows-shells.md`, `../patterns-recipes.md` (2×), `../rendering-model.md` |
+
+### Audit baseline shift
+
+- **Before (v3.4.0):** 83 real findings (15 CRITICAL, 0 HIGH, 62 MEDIUM, 6 INFO), `--strict` exit 1
+- **After (v3.4.1):** 69 real findings (0 CRITICAL, 0 HIGH, 61 MEDIUM, 8 INFO), `--strict` exit 0
+- **Net:** -14 findings (-17%); CRITICAL → 0 (the high-blast-radius class is fully closed)
+
+The 8 INFO are advisory-only (slot-vocab vs yaml-slots non-authoritative shell-tier — same false-positive class noted in v3.4.0 CHANGELOG). The 2 net-new INFO are from the new `<popover-ui>` + `<theme-panel slot="content">` example I introduced — same `popover-ui` slot pattern already used elsewhere in patterns-recipes.md.
+
+### Anti-pattern context absorbed
+
+The substrate manifest grew 152 → 156 between v3.4.0 baseline and v3.4.1 (peer-agent landed 4 new primitives — likely from the v0.6.34 + v0.6.35 spec hand-authoring wave). Re-running `audit-kit-recipes` against the live manifest each run keeps findings honest to current state.
+
+### Editorial improvements absorbed alongside the fixes
+
+While rewriting the patterns-agent.md "Chat Shell" section:
+- Replaced the fictional gen-ui-* component family table with a real substrate-element table including `chat-status`, `chat-empty`, `chat-sidebar`, and the `:has()` state-as-attribute cross-cut pattern per ADR-0023
+- Added cross-refs to `flows-shells.md` (canonical recipe) and `chat-shell.examples.html` (substrate demo)
+
+While rewriting patterns-forms.md form-container blocks:
+- Aligned with the substrate's actual form composition pattern (raw `<form>` + `<col-ui>` children + `<field-ui label>` wrapper). The Key Rules prose now correctly says "Use a raw `<form>`" instead of "Wrap fields in `<form-container-ui>`".
+
+While rewriting patterns-layout.md theme section:
+- Surfaced the actual `<theme-panel>` API (`parametric`, `presets`, `scheme-toggle` opt-ins) instead of inventing a fictional parametric `<theme-ui>` element
+- Documented the CSS-custom-property surface (`--a-density`, `--a-radius-k`, `--a-chroma`, etc.) which is the real parametric-tuning channel
+
+### Verify-target outputs at HEAD
+
+- check:skills:strict → 5/5 senior, 0 P-failures
+- run-skill-evals.mjs --strict → routing F1 90.9%, teach-routing 9/9, exit 0
+- audit-kit-recipes (default) → exit 0, 69 advisory findings
+- audit-kit-recipes --strict → exit 0 (NEW — was 1 at v3.4.0)
+- SKILL.md unchanged in size (version bump only)
+- Manifest entries: 80 (unchanged)
+
+### What's coming in v3.4.2 (preview)
+
+The 61 MEDIUM findings remain as the next worklist. They cluster around well-known prop drifts:
+- `<button-ui icon-leading>` → `<button-ui icon="X">` (~6 occurrences)
+- `<modal-ui show>` → `<modal-ui open>` (1)
+- `<drawer-ui show position>` → `<drawer-ui open side>` (1)
+- `<tab-ui name>` → `<tab-ui value>` (~5 occurrences)
+- `<tabs-ui active>` → `<tabs-ui value>` (1)
+- `<card-ui span>` doesn't exist; use parent `<col-ui cols=...>` grid sizing (~6 occurrences)
+- `<input-ui hint icon icon-leading>` → wrap in `<field-ui>` or use slot-based icons (~6 occurrences)
+- `<editor-sidebar collapsible>` → editor-sidebar has no `collapsible` opt-in (collapse is intrinsic) (~10 occurrences)
+- `<pane-ui size>` → use `minWidth/maxWidth` (~5 occurrences)
+- ...plus singletons (`<text-ui tracking>`, `<avatar-ui color>`, `<segmented-ui name>`, etc.)
+
+Triage register at `.brain/notes/2026-05-24-v3.4.0-kit-recipe-staleness-register.md` still drives the worklist; an updated v3.4.1+ register would replace the suggested-fix column with verify-and-commit status.
+
+---
+
+## 3.4.0 (2026-05-23)
+
+**MINOR** — Ships `scripts/audit-kit-recipes.mjs`, mechanizing the discovery of stale recipe markup in this skill's `references/*.md`. The user-flagged diagnosis ("a lot of the example code in the skill is potentially stale") gets a deterministic discovery instrument instead of relying on linear consumer-report → manual-audit → fix loops. Recipes are NOT fixed in v3.4.0 — only the audit instrument ships. The findings register is checked in to drive v3.4.1+ fixes.
+
+### Motivation — recipe staleness is the rate-limiter
+
+Three drift instances in close succession exposed the pattern:
+- v3.1.1 D1: editor-toolbar slot vocab (`icon|heading|description` instead of `title|status|action-leading`) — single-file fix in patterns-shells.md
+- v3.3.0 A1/A2/A3: admin-shell shape encoded pre-v0.4.0 (`<main>`/`<header-ui>`/`<section-ui>`) — rewrite across 2 files
+- FEEDBACK-56: setup.md Step 4 gate-bridge gap (consumer authored `slot="sidebar"` from memory) — 1-callout fix in setup.md (landed in v3.3.1)
+
+All three share a root cause: **the kit's own recipe markup encodes a stale-substrate vocabulary, and discovery only happens when a consumer hits the drift downstream.** Linear discovery (one report → one audit → one fix) is too slow against a substrate moving at ~MINOR/week. v3.4.0 inverts this with mechanical discovery.
+
+### What ships
+
+`.agents/skills/adia-ui-kit/scripts/audit-kit-recipes.mjs` (~700 lines):
+- Walks every triple-backtick `html` code block in `.agents/skills/adia-ui-kit/references/*.md`
+- Builds a substrate manifest by parsing 152 yaml files across `packages/web-components/components/` and `packages/web-modules/`
+- Augments the manifest with `<tag>.bespoke.css` selectors (light-DOM shell-tier per ADR-0033): both `tag > [slot="X"]` and `tag[slot="X"]` forms
+- Parses each HTML block with a minimal tag-event walker (no DOM lib)
+- Classifies findings:
+  - **CRITICAL** — unknown custom-element tag (e.g. legacy `<header-ui>` removed at v0.4.0; or fabricated `<router-ui>` that never existed)
+  - **MEDIUM** — unknown attribute on a known custom element (camelCase → kebab normalization handled)
+  - **INFO** — slot-on-child not declared in parent yaml (ADVISORY; yaml `slots:` block is non-authoritative for shell-tier)
+- Suppresses findings when surrounding prose contains anti-pattern markers (`ANTI-PATTERN`, `DO NOT`, `WRONG`, `pre-v0.`, etc.)
+- Modes: human report (default), `--json`, `--strict` (exit 1 on CRITICAL/HIGH), `--severity LEVEL,LEVEL` filter, `--root <substrate>` portable
+
+### Baseline at HEAD (v3.4.0)
+
+Run against `@adia-ai/web-modules@0.6.34` substrate:
+- **83 real findings** (15 CRITICAL, 0 HIGH, 62 MEDIUM, 0 LOW, 6 INFO)
+- **7 suppressed** in anti-pattern blocks (intentional WRONG examples — the kit's anti-pattern blocks are doing their job)
+
+CRITICAL findings (15 occurrences across 9 unique tag names):
+- `<form-container-ui>`, `<form-field>` — never existed in substrate; use raw `<form>` + `<field-ui>`
+- `<router-ui>` — never existed; routing is an app concern
+- `<gen-ui-chat>` — replace with `<a2ui-root>`
+- `<a2ui-playground>` — playground-only, not a substrate primitive
+- `<datetime-ui>` — replace with `<datetime-picker-ui>` (v0.6.34 new)
+- `<dialog-ui>` — replace with `<modal-ui>` or `<confirm-dialog-ui>` (v0.6.34 new)
+- `<theme-ui>` — replace with `<theme-panel>` (in popover)
+- `<breadcrumb-item-ui>` — replace with `<breadcrumb items=[...]>` data-driven
+
+MEDIUM findings (62 occurrences) cluster around well-known API drifts:
+- `<button-ui icon-leading>` → substrate has only `icon` (no leading variant)
+- `<modal-ui show>` / `<drawer-ui show>` → substrate uses `open`
+- `<tab-ui name>` → substrate uses `value`
+- `<card-ui span>` → no `span` prop; use parent grid sizing
+- `<input-ui hint>` / `<input-ui icon>` → not props on input-ui; wrap in `<field-ui>`
+- `<editor-sidebar collapsible>` → editor-sidebar has no opt-in collapsible (admin-sidebar does)
+- `<pane-ui size>` → use `minWidth/maxWidth`
+- ...and more — see register
+
+### Triage register
+
+`.brain/notes/2026-05-24-v3.4.0-kit-recipe-staleness-register.md` (11 KB, 356 lines) lists every finding with:
+- Severity + occurrence count
+- Suggested fix (where the canonical substrate replacement is known)
+- File:line locations (linkable in editors)
+- Verification contract: each fix MUST be grep-verified against substrate yaml before commit
+
+The register drives v3.4.1+ recipe-fix commits. Treat it as the v3.4.X arc worklist.
+
+### What v3.4.0 does NOT do
+
+- **Does NOT fix any recipes.** All 83 findings remain in the references/*.md files at HEAD. The audit is advisory at v3.4.0. The fix arc starts at v3.4.1.
+- **Does NOT wire the audit into a hard CI gate.** Strict mode is opt-in (`--strict`). v3.5.0 may promote to hard-fail after the v3.4.X arc has burned down CRITICAL to zero.
+- **Does NOT cover the kit's verification scripts themselves.** The script audits HTML blocks in `references/*.md` only. SKILL.md prose and the `.brain/notes/` lane are out of scope.
+
+### Refinement areas (v3.4.1+ if needed)
+
+The HIGH-severity slot-mismatch check was demoted to INFO in this ship. The yaml `slots:` block conflates "slots admin-shell directly accepts" (just `default`) with "vocab admin-shell descendants use" (`icon|heading|description|action|action-leading`). Refining the rule requires distinguishing positional CSS selectors per child-tag, which the current `*.bespoke.css` regex is too coarse for. Track this as a v3.4.X follow-up; do not promote INFO to HIGH until the rule is proven precise.
+
+### Regression footprint
+
+- check:skills:strict → 5/5 senior, 0 P-failures
+- run-skill-evals.mjs --strict → routing F1 90.9%, teach-routing 9/9, exit 0
+- SKILL.md verify-target row 1-4 grew (added the audit-kit-recipes.mjs line)
+- skill.json manifest: 79 → 80 entries
+- audit-kit-recipes.mjs new: 23 KB / 700 lines
+
+### Cross-references
+
+- FB-56 root cause (kit recipe staleness) — partially addressed in v3.3.1 via the setup.md bridge note; mechanized in v3.4.0
+- v3.1.2 audit-demo-slot-vs-css.mjs — sibling audit script, scans substrate `.examples.html` rather than kit `references/*.md`; complementary
+- `.brain/notes/2026-05-24-v3.4.0-kit-recipe-staleness-register.md` — the worklist for v3.4.1+
+
+---
+
+## 3.3.1 (2026-05-23)
+
+**PATCH** — Lands FB-56 (P3, kit's lane) — setup.md Step 4 bridge note routing shell-markup authoring to the pre-author bundle gate. Renumbers in-flight draft ticket from FB-55 → FB-57 (id collision with claims-ui-v10's FB-55 substrate ticket that landed in inbound during my v3.1.1 → v3.3.0 arc).
+
+### FB-56 — setup.md Step 4 pre-author bridge note
+
+The cold-start session for claims-ui-v10 (2026-05-23) hit 7 slot-vocab errors in `index.html` because §Setup Step 4 (the highest-traffic path in the skill) didn't bridge shell-markup authoring to the pre-author bundle gate. The pre-author gate is defined in §LoadingProtocol as a §Compose trigger — during §Setup, the agent's request is "install packages" / "create index.html", not "compose an admin-shell surface", so the gate doesn't fire. Agent authors slot vocabulary from memory → produces `slot="sidebar"` instead of `slot="leading"` → `AdminShell.#findSidebar()` silently returns nothing → sidebar toggle and resize permanently broken with no console output.
+
+Per FB-56's request:
+- `../setup.md` Step 4: added bridge callout at end of the `index.html` code block routing shell-app consumers to load `patterns-shells.md` BEFORE authoring shell markup
+- Quotes the canonical 7-error trace from FB-56 (`slot="sidebar"` → silent toggle break) as the load-bearing example
+- Points at yaml sidecars (`node_modules/@adia-ai/web-modules/shell/<name>/<name>.yaml`) as the authoritative slot/attribute source
+- Reference text: FB-56 was authored as a docs-only ~6-sentence ask; the landed callout is 9 sentences (added the silent-failure example explicitly, since that's the load-bearing reason the gate matters)
+
+### Draft renumber — FB-55 → FB-57
+
+My v3.1.1 ticket-draft `FB-editor-shell-demo-slot-vocab.md` used `id: "55"`. During my v3.1.1 → v3.3.0 arc, claims-ui-v10 filed real FB-55 (substrate silent toggle fail) and FB-56 (kit setup.md gate gap) which landed in `.agents/team/tickets/inbound/`. My draft's ID collided. Renumbered:
+- `id: "55"` → `id: "57"`
+- Filename: `FB-editor-shell-demo-slot-vocab.md` → `FEEDBACK-57--adia-ui--2026-05-23--editor-shell-demo-slot-vocab-drift.md` (matches conventional shape)
+- Frontmatter `version:` bumped `0.6.33` → `0.6.34`
+- Added cross-refs to FB-55 and FB-56 (same incident class, different surfaces)
+- Historical CHANGELOG entries referencing "FB-55" are append-only and not retouched (they describe what was true at the time of those releases)
+
+### What's coming in v3.4.0 (preview)
+
+The user's broader observation — "a lot of the example code in the skill is potentially stale" — motivates a follow-up MINOR. Three drift instances (v3.1.1 D1 editor-toolbar, v3.3.0 A1 admin-shell, FB-56 setup-step-4-bridge-gap) traced to the same root cause: **kit recipe markup encoded a stale-substrate vocabulary**. Linear discovery (one consumer report → one manual audit → one fix) is too slow. v3.4.0 will ship `scripts/audit-kit-recipes.mjs` — walks every HTML code block in `references/*.md`, validates tags + slots + props against substrate yaml SoT. Same pattern as v3.1.2's `audit-demo-slot-vs-css.mjs` but the scan target is the kit's own recipes instead of substrate `.examples.html` demos.
+
+### Regression footprint
+
+- check:skills:strict → 5/5 senior, 0 P-failures.
+- run-skill-evals.mjs --strict → routing F1 90.9%, teach-routing 9/9, exit 0.
+- Seed-size: SKILL.md unchanged (version bump only). setup.md +0.6 KB (bridge callout).
+- Manifest: 79 entries unchanged.
+
+### Cross-references
+
+- FB-56 (resolved by this commit): `.agents/team/tickets/inbound/FEEDBACK-56--adia-ui-skill--2026-05-23--setup-step4-missing-preauthor-gate-for-shell-markup.md`
+- FB-55 (substrate side, peer-agent lane — NOT this commit): `.agents/team/tickets/inbound/FEEDBACK-55--adia-ui--2026-05-23--admin-shell-silent-toggle-fail-unregistered-admin-sidebar.md`
+- FB-57 (my renumbered editor-shell demo drift draft): `.agents/team/tickets/drafts/FEEDBACK-57--adia-ui--2026-05-23--editor-shell-demo-slot-vocab-drift.md`
+
+---
+
+## 3.3.0 (2026-05-23)
+
+**MINOR** — Consumer-build-review driven canonical-anatomy rewrite. claims-ui-v* localhost:5173 build review surfaced 11 findings; deep audit traced two of them (broken admin-shell anatomy + zero responsive `@bp` usage) back to the kit's OWN recipes shipping pre-ADR-0023/pre-v0.4.0 shapes. Same drift class as v3.1.1's D1 finding on editor-shell: kit copied substrate's stale `.examples.html` demo (which carried the legacy shapes through v0.5.x) instead of the live canonical `chat-ui:site/index.html`.
+
+### A1 — `../patterns-shells.md` admin-shell recipe rewritten end-to-end
+
+The headline recipe (line 25, the first thing agents see when loading patterns-shells.md) showed `<main>` + `<header-ui>` + `<section-ui>` direct-children of `<admin-shell>` — the **pre-v0.4.0 legacy shape**. Per ADR-0024 these were retired five months ago. The substrate's `admin-shell.examples.html` demo still carries the legacy shape; the kit copied it.
+
+Rewrite extracted directly from `chat-ui:site/index.html` (the canonical):
+- Full 13-part canonical anatomy table — every tag with its role + attributes-that-matter column
+- Worked example with all 13 parts (left sidebar with its own topbar/section-ui/statusbar/data-resize; admin-content with topbar/scroll/page/statusbar; trailing sidebar; admin-command)
+- "Halfway-modernized" anti-pattern callout — the EXACT failure mode the claims-ui-v* consumer hit (visible parts adopted, invisible parts skipped, topbar placed at wrong level)
+- 7-row legacy→canonical migration table (`<main>` → `<admin-content>`, `<header-ui>` inside main → `<admin-topbar>` inside admin-content, `<section-ui>` as page body → `<admin-scroll>` > `<admin-page>` > `<admin-page-{header,body}>`, etc.)
+- New "Responsive — `@bp` annotations are mandatory" callout immediately under the recipe, with cross-link to `patterns-layout.md` §Responsive Layout (the kit's existing comprehensive `@bp` doc that consumers weren't finding from patterns-shells.md)
+- Explicit pointer to `chat-ui:site/index.html` as the SoT, with warning NOT to use `admin-shell.examples.html` (same drift trap as FB-55's editor-shell case)
+
+### A2 — `../patterns-shells.md` "Admin product page" composition recipe rewritten
+
+The composition recipe (line 763 in the "Composition recipes" section) showed `<header slot="header">` + `<nav-ui slot="leading">` + `<main>` as direct children of `<admin-shell>` — the **pre-v0.4.0 shape**. Rewritten to the canonical 13-part anatomy with the table-in-card embedded in `<admin-page-body>`.
+
+### A3 — `../patterns-recipes.md` Cold-Start app recipe — slot drift fix
+
+The Cold-Start app recipe (line 89) had `<admin-topbar slot="header">` inside `<admin-content>`. Per canonical, ONLY the sidebar's own admin-topbar uses `slot="header"`. The content-area admin-topbar carries NO slot attribute. Also missing: `<admin-statusbar>` at content-area bottom + `<div data-actions>` + theme-panel popover example. Fixed.
+
+### Why MINOR (not PATCH)
+
+Three precedents argue for MINOR:
+1. v2.28.0 (32-item v0.6.32 currency sweep) shipped as MINOR
+2. v3.1.1 D1 fix (slot-vocab drift) shipped as PATCH, but D1 was a single attribute name on one component — A1+A2+A3 here are STRUCTURAL rewrites of the kit's two highest-traffic admin-shell recipes
+3. The "halfway-modernized" anti-pattern + the new 13-part anatomy table + the legacy→canonical migration table together constitute new authoring contract surface
+
+### Cross-references
+
+- Consumer-build review (paste-ready for the consumer's agent): `/tmp/claims-ui-build-review-2026-05-23.md` (~9.8 KB)
+- Canonical anatomy SoT: `chat-ui:site/index.html` (NOT `admin-shell.examples.html`)
+- Related drift trap: `.agents/team/tickets/drafts/FB-editor-shell-demo-slot-vocab.md` (FB-55, same pattern, editor-shell side, peer-agent lane)
+- ADR-0023 (bespoke shell-tier children, shipped v0.3.6)
+- ADR-0024 (legacy shell shapes retired v0.4.0)
+
+### Regression footprint
+
+- check:skills:strict — 5/5 senior, 0 P-failures.
+- run-skill-evals.mjs --strict — routing F1 90.9% unchanged; teach-routing 9/9 (100%) unchanged.
+- audit-demo-slot-vs-css.mjs — 12 findings unchanged (substrate side hasn't moved on FB-55).
+- Seed-size: SKILL.md unchanged (only version bump). patterns-shells.md grew +6 KB (A1 +3.5 KB anatomy table + migration table; A2 +2.5 KB). patterns-recipes.md +0.6 KB (A3 statusbar + actions cluster).
+- Manifest: 79 entries unchanged.
+
+### v3.3.1+ candidate work (deferred)
+
+- **`audit-canonical-anatomy.mjs`** — a mechanical check that walks a consumer's DOM (or generated A2UI output) against the 13-part canonical admin-shell anatomy. Same pattern as v3.1.2's `audit-demo-slot-vs-css.mjs` — a static structural audit with HIGH/MEDIUM/LOW severity classes. Would have caught the consumer's drift mechanically. Worth building when a second consumer surfaces the same drift class.
+- **`audit-no-bp.mjs`** — sibling check for the responsive case: grep consumer HTML/JSX for `<grid-ui columns="N">` / `<row-ui gap="N">` without any `@` in the value. ZERO `@bp` usage in 59 layout primitives (claims-ui-v* baseline) suggests this is a widespread blind spot.
+
+---
+
+## 3.2.0 (2026-05-23)
+
+**MINOR** — v0.6.34 substrate-currency sweep. Audits the kit against the v0.6.33 → v0.6.34 substrate cut (released 2026-05-23) and lands the actionable items: V4 (tabs `[size]` behavior-change callout), V1+V2 (11 new substrate primitives — keyword index + brief descriptions), V3 (OD-5 `-default` token-shadowing theming recipe). 9 findings surfaced (V1-V9); 4 require kit action; 5 don't (already clean, not kit's lane, or substrate-only).
+
+### V4 (HIGH) — `<tabs-ui>` default size behavior change callout
+
+Substrate v0.6.34 retargeted `--tabs-button-height` from hardcoded `2.25rem` (36px, equivalent to `[size="lg"]`) to `var(--a-size)` — the universal `[size]` cascade. Default-rendered tabs visibly shrink from 36px → 30px.
+
+- `../composition.md` concept-index: added inline callout to both `<tabs-ui>` rows: *"v0.6.34+ default size is universal `--a-size` ≈ 30px — pre-v0.6.34 default was hardcoded 36px. Add `[size="lg"]` to restore the pre-v0.6.34 visual."*
+
+This is a behavior change consumers may not notice in source code — the markup is unchanged — but visually shrinks the tab strip. The callout lives in the concept-index where agents first look up `<tabs-ui>`.
+
+### V1+V2 (MEDIUM) — 11 new substrate primitives
+
+8 web-components + 3 web-modules added in v0.6.34 had ZERO kit references. Lightweight keyword-index entries added (NOT full recipes — recipes land as patterns emerge per the `teach-route` pattern):
+
+- `../composition.md`: new `### v0.6.34 new primitives` subsection with a single-row-per-primitive description table covering:
+  - `<calendar-grid-ui>` (substrate primitive — NOT user-facing date picker)
+  - `<combobox-ui>` (typeahead-filterable single-select; distinct-from-select callout)
+  - `<date-range-picker-ui>` (start+end + presets popover)
+  - `<datetime-picker-ui>` (date+time, never wraps native datetime-local per ADR-0025)
+  - `<integration-card-ui>` (single-tile third-party integration; status-driven button variant)
+  - `<list-window-ui>` (virtualized list; render-prop or slotted-template)
+  - `<spinner-ui>` (circular indeterminate; fills gap between skeleton + progress)
+  - `<time-picker-ui>` (WAI-ARIA Spinbutton segments)
+  - `<date-range-selector-ui>` (dashboard-tier preset-row + picker)
+  - `<confirm-dialog-ui>` (yes/no over modal; pre-stamped canonical shape)
+  - `<onboarding-checklist-ui>` (Stripe/Linear/Vercel "Getting started" pattern)
+
+Each entry names the substrate yaml's category, ground-truth description, and most-relevant decision-rule callout (e.g. combobox vs select). Closing pointer: `teach-route.mjs` for routing future recipe additions.
+
+### V3 (LOW) — OD-5 `-default` token-shadowing theming recipe
+
+OD-5 (substrate commit `e694be9d0`) added a `-default` partner to every component-leaf token. Pre-v0.6.34, leaf defaults shadowed consumer wrapper overrides; post-v0.6.34, the `var(--X, var(--X-default))` chain unlocks consumer override at any ancestor surface.
+
+- `../composition.md`: new `### Theming via component-leaf tokens (OD-5 -default suffix, v0.6.34+)` H3 section. Documents:
+  - Two-layer token model (global `--a-*` vs leaf `--<component>-*`)
+  - The before/after CSS pattern showing wrapper-scope overrides now working
+  - Naming convention: `--X` (instance override) vs `--X-default` (theme retarget)
+  - Decision guide: when each layer
+  - Note on global-token stability: `--a-*` surface unchanged across v0.6.34
+
+### What's NOT in this version (V5/V6/V7/V8/V9 — no kit action needed)
+
+- **V5** — a2ui-runtime CSS channel Phase 1 (a2ui-pipeline territory, not kit)
+- **V6** — `@0.6` floating-minor already covers v0.6.34; setup.md no-op
+- **V7** — `<text-ui>` variants `subheading|h1-h6` removed from substrate; composition.md's text-ui variant enumeration was already consistent (kit didn't reference the removed variants)
+- **V8** — 18 components got missing `text-align: start` reset (substrate-internal fix, not contract change)
+- **V9** — `<mark>` background ref typo fixed (substrate-internal)
+
+### Regression footprint
+
+- check:skills:strict — 5/5 senior, 0 P-failures.
+- run-skill-evals.mjs --strict — routing F1 90.9% unchanged; teach-routing 9/9 (100%) unchanged.
+- audit-demo-slot-vs-css.mjs — 12 findings unchanged (substrate side hasn't moved on FB-55 yet).
+- Seed-size: SKILL.md unchanged (only version bump). composition.md grew ~5 KB.
+- Manifest: 79 entries unchanged (no new files).
+
+### Why MINOR (not PATCH)
+
+Substrate-currency sweeps consistently shipped as MINOR (precedent: v2.28.0 32-item v0.6.32 currency sweep). The 11 new-primitive descriptions are NEW content (not corrective); the OD-5 theming subsection is a new authoring contract surface. MINOR is correct.
+
+### Cross-references
+
+- Substrate release: chat-ui `4263cdb66` (v0.6.34 lockstep)
+- OD-5 commit: `e694be9d0` (substrate sweep) + `cbdf11f09` (button-ui single-component fix)
+- Tabs size change: `2d931b980` (introduced) + `check:size-wiring` audit (the gate)
+- Wave 1+2 components: 10 P1 specs in `.claude/docs/specs/implementation-completed/`
+
+---
+
+## 3.1.3 (2026-05-23)
+
+**PATCH** — Editor-shell audit closeout: ships D4 (editor-canvas public API wiring recipe — focus-mode keyboard, zoom controller, `.resetView()`) + D6 (`[empty]` auto-management clarification + anti-patterns). The audit arc from v3.1.1 is now complete; all 6 D-items resolved (D1-D5 in v3.1.1/v3.1.2; D4+D6 in v3.1.3).
+
+### D4 — editor-canvas public API wiring recipe
+
+New "Editor canvas API + state" H2 section in `../patterns-shells.md` between "Editor-inside-admin" and "Chat shell". Three subsections:
+
+- **Focus-mode keyboard shortcut** — host wires the chord (Cmd+. / Ctrl+. by convention), calls `editorShell.toggleFocusMode()`, then listens for `editor-mode-change` events for any host-side propagation. Documents the substrate's automatic cascade: shell → toolbar `[full-screen]` + canvas `[focused]` + `.focus()` call + `editor-mode-change` event. Hard-rule callout: don't toggle the propagated attributes manually — they're shell-managed.
+- **Zoom controller** — `.zoom` getter/setter writes `--editor-canvas-zoom` CSS custom property; host content reads via `transform: scale(var(--editor-canvas-zoom, 1))`. Worked example with 7 zoom-step preset array + toolbar `[data-toolbar-action="zoom-in/out/reset"]` button wiring + Cmd+= / Cmd+- / Cmd+0 keyboard shortcuts. Public API surface table documents `.zoom`, `.resetView()`, `.focus()`, `.blur()`, plus reflected attributes `[empty]` and `[focused]` with "auto-managed; don't toggle" callouts.
+
+### D6 — `[empty]` is auto-managed (don't toggle it yourself)
+
+Subsection of the D4 H2 because the topics are tightly coupled. The substrate uses a MutationObserver on `childList` to auto-flip `[empty]` based on whether any non-`<editor-canvas-empty>` children exist. Documents:
+
+- The right way to "show content" (append a content child; `[empty]` auto-flips false)
+- The right way to "clear content" (`canvas.querySelectorAll(':scope > :not(editor-canvas-empty)').forEach(el => el.remove())`)
+- Four anti-patterns (manual `toggleAttribute`, `canvas.empty = X`, wrapping content in `<editor-canvas-empty>`, manual `[hidden]` toggle)
+- A distinct loading-state pattern for editors with async content (separate `[data-loading]` sibling node)
+- Implication for async content loading: the empty state shows for free during fetch, hides once first content child mounts
+
+### Editor-shell audit arc — closed
+
+The 6-finding editor-shell audit from v3.1.1 is now fully landed:
+
+| Finding | Severity | Disposition | Version |
+|---|---|---|---|
+| D1 | HIGH | Slot-vocab drift fix (kit + ticket-draft for substrate) | v3.1.1 |
+| D2 | HIGH | Substrate-side ticket-draft FB-55 | v3.1.1 |
+| D3 | MEDIUM | Standalone pane-ui split-pane recipe | v3.1.1 |
+| D5 | MEDIUM | Editor-inside-admin nested-shell recipe | v3.1.1 |
+| (mechanization) | — | audit-demo-slot-vs-css.mjs | v3.1.2 |
+| D4 | MEDIUM | editor-canvas API recipe (focus-mode + zoom) | v3.1.3 |
+| D6 | LOW | `[empty]` auto-management clarification | v3.1.3 |
+
+### Regression footprint
+
+- check:skills:strict — 5/5 senior, 0 P-failures.
+- run-skill-evals.mjs --strict — routing F1 90.9% unchanged; teach-routing 9/9 (100%) unchanged.
+- audit-demo-slot-vs-css.mjs — 12 baseline findings unchanged (6 HIGH + 6 LOW; the substrate side hasn't moved yet).
+- SKILL.md size unchanged (only version bumped); patterns-shells.md grew by ~9 KB for the new section + worked examples.
+- Manifest unchanged at 79 entries (no new files; all content went into existing patterns-shells.md).
+
+### Why PATCH (not MINOR)
+
+Same precedent as v3.1.1 (D3+D5 recipe additions shipped as PATCH): recipe additions that surface substrate capabilities the kit hadn't documented are corrective — the kit catching up to substrate truth — not new capability. MINOR is reserved for new authoring contracts, new scripts, new evals, or new senior-skill features. D4+D6 are documentation depth.
+
+### Cross-references
+
+- D-item taxonomy: see v3.1.1 entry above and `.claude/docs/REFACTOR-PROGRESS.md` Post-Phase-4 hygiene block
+- Substrate API source: `packages/web-modules/editor/editor-canvas/editor-canvas.js`
+- Substrate focus-mode source: `packages/web-modules/editor/editor-shell/editor-shell.js`
+
+---
+
+## 3.1.2 (2026-05-23)
+
+**MINOR** — Mechanizes the v3.1.1 lesson learned. Ships `scripts/audit-demo-slot-vs-css.mjs` — a portable, severity-classifying static analyzer that catches slot-vocabulary drift between demo HTML and bespoke CSS source-of-truth. Independent re-detects the D1/FB-55 finding plus 6 additional yaml-vs-CSS drift findings on `editor-statusbar`. New verify-target wired into Mode 1-4.
+
+### NEW — scripts/audit-demo-slot-vs-css.mjs
+
+The v3.1.1 retro flagged a discipline gap: the kit had been absorbing substrate demos as canonical, but demos can drift from their own CSS contract. The v3.1.1 fix corrected the symptom (the D1 slot vocab); v3.1.2 prevents recurrence (a mechanical check).
+
+**Algorithm:**
+1. Extract slot-positioning CSS rules of form `<host> > [slot="X"]` from all `*.bespoke.css` files under `packages/`.
+2. Walk every `*.examples.html` demo, parsing both live markup and embedded `<code-ui>` blocks (entity-decoded).
+3. For each direct child of a host that carries `slot="X"`, classify if `X` is in the CSS-positioned set.
+4. Misses get a severity classification:
+   - **HIGH** — slot name belongs to a sibling cluster's vocabulary (e.g. `slot="icon|heading|description"` on `<editor-toolbar>` matches `<admin-topbar>`'s vocab — the agent will look up the wrong rules)
+   - **MEDIUM** — slot name unknown to host yaml AND unknown to siblings (typo / experimental shape)
+   - **LOW** — slot name IS in host's yaml-declared slots but CSS doesn't position it (yaml-vs-CSS contract drift; renders sanely but signals one side stale)
+
+**CLI:**
+```bash
+node audit-demo-slot-vs-css.mjs                  # default: --root=. advisory (exit 0 on findings)
+node audit-demo-slot-vs-css.mjs --root=<path>    # portable to consumer / fixture repos
+node audit-demo-slot-vs-css.mjs --strict         # exit 1 on HIGH (default strict gate)
+node audit-demo-slot-vs-css.mjs --strict --include-medium  # also fail on MEDIUM
+node audit-demo-slot-vs-css.mjs --strict --include-low     # all findings block
+node audit-demo-slot-vs-css.mjs --json           # machine-readable output
+```
+
+**Baseline against current chat-ui substrate (v0.6.33):** 12 findings — 6 HIGH (the D1/FB-55 drift in `packages/web-modules/editor/editor-shell/editor-shell.examples.html` + the legacy `packages/web-components/patterns/editor-shell/` copy) + 6 LOW (yaml declares `editor-statusbar > slot="status"` but CSS doesn't position it — visible in 6 demo files). 0 MEDIUM. Independent re-detection of D1/FB-55 validates the script as a guardrail.
+
+### Verify-target wired into Mode 1-4
+
+- SKILL.md Mode 1-4 row: added `audit-demo-slot-vs-css.mjs` after `audit-shell-composition.mjs`. Advisory by default; `--strict` exits 1 on HIGH; portable via `--root=<substrate>`.
+
+### Why MINOR (not PATCH)
+
+Per VersionBump policy: new capability shipped (a new audit tool with its own behavior + a new verify-target wiring). PATCH would be wrong here — this isn't a corrective edit to an existing recipe; it's an extension of the kit's mechanical-check toolkit. Same precedent as v2.30.0 (`audit-shell-composition.mjs` shipped as MINOR).
+
+### Regression footprint
+
+- check:skills:strict — 5/5 senior, 0 P-failures.
+- run-skill-evals.mjs --strict — routing F1 90.9% unchanged; teach-routing 9/9 (100%) unchanged.
+- Seed-size: SKILL.md grew by ~250 bytes from the new verify-target row. 45.9 KB → ~46.2 KB. Still in warn band (<50 KB fail).
+- Manifest: 78 → 79 entries (1 new script).
+
+### Cross-references
+
+- The v3.1.1 reflection that motivated this: `.claude/docs/REFACTOR-PROGRESS.md` Post-Phase-4 hygiene block.
+- The originating drift: `.agents/team/tickets/drafts/FB-editor-shell-demo-slot-vocab.md` (FB-55).
+- CSS source of truth: `packages/web-modules/{chat,editor,shell}/.../css/*.bespoke.css`.
+
+### v3.1.3+ candidate work (deferred)
+
+- **D4** — editor-canvas public API wiring recipe (focus-mode keyboard + zoom controller). Still deferred.
+- **D6** — `[empty]` toggle pattern for editor-canvas-empty. Still deferred.
+- **Substrate-side action on the 6 LOW findings** — peer-agent territory: either add `editor-statusbar > [slot="status"]` CSS rules, or drop `status` from the yaml-declared slots. Not the kit's call.
+- **Substrate-side action on the 6 HIGH findings** — already filed as FB-55 in v3.1.1; substrate-author lane owns.
+
+---
+
+## 3.1.1 (2026-05-23)
+
+**PATCH** — Editor-shell audit: fix slot-vocabulary drift (D1) + add complementary recipes (D3 standalone pane-ui + D5 nested editor-inside-admin) discovered during depth-pass post-v3.1.0. The drift fix is corrective (kit catching up to substrate truth); the recipe additions surface substrate capabilities the kit hadn't documented.
+
+### D1 — editor-toolbar slot vocabulary corrected
+
+- `../patterns-shells.md`: editor-shell recipe rewritten — `slot="icon|heading|description"` → `slot="action-leading|title|status"` to match the substrate CSS source of truth (`packages/web-modules/editor/editor-shell/css/editor-shell.bespoke.css`). Added a "Slot vocabulary (substrate-grounded)" table documenting which slot names are positioned on each editor cluster member (`editor-toolbar`, `editor-canvas-toolbar`, `editor-statusbar`, `editor-sidebar`). Added an explicit "Common drift trap" callout pointing at the substrate-side ticket-draft.
+- `../flows-shells.md`: identical fix applied to the editor-shell composition example + the nested-shell mini-example. Updated the "Editor cluster wiring contract" bullet to reverse a previously-inverted claim (kit said `title` was retired and `heading` was current; substrate truth is the opposite — `title` is the canonical name and `heading` was never positioned by the editor cluster's CSS).
+
+### D2 — Substrate-side ticket-draft authored
+
+- `.agents/team/tickets/drafts/FB-editor-shell-demo-slot-vocab.md` (NEW, ~8.4 KB) — paste-ready feedback ticket for the peer/substrate-author lane. The substrate's own `editor-shell.examples.html` demo carries the same `icon|heading|description` drift through v0.6.33 (last touched in v0.6.32 status-sweep commit `5d8c62a80`); the kit drift originated from following that demo. Substrate-side fix is a 6-line slot rename; ticket includes diff, reproduction steps, suspected root cause, risk profile.
+
+### D3 — Standalone pane-ui (split-pane layout) recipe added
+
+- `../patterns-shells.md`: NEW "Standalone pane-ui (split-pane layout without a shell)" section between editor-shell and chat-shell. Documents the substrate-supported use case (advertised in `pane.yaml` SoT but missing from kit) where two `<pane-ui side="leading|trailing">` siblings in a flex row produce a shared resize seam — markdown-editor + preview, settings + detail, JSON + rendered output. Includes the full pane-ui contract table (props/events/inner-shape), three "when NOT to use" callouts, and the two-pane anti-patterns (no third sibling; no hand-rolled grabber).
+
+### D5 — Editor-inside-admin (nested-shell composition) recipe added
+
+- `../patterns-shells.md`: NEW "Editor-inside-admin (nested-shell composition)" section, converting the previous anti-pattern blurb into a positive recipe. Shows the canonical inline-page-builder shape with the four-property `flex: 1; min-height: 0` flex-chain rule made explicit (admin-page-body + editor-shell each need both properties; admin-page-body also needs `display: flex; flex-direction: column`). Includes the `persist=` namespacing pattern to avoid localStorage collisions with the outer admin shell.
+
+### What's NOT in v3.1.1 (deferred)
+
+- **D4** — editor-canvas public API wiring recipe (focus-mode keyboard shortcut + zoom controller integration). Mentioned in the contract but no worked example.
+- **D6** — `[empty]` toggle pattern for editor-canvas-empty visibility. CSS-only mechanism mentioned in the contract but no worked example.
+
+Both deferred items are depth-additions, not bug-fixes. They may land in v3.1.2 or v3.2.0 depending on demand.
+
+### Regression footprint
+
+- Routing F1 90.9% (unchanged; description didn't change).
+- Teach-routing 9/9 (100%; unchanged).
+- check:skills:strict — 5/5 senior, 0 P-failures.
+- Seed-size unchanged (SKILL.md not touched — all edits in references/).
+- Reference-file growth: patterns-shells.md +~ 6 KB (D3+D5 recipes); flows-shells.md ~unchanged (D1 substitutions, no net growth).
+
+### Cross-references
+
+- Substrate-side ticket: `.agents/team/tickets/drafts/FB-editor-shell-demo-slot-vocab.md` (FB-55)
+- CSS source of truth: `packages/web-modules/editor/editor-shell/css/editor-shell.bespoke.css`
+- Yaml SoT: `packages/web-modules/editor/{editor-shell,editor-toolbar,editor-canvas,editor-canvas-toolbar,editor-canvas-empty,editor-sidebar,editor-statusbar}.yaml`
+- pane-ui SoT: `packages/web-components/components/pane/pane.yaml`
+
+---
+
+## 3.1.0 (2026-05-23)
+
+**MINOR** — Phase 4 (final) of the REFACTOR-SPEC refactor (v2.28.0 → v3.0.0 → v3.1.0). **Mechanizes the §Teach decision tree (P4) + ships the session-log + DecisionModel audit substrate (P5).** Authoring-contract additions are advisory-only in v3.1.0; v3.2.0 may promote DecisionModel orphan-component audit to hard-fail after ≥3 weeks of advisory-mode traces.
+
+### P4 — §Teach decision tree mechanized
+
+- **NEW** `scripts/teach-route.mjs` — deterministic 7-branch (A-G) classifier for knowledge-payload routing. Returns landing target + confidence level. CLI supports `--payload="<text>"`, stdin pipe, `--eval=<corpus>`, `--strict`, `--json`. Per REFACTOR-SPEC P4.
+- **NEW** `../../evals/teach-routing-cases.json` — 9-case behavioral corpus covering all 7 branches (A: 2, B: 2, C/D/E/F/G: 1 each). Baseline: 9/9 (100%) pass at high confidence (8) + medium (1).
+- **UPDATED** `../teach-protocol.md` — decision-tree section now lead-paragraph documents the mechanization + prose tree retained for human review; ambiguity-resolution rule (script wins; update both prose + corpus when they disagree).
+- **UPDATED** `scripts/run-skill-evals.mjs` v1.0.0 → v1.1.0 — added Eval 4 (teach-routing) wired into both human + JSON report; `--strict` mode hard-fails at <100% teach-routing pass rate.
+
+### P5(a) — Session-log emission contract
+
+- **NEW** `../session-log-schema.md` — JSONL append-only session log; 8 event types (`skill_loaded`, `mode_entered`, `decision_made`, `component_named`, `verify_target_run`, `correction_applied`, `teach_landing`, `session_closed`); per-session file at `.agents/team/session-logs/YYYY-MM-DD/<session-id>.jsonl`.
+- **NEW** `scripts/validate-session-log.mjs` — JSONL schema validator. Errors on missing required fields, unknown event_type, invalid ISO 8601 timestamp, branch-out-of-range. Warnings on >500 char summary, single-action "decisions". Exit 1 on errors; `--strict` also fails on warnings.
+
+### P5(b) — DecisionModel orphan-component audit (ADVISORY)
+
+- **NEW** `../decision-model.md` — `decisions: [{decision, requiredSignal, possibleActions, chosenAction, rationale}]` contract. Worked login-page example. Allowlist-via-rationale escape hatch.
+- **NEW** `scripts/audit-decision-trace.mjs` — walks a JSONL session log + flags orphan-component findings (components named without a tracking `decision_made` event). **ADVISORY in v3.1.0** (`--advisory` default; exits 0 even on findings; collecting baseline). `--strict` exits 1 on findings. `--allowlist=<path>` supports per-project escape-hatch list. v3.2.0+ may promote `--strict` to required after ≥3 weeks of clean advisory traces.
+
+### SKILL.md changes
+
+- **§Teach stub** — added v3.1.0 mechanized callout pointing at `scripts/teach-route.mjs`.
+- **§SessionLog (NEW stub)** — points at `../session-log-schema.md`; documents `validate-session-log.mjs` + `audit-decision-trace.mjs` + the advisory-vs-strict rollout.
+- **No H2 reordering** — §Teach + §SessionLog land immediately after §FeedbackDiscipline (cold-start band unchanged; §PEV still at L82).
+
+### Counter-proposals landed
+
+- **Phase 4 split** (mine, 2026-05-22): P5 split into P5(a) session-log (low-risk) + P5(b) DecisionModel (advisory). Both ship in v3.1.0; only P5(b) is on a probationary rollout path.
+- **OQ4 decision** (spec §10): NO deprecation of substrate-only verify paths in v3.0.0 cut. The bundled-paths-supplement substrate-paths rule documented at v2.30.0 stands; v3.0.0 didn't change that.
+
+### Regression footprint
+
+- Routing F1 90.9% (TP=10 FP=2 FN=0 TN=3) — unchanged from v3.0.0 (Phase 3 didn't touch description; Phase 4 doesn't either).
+- Teach-routing 9/9 (100%) — new baseline.
+- check:skills:strict — 5/5 senior, 0 P-failures.
+- Seed size 44.4KB → 45.9KB (still warn-band; under 50KB fail). 1.5KB growth from §Teach v3.1.0 callout + §SessionLog stub addition is acceptable; future hygiene pass can chip.
+
+### Migration
+
+No user-facing breaking changes. Existing v3.0.0 consumers continue working. To opt into v3.1.0 features:
+1. **§Teach mechanization** — replace prose decision-tree calls with `node node_modules/adia-ui-kit/scripts/teach-route.mjs --payload="<text>"`.
+2. **Session-log emission** — author your own emit-on-event hook; validate periodically with `node node_modules/adia-ui-kit/scripts/validate-session-log.mjs <path>`.
+3. **DecisionModel** — opt-in only; emit `decision_made` events before component output, then run `node node_modules/adia-ui-kit/scripts/audit-decision-trace.mjs <log>` (advisory by default).
+
+---
+
+## 3.0.0 (2026-05-23)
+
+**MAJOR** — Phase 3 of the REFACTOR-SPEC refactor (v2.28.0 → v3.0.0). **Closes C1 (the 256KB tool-read limit bite) by extracting 27 H2 sections from SKILL.md into 27 new `references/*.md` files. SKILL.md shrinks from 258.6KB → 44.4KB (83% reduction), under the new 50KB hard-fail gate.** Plus P0 (seed-size CI gate) + P6 (capability-menu trim).
+
+### Why MAJOR (not MINOR)
+
+The §LoadingProtocol architecture is preserved (this is what the spec called out as still-correct), but the seed shape changes substantially:
+
+- Cold-start contract: ~258KB seed (single-tool-read fails) → ~44KB seed (fits in one tool-read with 200KB+ headroom)
+- 27 new reference files; older procedural content moves OUT of seed and INTO references
+- The §LoadingProtocol manifest changes (references now declare `load-when:` frontmatter)
+- The check-skills gate chain adds a new mechanical enforcement (`check:skills:seed-size`)
+
+Per kit's §VersionBump policy: MAJOR = breaking structural change to the seed shape. Consumer agents that memorized procedural detail at specific seed line numbers (rare but possible) will need to follow the H2 → reference-file pointer. Backward compatibility is preserved at the H2 level: every H2 still exists at the same name; bodies are stubs pointing at references.
+
+### What landed — P0 (seed-size CI gate)
+
+- **`scripts/skills/check-skills-seed-size.mjs`** (NEW) — substrate-level gate that fails CI if any senior SKILL.md exceeds 50KB (hard fail) or warns above 40KB (soft suggestion). Default thresholds match the 256KB tool-read limit's safe operating zone. Per-skill override via `.skill-policy.json` requires a `seed_size_waiver_reason` text for caps above 50KB. Surfaces both bytes (hard gate) and tokens (informational — ~3.5 bytes/token approximation; for exact counts, use `audit-skill-hygiene.mjs`). Per Phase 1 counter-proposal: bytes is the hard gate (matches tool-read mechanical limit); tokens is informational (matches cost-per-load story).
+- **`package.json`** — added `check-skills-seed-size.mjs` to both `check:skills` (warn mode) and `check:skills:strict` (hard-fail mode).
+
+### What landed — §6.1 §LoadingProtocol extraction
+
+- **`../loading-protocol.md`** (NEW, ~25KB) — full pre-author bundle gate trigger list, reference manifest, harness manifest, on-demand bundle rules.
+- SKILL.md §LoadingProtocol stub trimmed to ~15 lines: 3-line load rule + pre-author gate ⚠️ callout pointing at the reference.
+
+### What landed — §6.2 §CorrectionLoop extraction
+
+- **`../correction-loop.md`** (NEW, ~23KB) — 4-layer triage tree, 5 sniff tests for root cause, 7 worked examples, compound-fix anti-patterns.
+- SKILL.md §CorrectionLoop stub trimmed to ~5 lines: posture statement + reference pointer.
+
+### What landed — §6.3 §Mission condensation
+
+- **`../mission.md`** (NEW, ~11KB) — full 5-step consultant inventory, consultant-vs-author posture matrix, §Recon trigger list, worked examples.
+- SKILL.md §Mission stub trimmed to ~20 lines preserving: posture statement, consultant-vs-author distinction, when-to-be-consultant + when-to-be-author triage, §ContentTrust rule (preserved inline in the seed; data-not-instructions is a hard rule the agent must always have at cold-start).
+
+### What landed — §6.x §CSSPolicy extraction
+
+- **`../css-policy.md`** (NEW, ~16KB) — full policy rationale, CDN-bundle correctness milestone callouts, reserved layout-helper attribute names, "what this policy does NOT mean" carve-outs.
+- SKILL.md §CSSPolicy stub trimmed to ~12 lines: 3-path summary table + "pick ONE JS bundle path" rule + reference pointer.
+
+### What landed — §6.x "§Docs" + "§GapDetection" extraction
+
+- **`../docs-catalog.md`** (NEW, ~11.5KB) — full ui-kit.exe.xyz docs URLs, per-mode "which doc to read" mapping, ADR pointers, MIGRATION GUIDE path.
+- **`../gap-detection.md`** (NEW, ~11KB) — full 4-class gap detection (version drift, capability drift, spec drift, doc currency) + detection recipes + remediation patterns + ranking-by-leverage.
+- Both H2 stubs trimmed to ~10 lines each.
+
+### What landed — P6 capability-menu trim
+
+- **`../capabilities.md`** (NEW, ~14KB) — full 14-mode menu + per-mode triage table + "pick your entry point" rows.
+- **`../mode-routing.md`** (NEW, ~15KB) — full mode-routing usage detail, prompt-shape interpretation, mode-routing examples, cold-start checkpoint mechanics.
+- SKILL.md "What this skill can do" trimmed to 4-mode summary + reference pointer.
+- SKILL.md "How to use this skill" trimmed to 2-step orientation + reference pointer.
+
+### What landed — Wave 2 (10 more extractions, ~69KB saved)
+
+10 additional H2 sections extracted: `harness.md` (§Harness wiring), `exclusions.md` (Items deliberately NOT included), `catalog-lookup.md` (§1 Catalog Lookup), `composition.md` (§2 Composition), `recon.md` (§Recon 60-second inventory), `skill-hygiene.md` (§SkillHygiene 8 axes), `state.md` (§State controllers/signals), `reasoning-gate.md` (§0 Reasoning Gate), `migration.md` (§Migration). §FeedbackDiscipline kept inline-stub (existing `feedback-authoring.md` is the canonical procedure).
+
+### What landed — Wave 3 (9 final extractions, ~32KB saved)
+
+9 more: `reasoning-methodologies.md` (§ReasoningMethodologies general-purpose priors), `autocapture.md` (§AutoCapture opportunistic drafting), `ticket-tooling.md` (§TicketTooling `ticket-tool.py` reference), `theme.md` (§Theme color/density), `team-tickets.md` (§Team Tickets 4-stage pipeline), `session-log-template.md` (the YYYY-MM-DD HH:MM template block), `version-check.md` (§VersionCheck lockstep sanity), `diagnostic-output.md` (§7 overall posture assessment), `teach-protocol.md` (§Teach decision tree — kept existing reference file; replaced seed-resident copy).
+
+### Verify-target (Phase 3)
+
+- `check:skills:strict` — 5/5 senior skills passing all 5 binding-points (HarnessIntegration + Plan-Execute-Verify), 0 P-failures.
+- `check:skills:seed-size` — adia-ui-kit at 44.4KB ⚠ warn (below 50KB fail; above 40KB warn). Sibling seniors all in green at 23-27KB.
+- SKILL.md §PEV at L82 — well inside cold-start band (≤L250). Was at L249 pre-extraction.
+- `check:skills` link-check — all link-checked files clean.
+- `skill.json` validates as JSON; manifest length 72 = on-disk file count 72.
+- Routing-eval — kit still routes (98.3% accuracy at v2.30.0; will re-baseline post-extraction in v3.0.1 if needed; trigger block unchanged).
+- Net byte reduction: **258.6KB → 44.4KB (83% reduction, 219KB saved across 27 reference extractions)**.
+
+### Pitfalls caught + fixed during execution
+
+- **Pitfall 1**: §Teach extraction broke check-pev P3 (no §PEV cross-reference left in §Teach stub). Fixed by adding "Every §Teach landing inherits the §PEV loop" callout to the stub.
+- **Pitfall 2**: §Teach extraction also broke check-extensibility P4 (no `VISION-extensibility.md` reference in SKILL.md). Fixed by adding the extensibility-pattern cross-ref to the §Teach stub.
+- **Mitigation**: any future extraction that touches §Teach should preserve both the §PEV mention AND the VISION-extensibility.md mention. The gate scripts catch the regression; trust the scripts.
+
+### What did NOT land (deferred to Phase 4)
+
+- ❌ **§Teach decision tree mechanization** (P4) — Phase 4.
+- ❌ **Post-deploy session log / DecisionModel checkpoint** (P5) — Phase 4.
+- ❌ **Further trim to <40KB warn floor** — not strictly required; the gate is in warn band, not fail. Future hygiene pass can chip if convenient.
+
+### Phase 1 counter-proposal landed in Phase 3 (P0 bytes vs tokens)
+
+Phase 1's counter-proposal called for surfacing both bytes (hard gate) and tokens (informational) for the seed-size check. Landed in `check-skills-seed-size.mjs:42` — output reports both. Bytes drives the gate (matches the 256KB tool-read mechanical constraint); tokens reported as informational (matches cost-per-load story). OQ1 resolved per spec recommendation.
+
+---