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

package/skills/adia-ui-kit/evals/routing-corpus.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-ui-kit bundled routing corpus",
+  "version": "1.0.0",
+  "purpose": "Portable routing-accuracy corpus for adia-ui-kit. Each phrase declares whether the kit SHOULD be the routing target. Scored by `scripts/run-skill-evals.mjs` against the kit's description + trigger frontmatter — approximates how the harness routes intent. Per REFACTOR-SPEC P3.",
+  "scoring_notes": "The bundled scorer uses TF-IDF-style token overlap between the phrase and the kit's frontmatter. This is a HEURISTIC eval — the real harness routing may differ (especially for ambiguous phrases). Treat misroutes as a signal to tighten the kit's description / triggers, not as ground truth. Substrate runs the cross-skill version at `scripts/skills/run-skill-evals.mjs`; the bundled runner restricts evaluation to the kit alone (consumer repos don't have the sibling seniors available to compare against).",
+  "license": "internal",
+  "scope": "kit-only routing — does this phrase activate adia-ui-kit?",
+
+  "minimums_per_spec": {
+    "trigger_phrases": 10,
+    "adversarial_phrases": 5,
+    "adversarial_fraction": "33%"
+  },
+
+  "phrases": [
+    {
+      "id": "kit-01",
+      "phrase": "build a user profile card with avatar and edit actions",
+      "should_route_to_kit": true,
+      "rationale": "Canonical composition task — user profile card is a kit recipe."
+    },
+    {
+      "id": "kit-02",
+      "phrase": "generate UI for a pricing page with 3 tiers",
+      "should_route_to_kit": true,
+      "rationale": "Generative UI composition with specific layout intent."
+    },
+    {
+      "id": "kit-03",
+      "phrase": "compose a settings page with form fields and a save button",
+      "should_route_to_kit": true,
+      "rationale": "Multi-primitive composition — settings page is a kit recipe."
+    },
+    {
+      "id": "kit-04",
+      "phrase": "create an FAQ page with expandable questions",
+      "should_route_to_kit": true,
+      "rationale": "Page composition with accordion-ui pattern."
+    },
+    {
+      "id": "kit-05",
+      "phrase": "build a metrics dashboard with KPI stat cards",
+      "should_route_to_kit": true,
+      "rationale": "Dashboard composition — admin-shell + stat-ui pattern."
+    },
+    {
+      "id": "kit-06",
+      "phrase": "use AdiaUI primitives to compose a login screen",
+      "should_route_to_kit": true,
+      "rationale": "Explicit AdiaUI mention + auth-flow composition."
+    },
+    {
+      "id": "kit-07",
+      "phrase": "what's the recipe for a hero section with a CTA?",
+      "should_route_to_kit": true,
+      "rationale": "Recipe lookup — kit owns composition recipes."
+    },
+    {
+      "id": "kit-08",
+      "phrase": "compose this Figma mock into AdiaUI components",
+      "should_route_to_kit": true,
+      "rationale": "Mock-to-component translation — kit's primary mode."
+    },
+    {
+      "id": "kit-09",
+      "phrase": "build a navigation pattern with sidebar and main content",
+      "should_route_to_kit": true,
+      "rationale": "Layout pattern — admin-shell composition."
+    },
+    {
+      "id": "kit-10",
+      "phrase": "generate a chat interface from this user intent",
+      "should_route_to_kit": true,
+      "rationale": "Chat-shell composition — kit's chat cluster recipes."
+    },
+
+    {
+      "id": "kit-adv-01",
+      "phrase": "add a new component to packages/web-components/",
+      "should_route_to_kit": false,
+      "expected_alternative": "adia-ui-authoring",
+      "rationale": "Authoring NEW primitives — explicitly NEG-clause in kit description."
+    },
+    {
+      "id": "kit-adv-02",
+      "phrase": "cut a release of v0.6.34",
+      "should_route_to_kit": false,
+      "expected_alternative": "adia-ui-release",
+      "rationale": "Release cycle — not kit's domain."
+    },
+    {
+      "id": "kit-adv-03",
+      "phrase": "diagnose why zettel composition coverage dropped on the eval",
+      "should_route_to_kit": false,
+      "expected_alternative": "adia-ui-a2ui",
+      "rationale": "A2UI pipeline internals — not kit composition."
+    },
+    {
+      "id": "kit-adv-04",
+      "phrase": "explain how React useEffect hooks work",
+      "should_route_to_kit": false,
+      "expected_alternative": null,
+      "rationale": "Generic framework knowledge — kit's NEG clause covers 'unrelated frameworks'. Risk: kit's trigger block contains 'React, useEffect' as routing hints for AdiaUI-in-React projects, which has historically over-activated kit on bare React questions (documented as inherent-scorer-limit negative-02)."
+    },
+    {
+      "id": "kit-adv-05",
+      "phrase": "compose this",
+      "should_route_to_kit": false,
+      "expected_alternative": null,
+      "rationale": "Bare 'compose this' with no AdiaUI context — explicitly NEG-clause in kit description. Should not activate on the trigger word alone."
+    }
+  ],
+
+  "evaluator_notes": {
+    "current_state": "This corpus is scored by `scripts/run-skill-evals.mjs` (bundled in v2.30.0) against the kit's own description + trigger fields. The runner emits a routing F1 number; PASS for trigger-phrases means kit scores ≥ MIN_SCORE_THRESHOLD; PASS for adversarial-phrases means kit scores < MIN_SCORE_THRESHOLD (i.e. doesn't activate).",
+    "cross-skill_comparison": "When run inside the chat-ui substrate (where all 5 senior skills are present), the bundled runner falls through to the substrate's `scripts/skills/run-skill-evals.mjs` cross-skill comparison for higher fidelity. When run in a consumer repo (where only adia-ui-kit ships), it scores kit-only.",
+    "promotion_criteria": "Promote to a CI gate (warn → hard-fail) when the kit alone scores F1 ≥ 0.85 on this corpus across 3+ consecutive cycles. Until then, the corpus is for VISIBILITY (per REFACTOR-SPEC §10 OQ2).",
+    "review_cadence": "Every senior-skill quarterly checkpoint (per AGENTS.md BORIS §B3). Add 1+ new trigger / adversarial phrase per checkpoint reflecting newly-observed routing failure modes. Current cases cover: canonical composition (10), authoring-NEG (1), release-NEG (1), a2ui-NEG (1), bare-framework (1), bare-verb (1)."
+  }
+}

