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

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

@@ -8,7 +8,7 @@
 
 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.
 
-- **`references/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).
+- **`../../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.
 
@@ -35,7 +35,7 @@ The v3.9.0 `tokens.md` showed `<button-ui style="--button-bg: var(--a-primary)">
 - **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.
-- **`references/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.
+- **`../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).
 
@@ -44,35 +44,35 @@ The v3.9.0 `tokens.md` showed `<button-ui style="--button-bg: var(--a-primary)">
 **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.
-- **`references/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*).
+- **`../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.
 
-- **`references/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.
+- **`../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.
-- **`references/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 `references/figma-make.md` to the `files` array.
+- **`../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). `references/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`). `references/patterns-data.md` only.
+- **§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`). `references/setup.md` only.
-- **`admin-page-header` action-cluster examples corrected to `<div data-actions>`** (FB-84). `references/patterns-recipes.md` (Route-fragment example + authoring bullet) and `references/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).
+- **§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. `references/setup.md` only.
+**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)
 
@@ -104,8 +104,8 @@ The v3.9.0 `tokens.md` showed `<button-ui style="--button-bg: var(--a-primary)">
 
 ### What v3.7.10 absorbs (skill files)
 
-- `references/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).
-- `references/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.
+- `../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)
 
@@ -176,8 +176,8 @@ The cycle-17 review surfaced eight demos (`invite-members`, `contact-form`, `bil
 
 ### Files
 
-- `references/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
-- `references/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
+- `../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)
 
@@ -230,9 +230,9 @@ These four findings ALL share the v3.7.4-v3.7.7 family root cause: **the load-be
 ### 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)
-- `references/patterns-recipes.md` — Route setup gains router-provider callout; route-fragment template gains inner `<section>` wrapper + FB-69 cross-reference callout
-- `references/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
-- `references/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
+- `../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)
 
@@ -298,8 +298,8 @@ The meta-rule from v3.7.7 ("markup teaches structure; prose teaches the contract
 
 ### Files
 
-- `references/patterns-shells.md` — `[data-actions]` Key affordance bullet expanded
-- `references/patterns-layout.md` — Grid section gets gap-numeric-token callout
+- `../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)
 
@@ -375,7 +375,7 @@ A ⚠️ anti-pattern callout below the table names the specific failure mode: p
 
 ### Files
 
-- `references/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
+- `../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)
 
@@ -427,19 +427,19 @@ claims-ui-v11 adopted v3.7.4's Pattern A verbatim. First-paint visual review cau
 
 ### What landed in kit v3.7.5
 
-**`references/patterns-shells.md` §Brand chrome H3 (lines 208-262) rewritten:**
+**`../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)
 
-**`references/patterns-recipes.md:345-385` rewritten:**
+**`../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
 
-**`references/common-gotchas-consumer.md`:**
+**`../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"
@@ -517,9 +517,9 @@ The 13-part anatomy single-sources from chat-ui's multi-product workspace (`<sel
 
 ### Files touched
 
-- `references/patterns-shells.md` — canonical fixes + §Wrapper-vs-column callout + §Brand chrome H3 + §Routing inside admin-shell H3 + §Composition recipes Admin product page fix
-- `references/patterns-recipes.md` — extended §Entity list → detail drawer pattern + §Button density by surface table
-- `references/common-gotchas-consumer.md` — new §5 gotcha + audit-coverage row now pointing at the new gate (no longer "None; visual review only")
+- `../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)
 
@@ -561,7 +561,7 @@ Pattern-coverage extensions (4 new H3 sections + 1 callout + 1 gotcha + 1 table)
 
 ### Discovery wiring
 
-v3.7.2 (peer commit `0d1708994`) shipped `references/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.
+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):
 
@@ -610,11 +610,11 @@ No new capability, no new modes, no new artifacts. Pure discovery + version-drif
 
 ### Sister-skill source
 
-`adia-ui-authoring` v1.8.2 commit `62f57f973` shipped `references/common-gotchas.md` 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.
+`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
 
-**`references/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:
+**`../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])`.
@@ -668,7 +668,7 @@ This is the same risk class kit faces. Kit's `audit-kit-recipes`, `audit-native-
 
 ### What landed in kit v3.7.1
 
