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

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

@@ -6,13 +6,13 @@
 
 **MINOR** — Phase 2 of the REFACTOR-SPEC refactor (v2.28.0 → v3.0.0). Bundles the two substrate audit scripts (`audit-native-primitive-leak.mjs` + `audit-shell-composition.mjs`) into the kit with portable path resolution, adds a kit-focused routing corpus, and ships a portable `run-skill-evals.mjs` runner. The Mode 1–4 verify step is now genuinely portable — consumers can `cd <their-repo>; node /path/to/kit/scripts/audit-shell-composition.mjs` without depending on the chat-ui substrate.
 
-Closes spec P1 (M3 — verify-step portability) + P3 (M1 — routing accuracy portability). Tracked in `docs/REFACTOR-PROGRESS.md`.
+Closes spec P1 (M3 — verify-step portability) + P3 (M1 — routing accuracy portability). Tracked in `.claude/docs/REFACTOR-PROGRESS.md`.
 
 ### What landed
 
 - **`scripts/audit-native-primitive-leak.mjs`** (NEW, ~330 lines) — bundled copy of the substrate script. Path resolution rewritten: `REPO_ROOT = process.cwd()` by default, override via `--root=<path>`. Substrate copy at `scripts/dev/audit-native-primitive-leak.mjs` remains the canonical source for behavioral logic; the bundled copy adds only path portability. Header notes the bundled-copy convention.
 - **`scripts/audit-shell-composition.mjs`** (NEW, ~635 lines) — same treatment. Catches the FEEDBACK-41 cluster (missing `<admin-statusbar>`, `[data-spacer]`, `[data-actions]`, etc.) regardless of which repo it's run from.
-- **`evals/routing-corpus.json`** (NEW) — kit-focused routing corpus with **10 trigger phrases** (canonical composition tasks the kit SHOULD activate on) + **5 adversarial phrases** (authoring-NEG, release-NEG, a2ui-NEG, bare-framework, bare-verb). Meets spec P3 minimums (≥10 trigger + ≥5 adversarial, ≥33% adversarial fraction).
+- **`../../evals/routing-corpus.json`** (NEW) — kit-focused routing corpus with **10 trigger phrases** (canonical composition tasks the kit SHOULD activate on) + **5 adversarial phrases** (authoring-NEG, release-NEG, a2ui-NEG, bare-framework, bare-verb). Meets spec P3 minimums (≥10 trigger + ≥5 adversarial, ≥33% adversarial fraction).
 - **`scripts/run-skill-evals.mjs`** (NEW, ~310 lines) — portable eval runner. Three modes: (1) routing eval against `routing-corpus.json` (emits F1 + TP/FP/FN/TN; uses TF-IDF-style token-overlap compatible with substrate scorer); (2) behavioral structural count of `evals.json`; (3) adversarial structural count of `adversarial-content-trust.json`. Auto-detects substrate-vs-standalone mode. Accepts `--kit-dir=<path>` so consumer repos can invoke it via `node ./node_modules/adia-ui-kit/scripts/run-skill-evals.mjs --kit-dir=./node_modules/adia-ui-kit`. The counter-proposal from Phase 1 (consumer-repo CI compatibility) is landed.
 - **SKILL.md verify-target table** — Mode 1–4 row now cites `.agents/skills/adia-ui-kit/scripts/audit-*.mjs` (the bundled paths) instead of substrate-only `scripts/dev/audit-*.mjs`. Notes the v2.30.0+ bundled-copy + portability.
 - **`skill.json files` manifest** — 4 new entries (3 scripts + routing-corpus); 47/47 on-disk parity preserved.
