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

package/skills/adia-ui-kit/references/setup.md

@@ -0,0 +1,652 @@
+# §Setup — Cold-start harness (raw Vite + vanilla JS)
+
+> **Loading note.** Reference bundle extracted from `SKILL.md` per the
+> §LoadingProtocol inversion contract (v2.20.2+). Load via
+> `skill_view(name='adia-ui-kit', file_path='references/setup.md')`
+> when you're scaffolding a new AdiaUI project from scratch (raw Vite
+> + vanilla JS) OR you need the 8-step cold-start checklist with
+> verification gates. Skip if §Setup is already done and the cold-start
+> checkpoint is green (the agent harness should track this).
+
+Everything you need to go from `npm create vite@latest my-app` to working
+AdiaUI components in the browser. All steps below are required — skipping
+any one produces silent failures (blank icons, un-styled components,
+missing tags). Step 0 is a manifest gate that prevents the loudest failure
+class (vite "could not be resolved" / "Are they installed?").
+
+### Step 0 — Verify the manifest (before composing or authoring imports)
+
+Before writing any source code that imports `@adia-ai/*`, confirm the
+manifest declares the deps. The check is one grep and one `node -e`:
+
+```bash
+# (a) Source imports — are there any?
+grep -rEn "from ['\"]@adia-ai/" --include='*.ts' --include='*.js' \
+  --include='*.tsx' --include='*.jsx' --include='*.vue' --include='*.svelte' \
+  src/ 2>/dev/null | wc -l
+
+# (b) Manifest declarations — what's in package.json?
+node -e "const p=require('./package.json'); const deps={...p.dependencies, ...p.devDependencies}; const adia=Object.entries(deps).filter(([k])=>k.startsWith('@adia-ai/')); console.log(JSON.stringify(Object.fromEntries(adia), null, 2))"
+```
+
+| (a) imports | (b) declarations | What to do |
+|---|---|---|
+| 0 | 0 | Fresh repo — proceed to Step 1 |
+| N>0 | M>0 (matching) | Manifest healthy — proceed to compose |
+| **N>0** | **{}** | **HALT — manifest gap (Gap class 0). Surface to operator.** |
+| 0 | M>0 | Imports were removed; sweep declarations next cleanup (low priority) |
+
+If (a)>0 and (b) is empty: **do not author further imports**. The next
+`npm run dev` will halt with "could not be resolved" on the bare
+specifiers — vite's message says "Are they installed?" but they were
+never *declared*. `npm install` (no args) won't fix it — it honors the
+manifest, which says nothing. Surface the gap with the install command
+from Step 1, citing a sibling consumer's reference dep shape (e.g.
+`claims-ui-v8/package.json` for the AdiaUI consumer set).
+
+**Why this is Step 0, not Step 1:** the install in Step 1 *can* be
+done by the agent, but only after the operator has confirmed the dep
+set is intended for this repo. Authoring imports against an empty
+manifest creates source that won't start; surface the gap before that
+happens. See `SKILL.md §GapDetection Gap class 0` for the canonical
+worked example (claims-ui-v9, 2026-05-23).
+
+### Step 0.5 — CDN-only consumption (HTML-first, no bundler)
+
+If the user is building a CodePen demo, a marketing page, a third-party tutorial, or any "drop into static HTML" scenario, **skip the npm install path entirely**. Since v0.6.30, both `@adia-ai/web-components` and `@adia-ai/web-modules` ship pre-flattened + minified bundles via jsdelivr/unpkg. Three tags get you a working page:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.7/dist/web-components.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/shell/admin-shell.min.css">
+<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.7/dist/everything.min.js"></script>
+```
+
+**Version-pin policy:** use `@0.6` (floating-minor) as the default — picks up patch releases automatically while staying inside the v0.6.x lockstep. For an absolute pin substitute `@0.6.32` (current lockstep). Avoid `@latest` (volatile across MAJOR/MINOR bumps). All 9 `@adia-ai/*` packages move together in lockstep; the version you pick must be consistent across both `web-components` and `web-modules` links.
+
+The "everything" bundle (v0.6.32: ~1 MB raw / ~330 KB Brotli) registers **all 100+ primitives + a2ui-runtime + all 17 module-tier shells/parts** (admin-shell + 10 admin-* children, chat-shell + 6 chat-* children, editor-shell + 6 editor-* children, simple-shell + 2 simple-* children, theme-panel, a2ui-root). **Pick ONE JS bundle path** — mixing `everything.min.js` with a separate `web-components.min.js` causes `customElements.define` to throw dup-name errors.
+
+> **⚠️ v0.6.32 bundle correctness milestone.** Pre-v0.6.32, `everything.min.js` was shells-only (~750 KB, primitives missing) — using `<button-ui>` / `<card-ui>` / etc. would silently fail to upgrade. v0.6.32 is the first version where the bundle actually registers all 100+ primitives. **Pin to `@0.6.32` or floating `@0.6`** — do **not** pin to `@0.6.31` or earlier or you'll get blank pages where primitives should be.
+
+> **⚠️ icons-manifest.js requirement (v0.6.32+).** Icons rendered via `<*-ui icon="…">` are loaded lazily from `@phosphor-icons/core` at runtime, gated by `dist/icons-manifest.js` (256 KB, 1512 regular icons + 5 weights). This manifest is **bundled into `everything.min.js`** but must be present at `@adia-ai/web-components@0.7.13+/dist/icons-manifest.js` for the standalone `web-components.min.js` path. Pre-v0.6.32 the manifest was missing from the published tarball → icons silently rendered as blank.
+
+Choice tree:
+
+| Use case | Bundle path |
+|---|---|
+| CodePen / marketing / drop-into-HTML | `@adia-ai/web-modules@0.7/dist/everything.min.js` (single file, all 100+ primitives + 17 shells/parts + icon manifest baked in) |
+| Primitives only, no shells | `@adia-ai/web-components@0.7/dist/web-components.min.js` (must be paired with `dist/icons-manifest.js` co-load) |
+| One specific shell + primitives | `web-components.min.js` + ONE `dist/<cluster>/<shell>.min.js` (e.g. `@adia-ai/web-modules@0.7/dist/shell/admin-shell.min.js`, `dist/chat/chat-shell.min.js`, `dist/editor/editor-shell.min.js`, `dist/simple/simple-shell.min.js`) |
+| Real app with Vite/webpack | **Don't use these bundles** — `npm install` + tree-shake is tighter |
+
+Then skip to authoring — Steps 1-8 below are for npm-installed consumers; the CDN path doesn't need them.
+
+Full CDN reference: [ui-kit.exe.xyz/site/getting-started/cdn-usage](https://ui-kit.exe.xyz/site/getting-started/cdn-usage).
+
+---
+
+### Step 1 — Install packages
+
+```bash
+npm install @adia-ai/web-components @adia-ai/web-modules @phosphor-icons/core
+```
+
+- `@adia-ai/web-components` — 95 `*-ui` primitive elements
+- `@adia-ai/web-modules` — composite shells (admin / chat / editor / simple) **plus the A2UI render surface `<canvas-ui>` depends on**
+- `@phosphor-icons/core` — SVG icon assets (required for the icon loader)
+
+> **`@adia-ai/web-modules` is needed for more than shells.** The default
+> `@adia-ai/web-components` barrel (`import '@adia-ai/web-components'`, Step 2)
+> registers `<canvas-ui>`, the A2UI render surface, which needs the renderer
+> (`a2ui-root`) from `@adia-ai/web-modules`. On `@adia-ai/web-components`
+> **≤ 0.6.43** this was a *static* cross-package import, so the barrel failed
+> to build for a primitives-only app that omitted `web-modules` — a hard
+> Vite/rolldown `UNRESOLVED_IMPORT … web-modules/runtime/a2ui-root` at first
+> `npm run dev` (FEEDBACK-81). **v0.6.44 decouples it** (`<canvas-ui>`
+> loads the renderer lazily + guarded), so a true primitives-only app may then
+> omit `web-modules`. **Until you're on the fixed build, keep all three
+> installed** — which Step 1 already does. Do **not** trim `web-modules`
+> (Step 6) on ≤ 0.6.43 unless you also drop `canvas` from your imports.
+
+### Step 2 — Wire the entry file
+
+Replace the contents of `src/main.js` (or `main.ts`) with:
+
+```js
+// ── 1. Design tokens + component CSS ──
+import '@adia-ai/web-components/css';    // all primitive CSS
+
+// ── 2. Register all *-ui tags ──
+import '@adia-ai/web-components';        // side-effect: defines 95 custom elements
+
+// ── 3. Shell CSS (REQUIRED when using admin / chat / editor / simple) ──
+// Import the shell CSS for every shell tag you use — `<admin-shell>` etc.
+// **do not self-import their layout CSS**, so omitting these imports
+// produces an unstyled stacked-divs layout with no error. The package
+// exports map uses `./<cluster>/*.css` (resolves to `./<cluster>/*/*.css`):
+//   import '@adia-ai/web-modules/shell/admin-shell.css';
+//   import '@adia-ai/web-modules/chat/chat-shell.css';
+//   import '@adia-ai/web-modules/editor/editor-shell.css';
+//   import '@adia-ai/web-modules/simple/simple-shell.css';
+// (Pitfall: the tag is `<admin-shell>`, not `<app-shell>` — there is no
+//  umbrella `app-shell` tag in `@adia-ai/web-modules`.)
+
+// ── 4. Register shells via per-cluster subpaths ──
+// **Do NOT** use the full `@adia-ai/web-modules` barrel — at v0.6.7+ it
+// re-exports broken in-repo absolute paths from `chat/chat-shell.js`
+// (e.g. `import '/packages/web-components/components/code/code.js'`)
+// that fail in any consumer Vite build. Import only the clean
+// per-cluster subpaths you actually need:
+import '@adia-ai/web-modules/shell';       // registers admin-shell + children
+// import '@adia-ai/web-modules/chat';     // registers chat-shell (if needed)
+// import '@adia-ai/web-modules/editor';   // registers editor-shell
+// import '@adia-ai/web-modules/simple';   // registers simple-shell
+
+// ── 5. Icon loader (REQUIRED — see step 3 below) ──
+import { installIconLoadersForRegistered } from '@adia-ai/web-components/core/icons';
+
+// Vite glob — relative path from main.js (works in Vite 7 rollup AND Vite 8
+// rolldown). The `@`-scoped form (`@phosphor-icons/core/assets/regular/*.svg`)
+// works in Vite 7 but is REJECTED by Vite 8 rolldown ("Invalid glob — must
+// start with '/' or './'"). The relative form is portable across both.
+//
+// IMPORTANT: wrap the globs in a per-weight map (`{ regular, bold, … }`).
+// AdiaUI primitives stamp icons at MULTIPLE weights — e.g. `<select-ui multiple>`
+// stamps the chip-remove glyph as `<icon-ui name="x" weight="bold">`. A
+// regular-only map leaves bold lookups unresolved (blank icon + `[icon-ui] …
+// weight="bold" not found`). Phosphor names non-regular files
+// `<name>-<weight>.svg` under `assets/<weight>/`; load the weights your
+// primitives use — `bold` is the common one (a few stamp `fill`/`thin`).
+// Passing a flat glob (no weight key) is auto-promoted to `regular` in
+// v0.6.15+ with a one-time warn, and silently fails pre-v0.6.15.
+installIconLoadersForRegistered({
+  regular: import.meta.glob(
+    '../node_modules/@phosphor-icons/core/assets/regular/*.svg',
+    { query: '?raw', import: 'default', eager: true }
+  ),
+  bold: import.meta.glob(
+    '../node_modules/@phosphor-icons/core/assets/bold/*.svg',
+    { query: '?raw', import: 'default', eager: true }
+  ),
+});
+```
+
+**CSS order matters:** tokens + component CSS before any markup renders.
+**Icon loader must run after `import '@adia-ai/web-components'`** —
+`installIconLoadersForRegistered` reads `static requiredIcons` from
+registered elements, so the elements must be defined first.
+
+### Step 3 — Icon loader in depth
+
+Icons in AdiaUI are Phosphor SVGs loaded on demand. Components internally
+call `getIcon(name)` — if no loader is installed, `getIcon` returns an
+empty string and the icon slot is silently blank. This is the most common
+setup mistake.
+
+**`installIconLoadersForRegistered` (recommended):**
+
+Inspects `static requiredIcons` on every registered custom element class
+and installs loaders only for the icons those elements actually use. No
+manual list to maintain — add new components, icon set updates automatically.
+
+```js
+import { installIconLoadersForRegistered } from '@adia-ai/web-components/core/icons';
+
+// Vite glob — package-relative path (NOT /node_modules/...)
+// Wrap the globs in a per-weight map. Load every weight your primitives stamp —
+// `bold` is the common non-regular case (`<select-ui multiple>` chip-remove x),
+// with a few `fill`/`thin`. Phosphor files: `assets/<weight>/<name>-<weight>.svg`.
+// Flat globs (no weight key) are auto-promoted to `regular` in v0.6.15+ (one-time
+// warn) but silently fail on prior versions.
+installIconLoadersForRegistered({
+  regular: import.meta.glob(
+    '../node_modules/@phosphor-icons/core/assets/regular/*.svg',
+    { query: '?raw', import: 'default', eager: true }
+  ),
+  bold: import.meta.glob(
+    '../node_modules/@phosphor-icons/core/assets/bold/*.svg',
+    { query: '?raw', import: 'default', eager: true }
+  ),
+});
+```
+
+> **Pitfall: `@`-scoped vs relative globs (Vite 7 → Vite 8 break).**
+> Pre-v0.6.7 docs (and AdiaUI's own monorepo source) used the
+> `@`-scoped form `'@phosphor-icons/core/assets/regular/*.svg'`. That
+> form works in Vite 7 (rollup-based) but is **rejected by Vite 8
+> rolldown** with `Invalid glob: must start with '/' or './'`. The
+> portable form — `'../node_modules/@phosphor-icons/core/assets/regular/*.svg'`,
+> a path relative to the consuming file — works in both Vite 7 and
+> Vite 8. Use the relative form everywhere unless you've explicitly
+> pinned to Vite 7. AdiaUI's own monorepo source still uses
+> `/node_modules/...` (root-absolute); **do not copy that** into a
+> consumer project — root-absolute globs return empty in external
+> projects and all icons render blank.
+
+**Manual / minimal bundle (if you know exactly which icons you need):**
+
+```js
+import { installIconLoaders } from '@adia-ai/web-components/core/icons';
+
+installIconLoaders({
+  regular: import.meta.glob(
+    '../node_modules/@phosphor-icons/core/assets/regular/{caret-up-down,x,check,warning}.svg',
+    { query: '?raw', import: 'default', eager: true }
+  ),
+});
+```
+
+> **Pitfall: static glob brace-lists.** Vite resolves glob patterns at
+> build time, not runtime. If you add a component later that needs an icon
+> not in your brace-list, it renders blank with no error. Use
+> `installIconLoadersForRegistered` to avoid maintaining this list.
+
+**Single icon (framework consumers, no bundler glob):**
+
+```js
+import { registerIcon } from '@adia-ai/web-components/core/icons';
+import caretSvg from '@phosphor-icons/core/assets/regular/caret-up-down.svg?raw';
+registerIcon('caret-up-down', caretSvg);
+```
+
+### Step 4 — Minimal `index.html`
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>My App</title>
+</head>
+<body>
+  <card-ui>
+    <header slot="header">
+      <span slot="heading">Hello AdiaUI</span>
+    </header>
+    <section>
+      <col-ui gap="md">
+        <field-ui label="Name">
+          <input-ui placeholder="Your name"></input-ui>
+        </field-ui>
+        <button-ui text="Submit" variant="primary"></button-ui>
+      </col-ui>
+    </section>
+  </card-ui>
+
+  <script type="module" src="/src/main.js"></script>
+</body>
+</html>
+```
+
+> **Shell app?** If your app uses `<admin-shell>`, `<chat-shell>`,
+> `<editor-shell>`, or `<simple-shell>`, do **NOT** author shell markup
+> from memory in this step. Load [`patterns-shells.md`](patterns-shells.md)
+> BEFORE writing any shell element in `index.html` — the pre-author bundle
+> gate applies here exactly as it does during §Compose. The component yaml
+> sidecars (e.g.
+> `node_modules/@adia-ai/web-modules/shell/admin-sidebar/admin-sidebar.yaml`)
+> are also authoritative for slot names and attribute values. Authoring
+> from memory at Step 4 produces silent failures — e.g. `slot="sidebar"`
+> on `<admin-sidebar>` (the substrate queries `[slot="leading"]`; mismatched
+> slot fails the lookup and breaks toggle/resize with no console output).
+> See FEEDBACK-56 (claims-ui-v10 cold-start, 2026-05-23) for the canonical
+> 7-error trace this gate prevents.
+
+### Step 5 — Vite config (minimal, external consumer)
+
+A raw `npm create vite@latest` project has a working `vite.config.js` by
+default. For AdiaUI no special aliases are needed — everything resolves
+via the package `exports` map.
+
+> **⚠️ 0.6.44 only — `optimizeDeps.exclude` needed to boot.** On
+> `@adia-ai/web-components@0.7.13`, the default barrel registers `<canvas-ui>`,
+> whose lazy A2UI-renderer import used a *relative* cross-package path that Vite
+> can't resolve once it pre-bundles `web-components` into `node_modules/.vite/deps/`
+> — `npm run dev` fails with a `[vite:import-analysis] Failed to resolve import
+> "…/web-modules/runtime/a2ui-root/a2ui-root.js"` overlay + blank page (FEEDBACK-85).
+> Until you're on the fix, add:
+> ```ts
+> // vite.config.ts
+> export default defineConfig({
+>   optimizeDeps: { exclude: ['@adia-ai/web-components', '@adia-ai/web-modules'] },
+> });
+> ```
+> **0.6.45+ switches `<canvas-ui>` to a bare specifier — this exclude is then
+> unnecessary; remove it.**
+
+Only add a proxy if your app calls an LLM backend:
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': {
+        target: 'http://localhost:3456',
+        changeOrigin: true,
+      },
+    },
+  },
+});
+```
+
+> **Do not copy the in-repo Vite aliases** (`@core`, `@components`, `@llm`,
+> `@styles`). Those resolve paths inside the AdiaUI monorepo source tree.
+> External consumers import from `@adia-ai/web-components` — the package
+> exports map handles resolution.
+
+### Step 6 — Component registration (advanced)
+
+The barrel import in step 2 auto-registers all 95 elements. For fine-grained
+control:
+
+**Per-component** (tree-shaking):
+
+```js
+import '@adia-ai/web-components/components/button';
+import '@adia-ai/web-components/components/button.css';
+import '@adia-ai/web-components/components/card';
+import '@adia-ai/web-components/components/card.css';
+```
+
+**Conflict-safe** (multiple packages sharing a page):
+
+```js
+import { defineIfFree } from '@adia-ai/web-components/core';
+defineIfFree('button-ui', MyExtendedButton); // no-op if already defined
+```
+
+**Class-only** (test isolation / subclassing, no auto-register):
+
+```js
+import { UISlider } from '@adia-ai/web-components/components/slider/class';
+class MySlider extends UISlider { /* … */ }
+customElements.define('my-slider', MySlider);
+```
+
+### Step 7 — TypeScript
+
+Zero config since v0.6.0 — `npm install` and types resolve automatically
+via `exports.types` in each package.
+
+```ts
+import type { UIButton } from '@adia-ai/web-components';
+const btn = document.querySelector('button-ui') as UIButton;
+btn.text = 'Click'; // typed string
+```
+
+If your `tsconfig.json` predates `"moduleResolution": "bundler"`:
+
+```json
+{ "compilerOptions": { "moduleResolution": "bundler" } }
+```
+
+A2UI message/component types:
+
+```ts
+import type { A2UIMessage, A2UIComponent } from '@adia-ai/a2ui-runtime/schema';
+```
+
+### Step 8 — Agent harness bootstrap (`AGENTS.md` + `CLAUDE.md`)
+
+If the consumer project has **no agent-entry file** (no `AGENTS.md`,
+no `CLAUDE.md`, no `.cursor/rules`, no `WARP.md` etc.), create them as
+part of cold-start. Future agent sessions (Claude Code, Cursor,
+Windsurf, Hermes, OpenAI Codex, any harness that auto-loads project
+context) need an entry point that names which skill to defer to and
+records project-specific decisions.
+
+**Decision branch — pre-existing `AGENTS.md`:**
+
+If `AGENTS.md` already exists when you reach this step, do NOT silently
+skip. Branch:
+
+1. **Check whether it contains a `## Skill` section pointing at this
+   skill** (grep for `adia-ui-kit` in the file). If yes — it was
+   previously scaffolded; the bootstrap is already in place. Skip.
+2. **If no `## Skill` section** (the common case for a hand-rolled file
+   from an earlier session): **rewrite from the template**, preserving
+   any project-specific content (AdiaUI quirks, known bugs, decisions)
+   by moving it into the template's `## Project-specific decisions`
+   block. **Do not append** — the template structure relies on section
+   ordering, and appending produces duplicate-section drift.
+3. **Note the rewrite in your session summary** so the operator can
+   audit which sections moved where.
+
+The rewrite is the right answer because `AGENTS.md` without a `## Skill`
+pointer means every future session starts cold — no skill auto-load, no
+ticket pipeline commands, no install verification shortcut. Closes
+claims-ui-v2 FB-03.
+
+**The pattern:**
+
+```
+<project-root>/
+├── CLAUDE.md          # 1-line pointer: `@AGENTS.md`
+├── AGENTS.md          # canonical agent contract
+└── .agents/
+    ├── skills/        # optional: vendored project-specific skills
+    └── team/          # optional: ticket pipeline (drafts/outbox/inbox/archive)
+```
+
+**`CLAUDE.md`** is a single line that points at `AGENTS.md`:
+
+```
+@AGENTS.md
+```
+
+Claude Code, Cursor, and several other harnesses honor the `@<file>`
+include syntax — they pull in `AGENTS.md` content as if it were
+written inline. This avoids duplicating content across multiple
+harness-specific files. Other harnesses (Hermes, OpenAI Codex,
+WARP, etc.) read `AGENTS.md` directly per the
+[`AGENTS.md` convention](https://agents.md). Two files, one
+canonical source.
+
+**`AGENTS.md`** is the consumer's agent contract. Scaffold from
+the template at `assets/templates/AGENTS.template.md` in this
+skill. Replace the `{{PLACEHOLDER}}` markers:
+
+| Placeholder | Replace with |
+|---|---|
+| `{{PROJECT_NAME}}` | the consumer project's name (e.g. `Claims UI`) |
+| `{{PROJECT_NAME_KEBAB}}` | kebab-case form for ticket filenames (e.g. `claims-ui`) |
+| `{{PROJECT_DESCRIPTION_ONE_LINER}}` | one-sentence description |
+| `{{STACK}}` | e.g. "Vite + TypeScript + `@adia-ai/web-components`" |
+| `{{SKILL_PATH}}` | absolute path to this skill's SKILL.md |
+| `{{SKILL_PATH_DIR}}` | absolute path to the skill folder (for `scripts/` references) |
+| `{{SKILL_VERSION}}` | optional pin (e.g. `2.8.0`) — leave blank if floating |
+| `{{SKILL_COMMIT}}` | optional commit SHA — leave blank if floating |
+| `{{ADIA_AI_VERSION}}` | installed `@adia-ai/*` version (e.g. `0.6.32`) |
+| `{{PROJECT_SPECIFIC_DECISIONS}}` | project-specific choices (rendering mode, theme posture, data layer, etc.) |
+| `{{DATE}}` | YYYY-MM-DD of last review |
+
+**Why this works:**
+
+- Future agent sessions get loaded with `AGENTS.md` before any
+  context-gathering steps — they don't need to be told "go read
+  the AdiaUI skill". The pointer is in their auto-loaded layer.
+- Project-specific decisions live in `AGENTS.md`, not in the
+  skill — the skill stays portable; the project keeps its own
+  conventions findable.
+- The skill is loaded by **path reference**, not by copy. When the
+  skill updates, every consumer's agent sessions pick up the new
+  procedures automatically.
+- The `@AGENTS.md` pointer pattern means harness-specific files
+  (`CLAUDE.md`, `.cursor/rules`, `WARP.md`, etc.) stay tiny — one
+  line. No drift across harnesses.
+
+**Scaffold command** (from your consumer project root):
+
+```bash
+# Replace SKILL_DIR with your actual skill path
+SKILL_DIR=/Users/<you>/Projects/gen-ui-kit/.agents/skills/adia-ui-kit
+
+cp "$SKILL_DIR/assets/templates/AGENTS.template.md" AGENTS.md
+cp "$SKILL_DIR/assets/templates/CLAUDE.template.md" CLAUDE.md
+
+# Then edit AGENTS.md to fill in the placeholders.
+```
+
+**Pitfall: do NOT vendor the skill into the consumer project.** Some
+agents will try to copy the whole `adia-ui-kit/` folder into the
+consumer's `.agents/skills/`. That forks the skill — updates won't
+propagate. The right shape is **path reference** from `AGENTS.md`,
+not vendoring.
+
+**Pitfall: do NOT pin the skill version in `AGENTS.md`** unless the
+consumer explicitly wants reproducibility-over-currency. The skill's
+versioning is conservative (PATCH for doc fixes, MINOR for new
+sections, MAJOR for shape changes); floating reference is the
+default sensible choice.
+
+**If multiple harnesses are in use** (e.g. consumer team uses Claude
+Code AND Cursor AND Hermes):
+
+```
+<project-root>/
+├── AGENTS.md             # canonical
+├── CLAUDE.md             # `@AGENTS.md`
+├── .cursor/rules         # `@AGENTS.md` (Cursor convention varies; check docs)
+└── WARP.md               # `@AGENTS.md`
+```
+
+Each harness-specific file is a single-line pointer. The contract
+lives in `AGENTS.md` once.
+
+### §Setup checklist
+
+- [ ] `@phosphor-icons/core` in `package.json` dependencies
+- [ ] `@adia-ai/web-modules` installed — needed for shells **and** for
+      `<canvas-ui>` (the default `web-components` barrel registers it). On
+      `web-components ≤ 0.6.43`, omitting `web-modules` breaks the build even
+      with zero shell tags (FEEDBACK-81); v0.6.44+ lazy-loads it so a
+      true primitives-only app may then omit it.
+- [ ] CSS imported before markup renders (`@adia-ai/web-components/css`)
+- [ ] Shell CSS imported for each shell tag used (e.g.
+      `@adia-ai/web-modules/shell/admin-shell.css`) — required, not optional.
+      **Use the single-segment form** (one segment after `/shell/`): the
+      exports map wildcard `./shell/*.css → ./shell/*/*.css` resolves it
+      internally. The three-segment form
+      (`@adia-ai/web-modules/shell/admin-shell/admin-shell.css`) mirrors
+      the on-disk path but is blocked by the exports map at Vite 8 /
+      Rolldown build time with no correction hint.
+- [ ] Per-cluster shell registration import used (e.g.
+      `@adia-ai/web-modules/shell`), NOT the full `@adia-ai/web-modules`
+      barrel (broken at v0.6.7+ — chat-shell.js has in-repo absolute paths)
+- [ ] **Cluster barrel, not per-component path.** `@adia-ai/web-modules/shell`
+      (the cluster barrel, `shell/index.js`) registers three custom element
+      classes: `AdminShell`, `AdminSidebar`, and `AdminCommand`. The
+      superficially similar `@adia-ai/web-modules/shell/admin-shell`
+      (per-component path, `shell/admin-shell/admin-shell.js`) registers
+      **only `AdminShell`**. The CSS-only bespoke children (`admin-content`,
+      `admin-topbar`, `admin-page`, etc.) need no JS registration, but
+      `AdminSidebar` does — it owns the `[data-resize]` drag-handle wiring
+      and the `.toggle()` / `.collapse()` / `.expand()` public API that
+      `AdminShell` calls to forward `[data-sidebar-toggle]` clicks.
+      **Symptom:** the sidebar renders correctly (CSS targets by tag name)
+      but the toggle button does nothing and the resize handle is inert —
+      `AdminShell` calls `sidebar.toggle()` on an unregistered element and
+      silently fails (no error). The path looks more tree-shakeable than the
+      cluster barrel, which is why it's a plausible mistake; resist it.
+      *claims-ui regression 2026-05-23: introduced when a consumer prompt
+      specified `shell/admin-shell` for "shell primitives registration"; the
+      sidebar rendered correctly but toggle/resize were silently broken until
+      the user reported the issue.*
+- [ ] If `<admin-sidebar resizable>` is used: a `<div data-resize></div>`
+      direct child is present — without it `resizable` is a silent no-op
+      (no drag handle, no warning). Unlike `collapsible`, `resizable`
+      requires this author-supplied handle child.
+- [ ] Barrel import runs before `installIconLoadersForRegistered`
+- [ ] Icon loader glob uses `'../node_modules/@phosphor-icons/…'`
+      (relative form) — `'@phosphor-icons/…'` is rejected by Vite 8 rolldown
+- [ ] Icon loader map includes the **`bold`** weight (not just `regular`) —
+      primitives stamp bold glyphs (e.g. `<select-ui multiple>` chip-remove `x`);
+      a regular-only map renders those blank + warns. Add `fill`/`thin` too if a
+      primitive you use needs them.
+- [ ] No in-repo Vite aliases copied (`@core`, `@components`, `@llm`, `@styles`)
+- [ ] (0.6.44 only) `optimizeDeps.exclude: ['@adia-ai/web-components', '@adia-ai/web-modules']`
+      in `vite.config.ts` — without it the 0.6.44 `<canvas-ui>` relative-import breaks
+      Vite dep pre-bundling and the app won't boot (FEEDBACK-85). Remove on 0.6.45+.
+- [ ] Ran `scripts/check-adia-versions.py` from your consumer root —
+      9-package lockstep aligned + installed ≥ latest published (see
+      §VersionCheck below)
+- [ ] (Dev-only) If linking to `chat-ui` sources via `file:`, all 9
+      `@adia-ai/*` packages are linked (not a subset) — see §LocalLink
+- [ ] (Optional) If using a shell, decide explicit-import vs `/with-css`
+      opt-in path — see §CSSPolicy "Opt-in `/with-css` variants"
+- [ ] Agent harness bootstrap created — `AGENTS.md` + `CLAUDE.md`
+      pointer at project root (only if the project had no agent-entry
+      file). Scaffold from `assets/templates/AGENTS.template.md` +
+      `CLAUDE.template.md`; see §Setup Step 8 above.
+
+---
+
+### Verify the install matches what the skill describes — see §VersionCheck (canonical heading in SKILL.md)
+
+> The §VersionCheck procedure was promoted back to SKILL.md as an H2
+> anchor (v2.20.2 follow-up) so the broken-section-reference check
+> resolves cleanly. The canonical body lives in SKILL.md §VersionCheck.
+> The text below is the historical extract — kept for reference but
+> not the source of truth.
+
+**Why this gate exists.** The 9 `@adia-ai/*` packages ship in lockstep,
+and skill guidance is version-sensitive (e.g. §F-014/F-015 docs the
+bare-barrel bug that only affects v0.6.7 consumers; v0.6.8+ fixes it).
+Before trusting a stale install, run:
+
+```bash
+scripts/check-adia-versions.py
+```
+
+(Path relative to the consumer project that has this skill installed.
+If running from another consumer, pass `--root /path/to/consumer`.)
+
+The script reports three sources side-by-side: **installed**
+(node_modules), **declared** (package.json), **latest** (npm registry).
+It classifies drift and exits non-zero when something needs attention.
+
+**Exit codes**
+
+- `0` — install is clean: lockstep aligned, declarations match installs,
+  and installed ≥ latest published (or you used `--offline`).
+- `1` — drift detected. The text output names every package + suggests
+  the fix (`npm install @adia-ai/X@latest`, `npm install`, or wipe +
+  reinstall to repair split lockstep).
+- `2` — unrecoverable (no `package.json` or no `node_modules` at root).
+
+**Status legend**
+
+| Marker | Meaning | Fix |
+|---|---|---|
+| ✓ ok | installed == declared, matches latest | — |
+| ⚠ stale | installed < latest published | `npm install @adia-ai/<pkg>@latest` |
+| ⚠ split | lockstep broken — packages disagree on version | wipe `node_modules` + lockfile, reinstall |
+| ⚠ undeclared | user-facing package installed but not in package.json | add to `dependencies` |
+| ⚠ uninstalled | declared but missing from node_modules | `npm install` |
+| ⓘ ahead | installed > latest published (dev cut / local tarball) | informational, not an error |
+
+**Flags**
+
+- `--offline` — skip `npm view` (no network). Still verifies lockstep
+  + declared vs. installed; just can't tell you about staleness.
+- `--json` — machine-readable for agent harnesses.
+- `--root <path>` — explicit consumer root (default: cwd).
+
+**When to run it**
+
+- Once at the start of any new project work (cold-start gate).
+- After any `npm install` or `npm update` involving `@adia-ai/*`.
+- Before filing a feedback ticket — version coherence is required
+  evidence (see §FeedbackDiscipline principle 4 "verify before
+  claiming").
+- When a piece of skill guidance contradicts your install (the script
+  tells you which side is stale).
+
+**Monorepo-root behavior.** The script auto-detects the `@adia-ai/*`
+source monorepo via the `workspaces` field and suppresses "undeclared"
+warnings there (workspaces aren't external deps). The "ⓘ ahead" status
+is also expected in the monorepo when you've bumped sources but not yet
+published.