-**`references/component-literacy.md` §NAILED contract extension:**
+**`../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).
@@ -732,7 +732,7 @@ The kit's central Goodhart-risk closed: kit §PEV Mode 1-4 verify-target ("rende
 - 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 — `references/component-literacy.md` (~16KB)
+### 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:
 
@@ -743,7 +743,7 @@ The kit's analog of authoring's §Phase 2.5a Pre-flight Component Literacy. Fire
 - **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 `references/spec-to-ui-reasoning.md`
+### 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`.
@@ -790,7 +790,7 @@ The "Remaining open items" table in `REFACTOR-PROGRESS.md` shifts:
 
 ## 3.6.1 (2026-05-24)
 
-**PATCH** — Tighten wireframe content discipline in `references/spec-to-ui-reasoning.md` §Wireframe checkpoint. Operator concern: "make sure ASCII wireframes contents is crisp and concise and not include html etc."
+**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
 
@@ -859,7 +859,7 @@ The ladder + wireframing rubric IS the missing pre-composition pipeline. v3.6.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 — `references/spec-to-ui-reasoning.md` (~23KB)
+### New reference — `../spec-to-ui-reasoning.md` (~23KB)
 
 The kit-specific operationalization of the 2 canonical sources. Covers:
 
@@ -922,17 +922,17 @@ Both defects were the same shape: a reference file was authored (Phase 3, v3.0.0
 
 **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 [`references/diagnostic-output.md`](../../references/diagnostic-output.md) (2,511 bytes). Trimmed to a thin pointer matching the established stub shape.
+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 [`references/feedback-authoring.md`](../../references/feedback-authoring.md) (the canonical 6-step procedure with sub-templates) and [`references/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.
+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 — `references/audit-scripts.md` (-1.4KB from §PEV)
+### 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 (`references/audit-scripts.md`, 3.4KB) covers:
+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)
@@ -1143,7 +1143,7 @@ Verified 3 scenarios: happy path (exit 0), bad root (exit 2), empty refs dir (ex
 
 ### 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 docs/demos to actual JS):
+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.
@@ -1284,15 +1284,15 @@ Each fix grep-verified against substrate yaml before commit per the v3.4.0 regis
 
 | Stale tag | Replacement | Files |
 |-----------|------------|-------|
-| `<form-field>` | `<field-ui>` (substrate primitive) | `references/decision-model.md` (2×) |
-| `<breadcrumb-item-ui>` | plain `<a>`/`<span>` children inside `<breadcrumb-ui>` (separator auto via CSS `::before`; no item element) | `references/patterns-shells.md` (2×) |
-| `<form-container-ui>` | raw `<form>` element with `action=` / `method=` attrs | `references/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) | `references/patterns-forms.md` (1×) |
-| `<dialog-ui title="..." message="..." confirm-text="..." cancel-text="...">` | `<confirm-dialog-ui>` (web-modules/feedback) — same attrs except `message` → `description` | `references/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. | `references/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`. | `references/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. | `references/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). | `references/flows-shells.md`, `references/patterns-recipes.md` (2×), `references/rendering-model.md` |
+| `<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
 
@@ -1444,7 +1444,7 @@ The HIGH-severity slot-mismatch check was demoted to INFO in this ship. The yaml
 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:
-- `references/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
+- `../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)
@@ -1481,7 +1481,7 @@ The user's broader observation — "a lot of the example code in the skill is po
 
 **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 — `references/patterns-shells.md` admin-shell recipe rewritten end-to-end
+### 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.
 
@@ -1493,11 +1493,11 @@ Rewrite extracted directly from `chat-ui:site/index.html` (the canonical):
 - 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 — `references/patterns-shells.md` "Admin product page" composition recipe rewritten
+### 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 — `references/patterns-recipes.md` Cold-Start app recipe — slot drift fix
+### 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.
 
@@ -1539,7 +1539,7 @@ Three precedents argue for MINOR:
 
 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.
 