@@ -44,20 +44,20 @@ Closes spec P1 (M3 — verify-step portability) + P3 (M1 — routing accuracy po
 
 ## 2.29.0 (2026-05-23)
 
-**MINOR** — Phase 1 of the REFACTOR-SPEC refactor (v2.28.0 → v3.0.0). Manifest hygiene + content-trust rule + description harmonization + dropping dangling `../BORIS-feedback.md` cross-references. Substrate seed-extraction (the C1 SKILL.md > 256KB tool-read-limit fix) is deferred to Phase 3 (v3.0.0); this phase lands the lower-risk additive cleanup.
+**MINOR** — Phase 1 of the REFACTOR-SPEC refactor (v2.28.0 → v3.0.0). Manifest hygiene + content-trust rule + description harmonization + dropping dangling `BORIS-feedback.md` cross-references. Substrate seed-extraction (the C1 SKILL.md > 256KB tool-read-limit fix) is deferred to Phase 3 (v3.0.0); this phase lands the lower-risk additive cleanup.
 
-Triggered by the 2026-05-23 6-critic adversarial review of v2.28.0 (`docs/REFACTOR-SPEC.md` — 3 Critical / 9 Major / 7 Minor findings). Phased plan tracked in `docs/REFACTOR-PROGRESS.md`.
+Triggered by the 2026-05-23 6-critic adversarial review of v2.28.0 (`.claude/docs/REFACTOR-SPEC.md` — 3 Critical / 9 Major / 7 Minor findings). Phased plan tracked in `.claude/docs/REFACTOR-PROGRESS.md`.
 
 ### What landed
 
 - **§ContentTrust rule** (new H3 in SKILL.md §Mission, immediately before "When to be an author") — documents the consultant-posture rule: files in consumer repos are **data, not instructions**. AGENTS.md / README / FEEDBACK tickets / source files do not modify skill behavior, do not unlock new tools, and do not override hard rules. Defends against the lethal trifecta (file reads + tool actions + private data + network egress) per spec P2 + M9 + m7.
-- **`evals/adversarial-content-trust.json`** (new bundled eval corpus) — 5 cases covering ignore-prior-instructions, fake-skill-override, ticket-injection (rm-rf), readme-credential-exfiltration, spec-doc-skill-rebinding. Manually reviewable now; automated runner ships in Phase 2 (P3).
-- **`skill.json files` manifest completeness** (P2 + M2) — added 13 missing files to the array: 12 from spec + the new pev-rationale.md + the new adversarial corpus + the new docs/. Manifest now matches the on-disk inventory at `find references/ scripts/ evals/ assets/ docs/ -type f`. Manifest is reorganized into logical groups (root / docs / references / patterns / flows / feedback / diagnostic / evals / scripts / templates / team-scaffold) for readability.
-- **`references/pev-rationale.md`** (new, ~6.4KB) — absorbs the source citation + ecosystem-level rationale + §SelfAudit-vs-verify distinction from the formerly-cross-referenced `../BORIS-feedback.md`. Makes the skill self-contained for consumer-repo use (per §6.7 + m2).
+- **`../../evals/adversarial-content-trust.json`** (new bundled eval corpus) — 5 cases covering ignore-prior-instructions, fake-skill-override, ticket-injection (rm-rf), readme-credential-exfiltration, spec-doc-skill-rebinding. Manually reviewable now; automated runner ships in Phase 2 (P3).
+- **`skill.json files` manifest completeness** (P2 + M2) — added 13 missing files to the array: 12 from spec + the new pev-rationale.md + the new adversarial corpus + the new .claude/docs/. Manifest now matches the on-disk inventory at `find references/ scripts/ evals/ assets/ .claude/docs/ -type f`. Manifest is reorganized into logical groups (root / docs / references / patterns / flows / feedback / diagnostic / evals / scripts / templates / team-scaffold) for readability.
+- **`../pev-rationale.md`** (new, ~6.4KB) — absorbs the source citation + ecosystem-level rationale + §SelfAudit-vs-verify distinction from the formerly-cross-referenced `BORIS-feedback.md`. Makes the skill self-contained for consumer-repo use (per §6.7 + m2).
 - **Description harmonization** (§6.6 + m1) — SKILL.md frontmatter `description:` now matches `skill.json description` verbatim (the canonical 807-char WHAT+WHEN+NEG form). The verbose ~2.5KB description block was removed. The `trigger:` block (which holds the high-coverage routing keyword surface) is unchanged — verified that the substrate routing scorer at `scripts/skills/run-skill-evals.mjs:126` reads `${fm.description || ''} ${fm.trigger || ''} ${fm.triggers || ''}`, so token coverage is preserved.
-- **Dangling `../BORIS-feedback.md` references removed** (§6.7 + m2) — the 2 occurrences in SKILL.md (lines ~265 + ~4878) now point to `references/pev-rationale.md`. `grep -n 'BORIS-feedback' SKILL.md` returns 0 hits.
-- **`docs/REFACTOR-SPEC.md`** committed as a tracked artifact (was untracked).
-- **`docs/REFACTOR-PROGRESS.md`** authored as the phase ledger — tracks status / verify outcomes / counter-proposals for kimba per phase / cross-phase invariants.
+- **Dangling `BORIS-feedback.md` references removed** (§6.7 + m2) — the 2 occurrences in SKILL.md (lines ~265 + ~4878) now point to `../pev-rationale.md`. `grep -n 'BORIS-feedback' SKILL.md` returns 0 hits.
+- **`.claude/docs/REFACTOR-SPEC.md`** committed as a tracked artifact (was untracked).
+- **`.claude/docs/REFACTOR-PROGRESS.md`** authored as the phase ledger — tracks status / verify outcomes / counter-proposals for kimba per phase / cross-phase invariants.
 
 ### What did NOT land (deferred)
 
@@ -71,7 +71,7 @@ Triggered by the 2026-05-23 6-critic adversarial review of v2.28.0 (`docs/REFACT
 - New H3 section (§ContentTrust) in SKILL.md
 - New bundled reference file (pev-rationale.md)
 - New bundled eval corpus (adversarial-content-trust.json)
-- New tracked artifacts (docs/REFACTOR-SPEC.md + docs/REFACTOR-PROGRESS.md)
+- New tracked artifacts (.claude/docs/REFACTOR-SPEC.md + .claude/docs/REFACTOR-PROGRESS.md)
 - Per kit's own §VersionBump policy: MINOR = new section + capability
 
 ### Verify-the-output
@@ -172,7 +172,7 @@ Closes [FEEDBACK-52 skill-updates-post-session-docs-bundle-fixes](/Users/kimba/P
 
 - **§Docs "Component stability — `status` badge"** — new 5-row table mapping status values to docs-site badge variants (stable/beta/experimental/deprecated/early-access). Documents the v0.6.32+ status-badge system: yaml `status:` field → sidecar `x-adiaui.status` → docs site auto-injects `<tag-ui>` badge. Authoring guidance cross-references `adia-ui-authoring` yaml contract.
 
-- **`references/patterns-recipes.md` new H2 "Card-ui header — slotted children, NOT `<div>` wrapper"** — paste-ready wrong/right examples for the `<card-ui><header><div>` anti-pattern that silently bypasses card-ui's `:has(> [slot])` grid activator. Title + badge collapse into a full-width row instead of the canonical 1fr-heading + auto-action layout. 4-row available-slots table (icon/heading/description/action). CSS mechanism cited for archeology. Detection is manual (visual); see dogfood-sweep §Component Anatomy + Card Header Sweep for the static-grep probe.
+- **`../patterns-recipes.md` new H2 "Card-ui header — slotted children, NOT `<div>` wrapper"** — paste-ready wrong/right examples for the `<card-ui><header><div>` anti-pattern that silently bypasses card-ui's `:has(> [slot])` grid activator. Title + badge collapse into a full-width row instead of the canonical 1fr-heading + auto-action layout. 4-row available-slots table (icon/heading/description/action). CSS mechanism cited for archeology. Detection is manual (visual); see dogfood-sweep §Component Anatomy + Card Header Sweep for the static-grep probe.
 
 ### Diagnosis from the ticket
 
@@ -192,7 +192,7 @@ All three cases are kit-recipe gaps — the substrate had either already fixed t
 
 ## 2.27.2 (2026-05-23)
 
-**PATCH** — `references/patterns-data.md` §Row-Click → Detail Drawer: add editable-drawer-field recipe + `stat-ui` substitution anti-pattern (FEEDBACK-01 from claims-ui-v9 2026-05-23).
+**PATCH** — `../patterns-data.md` §Row-Click → Detail Drawer: add editable-drawer-field recipe + `stat-ui` substitution anti-pattern (FEEDBACK-01 from claims-ui-v9 2026-05-23).
 
 Closes [FEEDBACK-50 drawer-composition-recipe-gap](/Users/kimba/Projects/chat-ui/.agents/team/tickets/inbound/archive/FEEDBACK-50--claims-ui-v9--drawer-composition-recipe-gap--2026-05-23.md). Triage verdict: pure recipe gap; NO substrate/packages work needed (the underlying primitives — `input-ui`, `field-ui`, `stat-ui` — all work as designed and have accurate yaml descriptions; the canonical exemplar `packages/web-components/patterns/form-drawer/form-drawer.examples.html` already exists and uses `<field-ui>` 17 times). The skill recipe was the bottleneck.
 
@@ -223,13 +223,13 @@ Both failures trace to a single root cause: the kit's drawer recipe showed only
 - `check:skills:strict` → 5/5 senior, 0 P-failures, 0 broken-section-references
 - `routing-eval --strict` → 96.7% (corpus untouched)
 - `audit:skill-hygiene` → kit at ~257K (still over 250K warn threshold; +1.4K from this PATCH)
-- The new recipe content is self-contained in `references/patterns-data.md` §Row-Click → Detail Drawer; no main SKILL.md body changes (PATCH discipline — additive content in reference file, no §-section restructuring).
+- The new recipe content is self-contained in `../patterns-data.md` §Row-Click → Detail Drawer; no main SKILL.md body changes (PATCH discipline — additive content in reference file, no §-section restructuring).
 
 ## 2.27.1 (2026-05-23)
 
 **PATCH** — Setup checklist: add pitfall for `@adia-ai/web-modules/shell/admin-shell` (per-component path) vs `@adia-ai/web-modules/shell` (cluster barrel).
 
-- **Where:** `references/setup.md` §Setup checklist — new bullet after the existing "per-cluster barrel, NOT full barrel" item.
+- **Where:** `../setup.md` §Setup checklist — new bullet after the existing "per-cluster barrel, NOT full barrel" item.
 - **Triggers:** "sidebar toggle not working", "resize not working", "shell/admin-shell import", "AdminSidebar not registered"
 - **Replaces:** nothing — gap fill, not a correction of existing text.
 
@@ -243,7 +243,7 @@ Both failures trace to a single root cause: the kit's drawer recipe showed only
 
 **MINOR** — Canonical admin-shell reference drift fix (8 parts → 13 parts; `<menu-ui>` → `<select-ui avatar=…>`; native `<section>` → `<section-ui>`).
 
-User-surfaced drift: the consumer-prompt at `/tmp/claims-ui-consumer-prompt.md` cited `<menu-ui data-context-switcher>` + native `<section>` + a fictitious `<theme-picker-ui>` element. Comparison with the live docs site at `http://localhost:5174/site/examples/admin-dashboard` (which renders from `chat-ui:site/index.html`) showed every one of those tag choices was wrong. Root cause: the kit's own `references/patterns-recipes.md` was ambiguous — it named BOTH `<menu-ui>` and `<select-ui avatar=…>` as valid patterns and called native `<section>` "canonical per admin-shell.examples.html". The substrate's `admin-shell.examples.html` IS the v0.5.x form (uses menu-ui + native section); the live docs site migrated to select-ui + section-ui as the new canonical form, but the recipe didn't follow. My consumer prompt picked the wrong one because the recipe was non-committal.
+User-surfaced drift: the consumer-prompt at `/tmp/claims-ui-consumer-prompt.md` cited `<menu-ui data-context-switcher>` + native `<section>` + a fictitious `<theme-picker-ui>` element. Comparison with the live docs site at `http://localhost:5174/site/examples/admin-dashboard` (which renders from `chat-ui:site/index.html`) showed every one of those tag choices was wrong. Root cause: the kit's own `../patterns-recipes.md` was ambiguous — it named BOTH `<menu-ui>` and `<select-ui avatar=…>` as valid patterns and called native `<section>` "canonical per admin-shell.examples.html". The substrate's `admin-shell.examples.html` IS the v0.5.x form (uses menu-ui + native section); the live docs site migrated to select-ui + section-ui as the new canonical form, but the recipe didn't follow. My consumer prompt picked the wrong one because the recipe was non-committal.
 
 **Resolution**: `chat-ui:site/index.html` declared the **single authoritative reference**. The recipe demotes menu-ui + native-section to legacy/deprecated alternatives. The skill's canonical part-list grows 8 → 13 to match site/index.html's actual structure. The audit script grows 9 → 20 probes (11 new info-level probes covering the previously-missing parts).
 
@@ -265,7 +265,7 @@ User-surfaced drift: the consumer-prompt at `/tmp/claims-ui-consumer-prompt.md`
 
 - **§LoadingProtocol pre-author bundle gate verification** — enumerate-the-13-parts list updated to match §Mission. Each part has its canonical primitive named + the wrong primitive called out. Note added: "as of v2.27.0 the recipe was corrected to align with site/index.html (it had previously been ambiguous)".
 
-- **`references/patterns-recipes.md` Advanced shell recipe** — 6 surgical patches: (1) high-level Advanced/Default/Simple table now names `<select-ui avatar>` not `<menu-ui>`; (2) context-switcher inline example uses `<select-ui avatar>` with the legacy `<menu-ui>` form moved to a "Legacy form" callout; (3) nav wrapper uses `<section-ui>` not native `<section>` with native form moved to legacy callout; (4) user-menu uses `<select-ui avatar>` with the menu-ui form preserved as commented-out legacy reference for downstream agents who need to recognize older code; (5) Simple-shell variant diff block updated to remove select-ui (not menu-ui) when stepping down; (6) admin-entity-item read-only identity section references `<select-ui>` not `<menu-ui>` as the interactive alternative.
+- **`../patterns-recipes.md` Advanced shell recipe** — 6 surgical patches: (1) high-level Advanced/Default/Simple table now names `<select-ui avatar>` not `<menu-ui>`; (2) context-switcher inline example uses `<select-ui avatar>` with the legacy `<menu-ui>` form moved to a "Legacy form" callout; (3) nav wrapper uses `<section-ui>` not native `<section>` with native form moved to legacy callout; (4) user-menu uses `<select-ui avatar>` with the menu-ui form preserved as commented-out legacy reference for downstream agents who need to recognize older code; (5) Simple-shell variant diff block updated to remove select-ui (not menu-ui) when stepping down; (6) admin-entity-item read-only identity section references `<select-ui>` not `<menu-ui>` as the interactive alternative.
 
 - **dogfood-sweep `§ Admin-Shell Composition Audit` body** — 8 canonical parts → 13 canonical parts. Each commonly-missing part annotated with ★. Severity definitions updated: `warning` now includes "uses wrong primitive (e.g. `<menu-ui>` instead of `<select-ui>` for the context-switcher; native `<section>` instead of `<section-ui>` for the nav wrap)". Authoritative reference (`site/index.html` lines 42-120) named inline.
 
@@ -343,7 +343,7 @@ Three landings:
 
 - **§Recon Step 3** — strengthened from "note the declared range" to a 3-check sequence: (a) declared in package.json, (b) installed in node_modules, (c) imported in src/. Halt-condition explicit: if (c)>0 and (a) empty, the manifest is gapped — do not compose any further UI until the operator declares + installs.
 - **§GapDetection — new Gap class 0: Manifest gap (build-blocker)** before the existing 3 classes. Vite resolution fails at `npm run dev` on bare specifiers like `@adia-ai/web-components`. Error message ("Are they installed?") is misleading — they were never *declared*; `npm install` (no args) won't fix it. Remediation: `npm install <package>` with the matching reference shape from a known-good sibling consumer.
-- **`references/setup.md` Step 0** — pre-flight manifest gate. Authoring imports against an empty manifest creates source that won't start; surface the gap with the install command before that happens.
+- **`../setup.md` Step 0** — pre-flight manifest gate. Authoring imports against an empty manifest creates source that won't start; surface the gap with the install command before that happens.
 
 **Anti-pattern caught:** authoring imports into `src/main.ts` in a freshly-scaffolded consumer repo before the operator has added `@adia-ai/*` to the package.json manifest. The next `npm run dev` halts with "could not be resolved" on bare specifiers — a build-blocker that the agent should detect before authoring, not after.
 
@@ -355,7 +355,7 @@ Tracks the BORIS plan-execute-verify discipline: verify the environment can run
 
 ## [Previously-unreleased pitfall, folded into 2.24.0]
 
-- **admin-shell display:block pitfall (§FB-04)** — `references/patterns-layout.md` §App Shell: added pitfall block. (Was staged under [Unreleased]; promoted with this MINOR cut.)
+- **admin-shell display:block pitfall (§FB-04)** — `../patterns-layout.md` §App Shell: added pitfall block. (Was staged under [Unreleased]; promoted with this MINOR cut.)
 
 ## 2.23.1 (2026-05-22)
 
@@ -561,7 +561,7 @@ Three citation-strengthening edits:
   pointing at `VISION-extensibility.md` and naming sibling roll-ups
   (`adia-ui-release`, `adia-ui-authoring`) as the eventual second/third
   instantiations of the extensibility pattern.
-- `references/teach-protocol.md` gained an "Ecosystem context" line in
+- `../teach-protocol.md` gained an "Ecosystem context" line in
   the provenance block, framing the file as the canonical template
   sibling roll-ups will copy when adopting §Teach.
 - The version bumps + this CHANGELOG entry.
@@ -622,7 +622,7 @@ patterns reference for cross-component recipes, a flows reference for
 end-to-end journeys, inline SKILL.md for methodology/posture shifts, a
 harness-manifest cross-link for tooling additions, §CorrectionLoop for
 FEEDBACK resolutions, or **NO landing in the skill** (arc stories
-belong in `docs/journal/`, not here).
+belong in `.claude/docs/journal/`, not here).
 
 ### MINOR bump rationale
 
@@ -631,7 +631,7 @@ section + capability menu item + reference file = new procedural
 surface, not citation strengthening. Per §SkillHygiene discipline rule
 5 ("MINOR cuts ship new sections; PATCH cuts polish existing ones"),
 bundling this with v2.20.9's two recipe additions would have muddied
-the changelog narrative. Reference: `references/teach-protocol.md`'s
+the changelog narrative. Reference: `../teach-protocol.md`'s
 own anti-pattern 5 ("don't bundle MINOR + PATCH in one cut") — the
 skill is dogfooding its own §Teach discipline.
 
@@ -645,7 +645,7 @@ keyword wiring. The total v2.21.0 picture across both commits:
 
 - **§Teach section in SKILL.md** (~89 lines, shipped in peer's
   `7ff9bcb74` 2026-05-22) — stub pointing to
-  `references/teach-protocol.md`. Placed adjacent to §SkillHygiene
+  `../teach-protocol.md`. Placed adjacent to §SkillHygiene
   (the two are sibling disciplines — audit + train). Contains the
   30-second procedure summary, the load-bearing principle ("the skill
   is a CITATION layer, not a KNOWLEDGE layer"), and cross-references
@@ -657,14 +657,14 @@ keyword wiring. The total v2.21.0 picture across both commits:
   new knowledge — make adia-ui-kit aware of X → §Teach".
 
 - **Reference manifest row** (shipped in `7ff9bcb74`) —
-  `references/teach-protocol.md` joins the manifest table with "full
+  `../teach-protocol.md` joins the manifest table with "full
   extract (v2.21.0)" tag.
 
-- **`references/teach-protocol.md`** (394 lines, shipped earlier in
+- **`../teach-protocol.md`** (394 lines, shipped earlier in
   `3e831e898` as the option-3 carve-out) — the full procedural detail:
   seven-branch decision tree, five-step landing procedure, seven
   worked examples (A through G, including the **negative case G**
-  where the correct landing is `docs/journal/`, NOT the skill), seven
+  where the correct landing is `.claude/docs/journal/`, NOT the skill), seven
   anti-patterns, and a quick-reference routing card.
 
 - **Trigger keywords** (this commit) — 12 phrases added to the
@@ -678,7 +678,7 @@ keyword wiring. The total v2.21.0 picture across both commits:
   activation surface even though the section + reference file exist.
 
 - **Version bumps** (this commit) — SKILL.md frontmatter 2.20.8 →
-  2.21.0, skill.json 2.20.9 → 2.21.0, plus `references/teach-protocol.md`
+  2.21.0, skill.json 2.20.9 → 2.21.0, plus `../teach-protocol.md`
   added to the `files` array.
 
 - **CHANGELOG.md** (this commit) — this entry. Acknowledges peer's
@@ -769,7 +769,7 @@ landing protocol applied to its own creation. Walk-through:
   +1 triage table row, +1 reference manifest row, +1 trigger keyword
   cluster, version bump 2.20.8 → 2.21.0)
 - `skill.json` (version bump 2.20.9 → 2.21.0, +1 entry in files array)
-- `references/teach-protocol.md` (was shipped in `3e831e898` 2026-05-22)
+- `../teach-protocol.md` (was shipped in `3e831e898` 2026-05-22)
 - `CHANGELOG.md` (this entry)
 
 ### Pairs with
@@ -825,7 +825,7 @@ breaking changes to existing recipes; this is purely additive.
 
 ### Files touched
 
-- `references/patterns-recipes.md` (+104 lines, 2 new recipes at end)
+- `../patterns-recipes.md` (+104 lines, 2 new recipes at end)
 - `skill.json` version bump
 - `CHANGELOG.md` this entry
 
@@ -1137,7 +1137,7 @@ Chose Option A for this cut. Rationale:
   - Routing analysis preserved in the bundle's loading note for
     that future cut
 
-THE NEW BUNDLE — `references/patterns-recipes.md` (35KB):
+THE NEW BUNDLE — `../patterns-recipes.md` (35KB):
   - Admin shell anatomy (→ future patterns-shells.md)
   - App-shell composition tiers — Advanced / Simple / Minimal
   - Data binding: REST endpoint → component (→ future patterns-wiring.md)
@@ -1158,7 +1158,7 @@ all-extract milestone.
 Stub left in SKILL.md teaches:
   - 1-paragraph summary of patterns vs flows axis
   - Visual reference + recipe-doc pointers (ui-kit.exe.xyz/site/pages/patterns/,
-    docs/guides/71-recipes.md, ui-kit.exe.xyz/site/modules/)
+    .claude/docs/guides/71-recipes.md, ui-kit.exe.xyz/site/modules/)
   - Bundle map table (8 bundles, 'load when' column)
   - 'Skip if' disqualifier (end-to-end → §Flows; structural → §1+§2)
   - 'Pair with' axis explanation