package/skills/adia-ui-kit/evals/teach-routing-cases.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "adia-ui-kit teach-routing behavioral corpus",
+  "version": "1.0.0",
+  "purpose": "Behavioral eval for the §Teach decision tree mechanization. Each case names a knowledge-payload + the expected branch (A–G) the script should classify it into. Per REFACTOR-SPEC P4.",
+  "scoring_notes": "Scored by `scripts/teach-route.mjs --eval=...`. Pass = branch matches expected_branch. Confidence (high/medium/low) is reported but doesn't affect pass/fail — track confidence trends across releases to spot vocabulary drift.",
+  "license": "internal",
+
+  "minimums_per_spec": {
+    "trigger_cases_per_branch": 1,
+    "total_cases": 7,
+    "branches_covered": "A-G all 7"
+  },
+
+  "cases": [
+    {
+      "id": "branch-A-01",
+      "payload": "new slot on calendar-picker-ui for trailing actions",
+      "expected_branch": "A",
+      "expected_landing_pattern": "packages/web-components/components/calendar-picker/",
+      "rationale": "Per-component slot addition — substrate yaml."
+    },
+    {
+      "id": "branch-A-02",
+      "payload": "add a new a2ui.rule to the table-toolbar-ui yaml clarifying when [sticky] is allowed",
+      "expected_branch": "A",
+      "expected_landing_pattern": "packages/web-components/components/table-toolbar/",
+      "rationale": "a2ui.rule = per-component contract; lives in yaml SoT."
+    },
+
+    {
+      "id": "branch-B-01",
+      "payload": "add a recipe showing how to compose an editor-shell inside admin-page-body for the nested-shell case",
+      "expected_branch": "B",
+      "expected_landing_pattern": "references/patterns-shells.md",
+      "rationale": "Cross-component composition recipe with shell focus — patterns-shells."
+    },
+    {
+      "id": "branch-B-02",
+      "payload": "recipe for wiring a chart-ui with optimistic-update controllers and signal subscriptions",
+      "expected_branch": "B",
+      "expected_landing_pattern": "references/patterns-",
+      "rationale": "Cross-component recipe — could land in patterns-data or patterns-wiring depending on gravity."
+    },
+
+    {
+      "id": "branch-C-01",
+      "payload": "end-to-end auth flow with sign-in, OTP verification, forgot-password reset, and the registration wizard",
+      "expected_branch": "C",
+      "expected_landing_pattern": "references/flows-auth.md",
+      "rationale": "Multi-page user journey covering auth — flows-auth."
+    },
+
+    {
+      "id": "branch-D-01",
+      "payload": "we need a new reasoning methodology: before any composition, decompose the user intent into named decisions with required signals (the DecisionModel posture from REFACTOR-SPEC P5)",
+      "expected_branch": "D",
+      "expected_landing_pattern": "SKILL.md inline",
+      "rationale": "Methodology / posture shift that shapes every other section — SKILL.md inline."
+    },
+
+    {
+      "id": "branch-E-01",
+      "payload": "new audit script that detects orphan components in agent output (DecisionModel trace audit per REFACTOR-SPEC P5(b))",
+      "expected_branch": "E",
+      "expected_landing_pattern": "scripts/",
+      "rationale": "Tooling addition — runnable script — scripts/."
+    },
+
+    {
+      "id": "branch-F-01",
+      "payload": "FB-42 resolved upstream; the skill used to say <admin-statusbar> defaults to slot=footer, but that was wrong. Update the skill's misdiagnosis taxonomy in CorrectionLoop.",
+      "expected_branch": "F",
+      "expected_landing_pattern": "§CorrectionLoop",
+      "rationale": "Feedback resolution — correction belongs in §CorrectionLoop."
+    },
+
+    {
+      "id": "branch-G-01",
+      "payload": "lesson learned from the v0.6.33 release cycle — the icon-loader race condition that caused FB-53 was a one-off that's already fixed upstream. Archive the post-mortem.",
+      "expected_branch": "G",
+      "expected_landing_pattern": "docs/journal/",
+      "rationale": "Arc story / historical context — journal entry, not skill."
+    }
+  ],
+
+  "evaluator_notes": {
+    "current_state": "Corpus has 9 cases across all 7 branches (A: 2 cases, B: 2 cases, C/D/E/F/G: 1 case each). Pass-rate target: 100% on the bundled corpus (the script must classify its own canonical examples correctly).",
+    "promotion_criteria": "Add 2-3 cases per quarterly senior-skill checkpoint as new payload shapes are observed. Aim for ≥3 cases per branch by v3.2.0 (per AGENTS.md BORIS §B3 cadence).",
+    "review_cadence": "When teach-route.mjs misroutes in real-world use, add the failing payload to the corpus as a new case with the correct expected_branch. The corpus grows in lockstep with the script's vocabulary."
+  }
+}

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