-- `references/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."*
+- `../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>`.
 
@@ -1547,7 +1547,7 @@ This is a behavior change consumers may not notice in source code — the markup
 
 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):
 
-- `references/composition.md`: new `### v0.6.34 new primitives` subsection with a single-row-per-primitive description table covering:
+- `../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)
@@ -1566,7 +1566,7 @@ Each entry names the substrate yaml's category, ground-truth description, and mo
 
 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.
 
-- `references/composition.md`: new `### Theming via component-leaf tokens (OD-5 -default suffix, v0.6.34+)` H3 section. Documents:
+- `../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)
@@ -1598,7 +1598,7 @@ Substrate-currency sweeps consistently shipped as MINOR (precedent: v2.28.0 32-i
 - 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 `docs/specs/implementation-completed/`
+- Wave 1+2 components: 10 P1 specs in `.claude/docs/specs/implementation-completed/`
 
 ---
 
@@ -1608,7 +1608,7 @@ Substrate-currency sweeps consistently shipped as MINOR (precedent: v2.28.0 32-i
 
 ### D4 — editor-canvas public API wiring recipe
 
-New "Editor canvas API + state" H2 section in `references/patterns-shells.md` between "Editor-inside-admin" and "Chat shell". Three subsections:
+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.
@@ -1651,7 +1651,7 @@ Same precedent as v3.1.1 (D3+D5 recipe additions shipped as PATCH): recipe addit
 
 ### Cross-references
 
-- D-item taxonomy: see v3.1.1 entry above and `docs/REFACTOR-PROGRESS.md` Post-Phase-4 hygiene block
+- 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`
 