@@ -2158,7 +2158,7 @@ slug-normalisation fix. Doc + tooling only — no substrate change.
   `<breadcrumb-ui slot="heading">`** (FB-19). Both composition examples
   corrected to the default slot, so the skill no longer demonstrates the
   anti-pattern it now warns against.
-- **`scripts/ticket-tool.py` — `cmd_new` slug normalisation** (FB-21).
+- **`ticket-tool.py` — `cmd_new` slug normalisation** (FB-21).
   An uppercase character in a `--slug` value (e.g. `innerHTML`) produced
   a filename `FILENAME_RE` silently rejects, so `finalize` reported the
   draft as missing. `cmd_new` now lowercases the slug and collapses any
@@ -2459,7 +2459,7 @@ ADR-0031 landed the central inbound store at
 tooling were unwired — consumer projects had no way to route tickets
 there without manual `cp`. This version closes the loop:
 
-- **`scripts/ticket-tool.py`** gained `ADIA_TICKETS_DIR` env-var
+- **`ticket-tool.py`** gained `ADIA_TICKETS_DIR` env-var
   support: when set, all subcommands operate against the central
   store regardless of which repo the CLI is invoked from. Resolution
   order: env var (central mode) → `find_repo_root() / TICKETS_REL`
@@ -2511,7 +2511,7 @@ there without manual `cp`. This version closes the loop:
   `files:` manifest (`AGENTS.template.md`, `CLAUDE.template.md`,
   `check-adia-versions.py`).
 - `CHANGELOG.md` — this entry.