@@ -0,0 +1,245 @@
+---
+name: capabilities
+load-when: When choosing a mode / capability: full 14-item menu + per-mode triage table + 'pick your entry point' rows. Load if the seed's 4-item summary doesn't cover the user's intent.
+load-size-tokens: ~3,700
+required-for:
+  - mode picking
+  - first-task discovery
+---
+
+# What this skill can do (capability surface)
+
+**LLM directive — on-load presentation contract.** When the user invokes
+this skill with no concrete request — e.g. `use adia-ui-kit`, `load
+adia-ui-kit`, `what can you do with AdiaUI?`, "the skill is loaded, now
+what?" — your on-load summary must follow **this exact shape**:
+
+1. One short greeting line acknowledging the skill is active and its
+   version (e.g. `✅ AdiaUI Kit skill v2.8.0 active. Here's the full
+   capability surface:`).
+2. A **numbered list (1., 2., 3., …)** with one item per category below.
+3. Each item formatted as two lines:
+   - **Line 1 (headline):** `<N>. <emoji> <Title>` — short, scannable.
+   - **Line 2 (summary):** one short sentence in plain English describing
+     what the user gets, **plus** the `→ §Section` pointer at the end.
+4. Do **not** dump the inline detail strings ("npm install …", attribute
+   names, decorator syntax) into the on-load summary. Those belong in the
+   section bodies. The on-load summary is a menu, not a manual.
+5. **Enumerate every category — do not collapse, drop, or merge.**
+   Install (📦) and Harness (🧬) are the most-missed; surface them as
+   their own numbered items, never folded into a generic "Setup" line.
+   Consultant posture (🩺, item 13) is the most-missed for brownfield
+   sessions — when the user lands in an existing repo without naming a
+   concrete request, item 13 is often the right entry point.
+6. **Render the "Pick your entry point" triage table** (verbatim from
+   below — copy the markdown table; do NOT paraphrase) immediately after
+   the 13-item menu, under the heading `### Where are you starting from?`.
+   The menu tells the user *what the skill offers*; the triage table
+   tells them *which item maps to their situation*. Both are required.
+7. End with one short prompt question (e.g. `Which would you like to
+   start with — pick a number 1-13, or describe your situation?`) —
+   never start composing markup before the user picks.
+
+The skill operates across the full project lifecycle, from `npm create
+vite@latest` through shipping a generative-UI surface. **Render the
+capability menu from the headlines + summaries below — not the detail
+fields.**
+
+### Capability menu (the on-load source-of-truth)
+
+1. 📦 **Install `@adia-ai` packages**
+   - **Summary:** The cold-start path — install the npm packages, wire
+     `main.js` with CSS + barrel + icon loader, and verify with
+     `scripts/check-adia-versions.py` that the 9-package lockstep is
+     aligned + installed ≥ latest published. **End state: a working
+     `<button-ui>` or `<card-ui>` rendering in the browser.** No
+     generative harness required at this stage — that's a separate
+     opt-in (item 4) for apps that render LLM-generated UI at runtime.
+     **If the project has no `AGENTS.md` / `CLAUDE.md` at the root,
+     scaffold them from `assets/templates/` so future agent sessions
+     auto-load with the right skill pointer.** → §Setup + §VersionCheck
+   - *Detail (for the body, not the on-load menu):* `npm install
+     @adia-ai/web-components @adia-ai/web-modules @phosphor-icons/core`,
+     wire CSS + barrel import + `installIconLoadersForRegistered`,
+     minimal Vite config, TypeScript types, per-component imports for
+     tree-shaking, conflict-safe `defineIfFree` registration.
+     **Verify** with `scripts/check-adia-versions.py` — reports
+     installed / declared / latest side-by-side and exits non-zero on
+     lockstep break, stale install, or undeclared user-facing package.
+     **Bootstrap** `AGENTS.md` + `CLAUDE.md` (1-line pointer) from
+     `assets/templates/` if absent — see §Setup Step 8. **`<canvas-ui>` /
+     `<a2ui-root>` / `registerResolver` are NOT part of basic install** —
+     they belong to the generative harness (item 4), which the vast
+     majority of product UIs (dashboards, forms, data tables, auth
+     flows) do not need.
+
+2. 🖼️ **Wire AdiaUI into an existing framework app**
+   - **Summary:** Drop AdiaUI into SPA, Next.js, Nuxt, SvelteKit, or
+     Astro with framework-correct imports and property binding.
+     → §Rendering Model
+   - *Detail:* `'use client'` boundaries, hydration guards, React
+     `useEffect`+`ref`, Vue `:value`, Svelte `bind:value`, SSR-safe
+     barrel placement.
+
+3. 🤖 **Install + use the AdiaUI MCP server**
+   - **Summary:** Drive AdiaUI from your agent IDE (Claude Desktop /
+     Claude Code / Cursor / Windsurf) via the `adiaui-mcp` server.
+     → §MCP
+   - *Detail:* one-time host registration, provider keys, native tools
+     `generate_ui` / `list_patterns` / `refine_ui` / `server_status`,
+     dual stdio (sampling) + HTTP transports.
+
+4. 🧬 **Choose a generative-UI rendering mode**
+   - **Summary:** Once the harness is mounted (item 1), decide *when*
+     generation happens — at build time (static HTML), at runtime from
+     a `doc=` array (no server), or live via SSE/MCP streaming. → §Harness
+   - *Detail:* Mode A (author-time → static HTML committed to repo),
+     Mode B (runtime `doc=` rendering, no server), Mode C (SSE/MCP
+     streaming), `canvas.process()` / `canvas.processAll()` /
+     `canvas.reset()` API, when each mode is the right fit.
+
+5. 🚚 **Migrate from `@agent-ui-kit` or an older `@adia-ai` version**
+   - **Summary:** Bring an inherited or pre-existing codebase forward —
+     namespace rename (`@agent-ui-kit/*` → `@adia-ai/*`), tag renames,
+     attribute changes, token renames, retired legacy shell shapes,
+     and every version-cut breaking change up to `^0.6.0`. → §Migration
+     (defers to `docs/MIGRATION GUIDE.md` + the `adia-ui-migration` skill
+     for the mechanical sweep)
+   - *Detail:* Predecessor namespace `@agent-ui-kit/web-components` →
+     `@adia-ai/*` 9-package monorepo; base class `AgentElement`/`AdiaElement`
+     → `UIElement`; design tokens `--agent-*` → `--a-*`; `<stat-ui>` →
+     `<stat>` filename; `<link-ui>` token rename `--link-color-*` →
+     `--link-fg-*`; legacy shell authoring shapes RETIRED in `0.4.0`
+     (ADR-0024) — use the bespoke `<admin-shell>` / `<chat-shell>` /
+     `<editor-shell>` vocabulary. Mechanical sweeps via the dedicated
+     `adia-ui-migration` skill — call it explicitly for codebase-wide
+     search-and-replace + verification gate.
+
+6. 🏗️ **Build screens and flows (phase-gated)**
+   - **Summary:** Compose a new surface via §0 plan → §1 catalog → §2
+     markup → §3 validation. Never skip §0. → §0 Reasoning Gate
+   - *Detail:* GenUI Plan + confirmation wait, yaml/a2ui.json lookup,
+     HTML + A2UI JSON composition, 5-gate validation checklist.
+
+7. 🔌 **Wire state and data**
+   - **Summary:** Add reactivity, domain state, and live endpoints
+     without script blocks of `fetch()`. → §State
+   - *Detail:* signals (local), `BaseController` (domain state with
+     optimistic + undo/redo), `data-stream-*` bindings (REST/SSE),
+     form submission patterns.
+
+8. 🎨 **Theme and brand**
+   - **Summary:** Apply named themes, toggle light/dark, or override
+     brand colors via tokens. → §Theme
+   - *Detail:* `toggle-scheme`, density modes, custom theme registration,
+     zero-specificity token overrides.
+
+9. 🧩 **Apply real-world patterns**
+   - **Summary:** Reach for proven assemblies — admin shell, tables,
+     dashboards, charts, drawers, error pages, agent surfaces.
+     → §Patterns
+   - *Detail:* admin/editor/nested/simple shells, command palette,
+     `table-ui` + `table-toolbar-ui` pairing, KPI grids, all 18 chart
+     types, heatmaps, destructive confirms, 404/500, chat streaming +
+     reasoning panels.
+
+10. 📋 **Copy-paste end-to-end flows**
+    - **Summary:** Full recipes for the common surfaces — auth, wizard,
+      onboarding, settings, marketing, kanban. → §Flows
+    - *Detail:* sign-in / OTP / forgot-password, registration wizard,
+      persona picker, settings page, marketing hero, kanban board, user
+      profile card.
+
+11. 📚 **Discover documentation**
+    - **Summary:** Look up components, tokens, guides, and live demos
+      without inventing URLs. → §Docs
+    - *Detail:* URL manifest for `ui-kit.exe.xyz/site/...`, in-package
+      files (`<name>.yaml` / `.a2ui.json` / `.d.ts` / `.test.js` /
+      `.examples.md` v0.6.7+), numbered guides in `docs/guides/`,
+      specs in `docs/specs/`, documentation triage table.
+
+12. 📝 **Author session logs + defensible upstream tickets**
+    - **Summary:** Capture provenance and file upstream FEEDBACK
+      maintainers can act on. Agents draft to
+      `.agents/team/tickets/drafts/` on a rolling basis; humans finalize
+      to `outbox/`; responses land in `inbox/`. The 4-stage pipeline is
+      gated by `ticket-tool.py` (11 finalize gates).
+      → §FeedbackDiscipline + §Team Tickets + §AutoCapture + §TicketTooling
+    - *Detail:* `generate ui-kit log` → `.adia-ui-kit/session-log.md`;
+      `ticket-tool.py new feedback <recipient> --slug <s>` scaffolds a
+      draft from the 5-block template (Executive summary + cost table +
+      per-finding What/Root/Repro/Request/Why + verified exclusions +
+      pre-finalize checklist); `ticket-tool.py finalize NN` runs 11 gates
+      and promotes drafts/ → outbox/; `retract` / `set-status` /
+      `register-response` / `registry-rebuild` handle lifecycle.
+      Discipline vendored from color-app's battle-tested
+      `.agents/team/skills/feedback-authoring.md` (60+ shipped tickets).
+
+13. 🩺 **Diagnose an inherited / unknown AdiaUI repo (Consultant posture)**
+    - **Summary:** Land in a brownfield repo you don't know, walk a
+      9-step inventory + 3-class gap-detection, and produce a Repo
+      Health Report scoring overall posture across primitive usage,
+      composition shape, token coverage, version coherence, and
+      consumer-side hygiene. Use **before** filing tickets, proposing
+      migrations, or authoring new surfaces — the report tells you
+      what's already there and where the actual gaps are.
+      → §Recon + §GapDetection + §DiagnosticOutput
+    - *Detail:* 9-step recon (sitemap / package.json / @adia-ai version
+      coherence / shell-tier inventory / token usage / primitive census
+      / unused-import scan / a11y signals / build state); 3 gap classes
+      (substrate-misuse, version-drift, missing-discipline); diagnostic
+      template (executive summary + per-gap What/Evidence/Layer/Fix +
+      posture assessment). Archive each report alongside the consuming
+      repo's other diagnostics (e.g. a `diagnostic-reports/` folder),
+      named `YYYY-MM-DD-<repo>-health-report.md`.
+      Pair with §CorrectionLoop when a specific bug is reported (the
+      report tells you the landscape; the correction loop tells you how
+      to reason about a specific defect).
+
+14. 📚 **Teach the skill new knowledge (Teach posture)**
+    - **Summary:** Land new knowledge (a new primitive, a new pattern,
+      a resolved FEEDBACK ticket, a methodology shift) into the right
+      target without bloating the skill or drifting from yaml SoT. The
+      Teach protocol's decision tree routes each input to its correct
+      home — yaml SoT (per-component facts), a patterns reference
+      (cross-component recipes), a flows reference (end-to-end
+      journeys), inline SKILL.md (methodology / posture), tooling
+      cross-link, FEEDBACK correction, or **NO landing in the skill**
+      (arc stories belong in the journal, not here). Triggers: "make
+      sure adia-ui-kit knows about X", "train the skill on Y", "absorb
+      this lesson into adia-ui-kit", "the skill should be aware of Z".
+      → §Teach (→ `references/teach-protocol.md` for the full procedure)
+    - *Detail:* 5-step landing procedure (audit before patching →
+      author the patch → wire the activation surface → version +
+      CHANGELOG → verify with `audit:skill-hygiene`). Seven worked
+      examples covering every decision-tree branch including the
+      negative case ("arc stories go in journal, not skill"). Seven
+      anti-patterns observed during this skill's own evolution
+      (append-only, yaml SoT duplication, orphan triggers, capability
+      menu lies, MINOR + PATCH bundling, hygiene-debt deferral,
+      one-way thinking). Use when another agent in the codebase hands
+      you new content to integrate; **don't use** when authoring fresh
+      from scratch (that's §Mission Author posture) or fixing a wrong
+      claim (§CorrectionLoop).
+
+**Pick your entry point** by where the project is today:
+
+| Project state                                              | Start at           |
+| ---------------------------------------------------------- | ------------------ |
+| **Inherited / unknown repo — diagnose first**              | **§Recon + §GapDetection + §DiagnosticOutput** |
+| Empty / fresh `npm create vite@latest`                     | §Setup + §Harness  |
+| Existing SPA / Next / Nuxt / SvelteKit / Astro             | §Rendering Model   |
+| Existing AdiaUI app, want runtime/generative UI            | §Harness           |
+| Existing app on `@agent-ui-kit` or older `@adia-ai` version | §Migration         |
+| Want to drive AdiaUI from an agent (Claude/Cursor/Windsurf)| §MCP               |
+| **Teaching the skill new knowledge — \"make adia-ui-kit aware of X\"** | **§Teach**         |
+| Existing AdiaUI app, building a new feature                | §0 Reasoning Gate  |
+| Need to recreate a known surface (admin / chat / form)     | §Flows or §Patterns |
+| Found a bug or want to file feedback                       | §Tickets           |
+| Wrong output reported — diagnose before fixing             | §CorrectionLoop    |
+
+If the user request is ambiguous about which entry point applies, **ask
+one clarifying question** (e.g. "is this a new project or an existing
+app?") before recommending steps. Don't assume cold-start.
+
+---

package/skills/adia-ui-kit/references/catalog-lookup.md

@@ -0,0 +1,186 @@
+---
+name: catalog-lookup
+load-when: Before composing — when matching user intent to specific AdiaUI primitives. Covers the ladder (intent to component category to specific tag), llms.txt usage, examples.html lookup, and the canonical-tag search procedure
+load-size-tokens: ~2,500
+required-for:
+  - composition modes 1-4
+  - pre-author bundle gate
+---
+
+# §1 — Catalog Lookup (before composing)
+
+Before writing any markup, look up what exists. Using attributes that
+don't exist or invoking unregistered tags is the second most common
+failure after premature rendering.
+
+> ⚠️ **Prior-art-first rule (NON-NEGOTIABLE).** Before authoring a
+> novel solution for ANY UI problem, you must FIRST exhaust the
+> existing catalog. Concretely:
+>
+> 1. **`packages/web-components/components/`** (122 primitives). Scan
+>    by category and by keyword. Every primitive ships a `<name>.yaml`
+>    with `description`, `props`, `slots`, `events`, `composes`,
+>    `keywords`, `synonyms`, and `anti_patterns` fields specifically so
+>    you can find it by intent, not just by tag name. If your problem
+>    is "show a loading state for a KPI card", `stat-ui[loading]` +
+>    `skeleton-ui` already solve it (v0.6.18). If your problem is
+>    "imperative toast", `feed-ui` + the `CustomEvent('feed')` bus
+>    already solve it. Do not invent `<my-loading-card>` or a
+>    re-implementation of a toast queue.
+> 2. **`packages/web-modules/`** (composite shells + canvas + a2ui-runtime).
+>    Scan the four shell clusters (`shell/`, `chat/`, `editor/`,
+>    `simple/`) and the `generative/` cluster. If your problem is
+>    "split-pane sidebar + topbar + content scroll region", `admin-shell`
+>    has already solved it; do not hand-roll a flex layout. If your
+>    problem is "compose web-components from JSON", `a2ui-root` /
+>    `registerResolver` already solve it.
+> 3. **Token system** (`packages/web-components/styles/tokens.css` +
+>    `typography.css` + `prose.css`). Before introducing a new CSS
+>    variable, check the existing ladder. `--a-canvas-{0..4}`,
+>    `--a-body-{sm,md,lg}`, `--a-weight-{regular,medium,semibold,bold}`,
+>    `--a-fg{,-muted,-strong}` etc. cover almost every typography +
+>    surface need.
+> 4. **Traits** (`packages/web-components/traits/`, 56 traits in 9
+>    categories). Cross-cutting behaviors (`dismissible`, `selectable`,
+>    `resizable`, `keyboard-nav`, etc.) are encoded as traits with their
+>    own examples + tests. If your problem maps to a trait, USE the
+>    trait — don't re-implement the behavior inline.
+>
+> **Searching is mandatory; not finding is rare.** When the v0.6.18 cut
+> shipped `text-ui` size/color/weight/text-align overlays (FB-10), the
+> skill had been documenting those props as if they existed for two
+> previous versions — because consumers naturally reached for them and
+> the existing variant-only API was missing the obvious overlay layer.
+> The substrate caught up to the doc, not the other way around. That
+> only works if you check the doc + the substrate side-by-side. If
+> what you need ISN'T in the catalog, the right move is **file a
+> FEEDBACK ticket** (see §Team Tickets) — not invent a one-off.
+>
+> **How to search efficiently:**
+> - `npx adia-ui-doc <name>` — fast yaml summary for a tag you suspect exists
+> - `npx adia-ui-doc` (no arg) — list all 96 components
+> - `grep -rE "keywords:|synonyms:|description:" packages/web-components/components/*/­*.yaml | grep -i "<your intent>"`
+>   — semantic search across the catalog
+> - Live site: `https://ui-kit.exe.xyz/site/components/` (browse) or
+>   `/site/components/<name>` (deep dive)
+> - For modules: `ls packages/web-modules/*/`
+
+> **Where:** authoritative API in `<name>.yaml` (ships in npm). Visual
+> reference at `https://ui-kit.exe.xyz/site/components/<name>`. Full
+> URL manifest in §Docs below. If you're unsure what tools you have to
+> fetch a URL, prefer the local `.yaml` — it's always available.
+
+### Where to look
+
+**External consumer (installed via npm):**
+
+```
+node_modules/@adia-ai/web-components/components/<name>/
+  <name>.yaml         ← canonical API spec (props, slots, events, anti-patterns)  ✓ ships
+  <name>.a2ui.json    ← A2UI JSON spec (generated)                                ✓ ships
+  <name>.d.ts         ← TypeScript declarations                                   ✓ ships
+  <name>.examples.md  ← canonical usage fragments (1-3 per component)             ✓ ships (v0.6.7+)
+  <name>.test.js      ← behavioral contract (read for "why does X work this way") ✓ ships
+  <name>.examples.html ← authoring demo with full page chrome — NOT in npm
+                          → in-repo only; external consumers use .examples.md
+
+node_modules/@adia-ai/web-components/
+  custom-elements.json ← W3C Custom Elements Manifest v2.1.0 (110 modules)        ✓ ships (v0.6.7+)
+  bin/doc.mjs          ← CLI: npx adia-ai-doc <name>                              ✓ ships (v0.6.7+)
+  USAGE.md             ← deep usage patterns (incl. data-stream-* §6)             ✓ ships
+
+node_modules/@adia-ai/web-modules/<cluster>/<name>/
+  Clusters: shell | chat | editor | simple | runtime | theme | generative
+  ↑ NEW v0.6.7: `generative` subpath bundles canvas-ui + a2ui-root + registerResolver
+```
+
+> **Examples ship as Markdown** (v0.6.7+). Each component has a `.examples.md`
+> with 1-3 canonical fragments — the authoring `.examples.html` files are
+> still in-repo only (they have full demo-page chrome too heavy to ship).
+> For richer visual reference, browse `https://ui-kit.exe.xyz/site/components/<name>`.
+
+Live component docs: `https://ui-kit.exe.xyz/site/components/<name>`
+(e.g. `https://ui-kit.exe.xyz/site/components/button`)
+
+**Component stability — `status` badge** (since v0.6.32+):
+
+When browsing `/site/components/<name>`, a colored `<tag-ui>` badge
+next to the component name indicates its stability:
+
+| Badge | Variant | Meaning |
+|-------|---------|---------|
+| (no badge) | — | `status: stable` — public API; safe to use |
+| `beta` | `warning` | Functional, but API may still change in MINOR releases |
+| `experimental` | `ghost` | Early prototype; expect breaking changes |
+| `deprecated` | `danger` | Replacement exists — check the page's `Related` section |
+| `early-access` | `info` | Customer-preview tier; consult release notes before relying on it |
+
+The status is set in `<name>.yaml` (`status: <value>`) and propagated
+automatically through the sidecar to the docs site. All current
+components ship `status: stable` (the vast majority show no badge).
+Authoring guidance for new components: see `adia-ui-authoring` skill
+yaml contract.
+
+**In the AdiaUI monorepo** (`/Users/kimba/Projects/adia/gen-ui-kit`):
+
+```
+packages/web-components/components/<name>/
+packages/web-modules/<cluster>/<name>/
+docs/specs/component-token-contract.md
+docs/specs/component-implementation-patterns.md
+```
+
+### Lookup procedure
+
+**Fastest path (v0.6.7+): use the bundled CLI.**
+
+```bash
+npx adia-ui-doc <name>      # yaml summary + live URL + first example
+npx adia-ui-doc              # list all 96 components
+```
+
+The CLI reads from the installed package, so it always reflects the
+version you're actually running.
+
+**For full detail, read the artifacts directly:**
+
+1. **List the catalog** (external): `ls node_modules/@adia-ai/web-components/components/ | sort`
+   Or in-repo: `ls packages/web-components/components/ | sort`
+2. **Read the yaml** for any component you plan to use:
+   ```
+   cat node_modules/@adia-ai/web-components/components/<name>/<name>.yaml
+   ```
+   Key sections: `props:`, `slots:`, `events:`, `tokens:`, `anti_patterns:`
+3. **Check a2ui.json** for enum values and prop types:
+   ```
+   cat node_modules/@adia-ai/web-components/components/<name>/<name>.a2ui.json
+   ```
+4. **For TypeScript users:** `<name>.d.ts` has the typed prop surface:
+   ```
+   cat node_modules/@adia-ai/web-components/components/<name>/<name>.d.ts
+   ```
+5. **For canonical markup examples** (v0.6.7+, ships in npm):
+   ```
+   cat node_modules/@adia-ai/web-components/components/<name>/<name>.examples.md
+   ```
+   1-3 fragments per component. For richer visual reference, browse
+   `https://ui-kit.exe.xyz/site/components/<name>`.
+6. **For behavioral edge cases:** `<name>.test.js` is the authoritative
+   spec — vitest tests document expected behavior including focus management,
+   keyboard nav, ARIA assertions.
+7. **For IDE / tool integration** (v0.6.7+): the package ships
+   `custom-elements.json` (W3C manifest v2.1.0). VS Code LSP extensions
+   pick this up automatically for autocomplete and type-safety.
+
+### Co-located registrations
+
+Some elements register inside their parent `.js` (not a separate
+directory): `list-item-ui`, `stepper-item-ui`, `avatar-group-ui`.
+If a directory doesn't exist, grep `customElements.define` in the
+parent before assuming the element is missing.
+
+### CSS-only components
+
+`header/`, `footer/`, `section/` ship yaml + a2ui.json only — no `.js`.
+They are styled by parent slot rules. Do not try to register them.
+---

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

@@ -0,0 +1,8 @@
+# adia-ui-kit Changelog — v1.x archive
+
+> Historical entries rolled out of the live [`CHANGELOG.md`](../../CHANGELOG.md), which keeps only the most recent 3. Newest-first.
+
+## 1.0.0 (2026-04-16)
+
+- Initial version
+- Migrated from skills/ to .claude/skills/ format