@@ -1703,7 +1703,7 @@ Per VersionBump policy: new capability shipped (a new audit tool with its own be
 
 ### Cross-references
 
-- The v3.1.1 reflection that motivated this: `docs/REFACTOR-PROGRESS.md` Post-Phase-4 hygiene block.
+- 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`.
 
@@ -1722,8 +1722,8 @@ Per VersionBump policy: new capability shipped (a new audit tool with its own be
 
 ### D1 — editor-toolbar slot vocabulary corrected
 
-- `references/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.
-- `references/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).
+- `../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
 
@@ -1731,11 +1731,11 @@ Per VersionBump policy: new capability shipped (a new audit tool with its own be
 
 ### D3 — Standalone pane-ui (split-pane layout) recipe added
 
-- `references/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).
+- `../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
 
-- `references/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.
+- `../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)
 
@@ -1768,24 +1768,24 @@ Both deferred items are depth-additions, not bug-fixes. They may land in v3.1.2
 ### 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** `references/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).
+- **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** `references/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** `../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** `references/decision-model.md` — `decisions: [{decision, requiredSignal, possibleActions, chosenAction, rationale}]` contract. Worked login-page example. Allowlist-via-rationale escape hatch.
+- **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 `references/session-log-schema.md`; documents `validate-session-log.mjs` + `audit-decision-trace.mjs` + the advisory-vs-strict rollout.
+- **§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
@@ -1831,34 +1831,34 @@ Per kit's §VersionBump policy: MAJOR = breaking structural change to the seed s
 
 ### What landed — §6.1 §LoadingProtocol extraction
 
-- **`references/loading-protocol.md`** (NEW, ~25KB) — full pre-author bundle gate trigger list, reference manifest, harness manifest, on-demand bundle rules.
+- **`../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
 
-- **`references/correction-loop.md`** (NEW, ~23KB) — 4-layer triage tree, 5 sniff tests for root cause, 7 worked examples, compound-fix anti-patterns.
+- **`../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
 
-- **`references/mission.md`** (NEW, ~11KB) — full 5-step consultant inventory, consultant-vs-author posture matrix, §Recon trigger list, worked examples.
+- **`../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
 
-- **`references/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.
+- **`../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
 
-- **`references/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.
-- **`references/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.
+- **`../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
 
-- **`references/capabilities.md`** (NEW, ~14KB) — full 14-mode menu + per-mode triage table + "pick your entry point" rows.
-- **`references/mode-routing.md`** (NEW, ~15KB) — full mode-routing usage detail, prompt-shape interpretation, mode-routing examples, cold-start checkpoint mechanics.
+- **`../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.
 

package/skills/adia-ui-kit/references/common-gotchas-consumer.md

@@ -7,7 +7,7 @@ required-for:
   - Any surface containing toolbars / button clusters / form-control rows
   - Any surface using container queries for responsive layout
   - Debugging a "passes audit but looks broken" defect
-companion-skill: "adia-ui-authoring v1.8.2 (sister skill's `references/common-gotchas.md` — same patterns, substrate-side framing)"
+companion-skill: "adia-ui-authoring v1.8.2 (sister skill's own `common-gotchas.md` reference — same patterns, substrate-side framing)"
 sister-postmortems:
   - ".brain/postmortems/2026-05-24-component-css-illiteracy.md"
   - ".brain/postmortems/2026-05-24-card-structure-audit-enforcement-gap.md"
@@ -19,7 +19,7 @@ Four concrete failure modes recurring across the 2026-05-24 billing-overview + 8
 
 Each entry: pattern + how to detect + the right fix + sister-skill citation.
 
-This reference parallels `adia-ui-authoring`'s `references/common-gotchas.md` (5 gotchas; the 5th — nested HTML comments in design-plan blocks — is substrate-side authoring-specific and not relevant to consumer composition).
+This reference parallels the `adia-ui-authoring` sister skill's own `common-gotchas.md` (5 gotchas; the 5th — nested HTML comments in design-plan blocks — is substrate-side authoring-specific and not relevant to consumer composition).
 
 ---
 
@@ -51,7 +51,7 @@ This reference parallels `adia-ui-authoring`'s `references/common-gotchas.md` (5
 - `npm run audit:card-structure --strict` in the consuming repo (substrate audit; runs against any HTML the consumer authors)
 - Visual: chrome looks "flat" — no inset between border and content, sibling divs touching the card edge
 
-**The right fix**: USE the composite's grammar. Pre-flight Component Literacy (`references/component-literacy.md`) is the upstream defense; this gotcha is what happens when literacy is skipped.
+**The right fix**: USE the composite's grammar. Pre-flight Component Literacy (`component-literacy.md`) is the upstream defense; this gotcha is what happens when literacy is skipped.
 
 **Sister postmortem**: `.brain/postmortems/2026-05-24-component-css-illiteracy.md`
 **Sister commit**: chat-ui `4e86400c9` (payment-method-list rewrite to canonical grammar)

package/skills/adia-ui-kit/references/css-policy.md

@@ -240,7 +240,7 @@ the CDN URL rather than an npm import path.
 > shells-only bug, so the only working pre-0.6.32 path is the
 > dual-bundle workaround).
 
-**Authoritative reference**: `references/setup.md` Step 0.5 (peer authored
+**Authoritative reference**: `setup.md` Step 0.5 (peer authored
 in the v0.6.30 cycle); full CDN docs at
 [`ui-kit.exe.xyz/site/getting-started/cdn-usage`](https://ui-kit.exe.xyz/site/getting-started/cdn-usage);
 working CodePen template at

package/skills/adia-ui-kit/references/decision-model.md

@@ -138,7 +138,7 @@ The audit subtracts allowlist entries from findings. Allowlist additions should
 ## What v3.1.0 ships
 
 - `scripts/audit-decision-trace.mjs` — runs in advisory mode by default. Reads a JSONL session log (per `session-log-schema.md`), extracts `decision_made` and `component_named` events, walks the trace, reports orphan-component findings.
-- `references/decision-model.md` — this document.
+- `decision-model.md` — this document.
 - **No SKILL.md hard requirement** that agents emit DecisionModel events in v3.1.0 — emission is opt-in / advisory.
 
 ## What v3.2.0+ may add
@@ -152,7 +152,7 @@ The audit subtracts allowlist entries from findings. Allowlist additions should
 ## Cross-references
 
 - `scripts/audit-decision-trace.mjs` — the runtime audit
-- `references/session-log-schema.md` — the JSONL event format that this audit consumes
-- `references/teach-protocol.md` — branch-D decisions about NEW methodologies land here
+- `session-log-schema.md` — the JSONL event format that this audit consumes
+- `teach-protocol.md` — branch-D decisions about NEW methodologies land here
 - REFACTOR-SPEC P5(b) — origin of this contract
 - AGENTS.md Plan-Execute-Verify rule (§14) — the discipline that DecisionModel mechanizes