-- `scripts/ticket-tool.py` — `ADIA_TICKETS_DIR` env-var, resolve
+- `ticket-tool.py` — `ADIA_TICKETS_DIR` env-var, resolve
   helpers, regex widening, TicketPath.from_path sender_slug, scan
   list extension.
 - `assets/templates/AGENTS.template.md` — central-inbound workflow
@@ -2529,12 +2529,12 @@ mode unchanged.
 ```bash
 # Per-repo mode (back-compat unchanged):
 cd /Users/kimba/Projects/chat-ui
-python3 .agents/skills/adia-ui-kit/scripts/ticket-tool.py next-id   # → next NN
+ticket-tool.py next-id   # → next NN (run from the skill's ticket-tool)
 
 # Central-store mode from a consumer repo:
 cd /Users/kimba/Projects/adia/claims-ui-v2
 ADIA_TICKETS_DIR=/Users/kimba/Projects/chat-ui/.agents/team/tickets \
-  python3 /Users/kimba/Projects/chat-ui/.agents/skills/adia-ui-kit/scripts/ticket-tool.py next-id
+  ticket-tool.py next-id
 # → same NN as the chat-ui call (proves shared registry)
 
 # Smoke /with-css resolution:
@@ -3356,13 +3356,13 @@ This cut adopts it wholesale.
 
 ### New: vendored references
 
-  `references/feedback-authoring.md` — full procedural detail (457 lines)
+  `../feedback-authoring.md` — full procedural detail (457 lines)
   vendored from color-app's `.agents/team/skills/feedback-authoring.md`.
   Five core principles + four-bucket classification + sniff tests +
   AdiaUI-specific pitfalls (the four-symptom binding contract, HTML
   comment apostrophes, Phosphor icon verification, Vite cache,
   Playwright gotchas).
-  `references/response-authoring.md` — companion (388 lines), full
+  `../response-authoring.md` — companion (388 lines), full
   verdict taxonomy + procedure for reviewing FEEDBACK before submission
   + self-review pattern (write the RESPONSE you'd expect upstream to
   write, see if it rejects any claims).
@@ -3411,7 +3411,7 @@ This cut adopts it wholesale.
 
 ### Removed (v2.3.0 artifacts)
 
-  scripts/finalize-ticket.py          (replaced by ticket-tool.py)
+  finalize-ticket.py                  (replaced by ticket-tool.py)
   assets/draft-templates/             (replaced by assets/templates/)
   assets/team-readmes/                (replaced by assets/team-scaffold/)
 
@@ -3447,7 +3447,7 @@ This cut adopts it wholesale.
   front-matter contract), §AutoCapture (trigger taxonomy + negative
   triggers + mid-task UX), §FinalizeTicket (9-gate spec + script
   invocation patterns + revert procedure).
-- **Add `scripts/finalize-ticket.py`** — Python implementation of the
+- **Add `finalize-ticket.py`** — Python implementation of the
   finalize command. Stdlib-only (no PyYAML dep). Three modes:
   `--list` (inventory drafts), `--check <slug>` (run gates dry-run),
   `<slug>` (run gates + promote). Updates `outbox/README.md` registry
@@ -3493,7 +3493,7 @@ This cut adopts it wholesale.
   rename, `0.0.20` and `0.4.0` largest breaks, `0.6.0`/`0.6.1` token
   renames, additive-only version spans) and **defers** to the canonical
   sources:
-  - `docs/MIGRATION GUIDE.md` for version-by-version BREAKING items + diffs.
+  - `.claude/docs/MIGRATION GUIDE.md` for version-by-version BREAKING items + diffs.
   - The dedicated `adia-ui-migration` skill for the mechanical sweep.
   - ADR-0024 for the legacy-shell retirement contract decision.
   Includes an LLM directive forbidding inline migration-command pasting