@adia-ai/adia-ui-forge 0.8.4 → 0.8.6

package/skills/adia-author/evals/routing-corpus.json

@@ -1,222 +1,43 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "name": "adia-author routing accuracy corpus",
-  "version": "2.0.0",
-  "purpose": "Routing-eval corpus for adia-author (adia-forge plugin). Each phrase declares whether adia-author SHOULD be the routing target. Scored by the estate's TF-IDF routing-eval runner against the skill's description (heuristic token overlap).",
-  "scoring_notes": "Heuristic signal, not ground truth. Treat misroutes as a prompt to tighten the skill description, never as a reason to keyword-stuff it. Real harness routing is LLM-driven.",
-  "license": "internal",
-  "scope": "adia-author routing — does this phrase activate adia-author?",
-
-  "minimums_per_spec": {
-    "trigger_phrases": 21,
-    "adversarial_phrases": 6,
-    "task_shapes_covered": "new-primitive, modify-primitive, shell, module-promotion, drift-audit, llm-bridge, composite-demo",
-    "adversarial_fraction": "20%"
-  },
-
-  "phrases": [
-    {
-      "id": "author-new-primitive-01",
-      "phrase": "add a new button-ui primitive component",
-      "should_route_to_author": true,
-      "expected_shape": "new-primitive",
-      "rationale": "Canonical new-primitive task shape."
-    },
-    {
-      "id": "author-new-primitive-02",
-      "phrase": "build a new <toggle-ui> component from scratch",
-      "should_route_to_author": true,
-      "expected_shape": "new-primitive",
-      "rationale": "'build a <foo-ui>' phrasing."
-    },
-    {
-      "id": "author-new-primitive-03",
-      "phrase": "create a new primitive web component in packages/web-components",
-      "should_route_to_author": true,
-      "expected_shape": "new-primitive",
-      "rationale": "Explicit packages/web-components path mention."
-    },
-
-    {
-      "id": "author-modify-01",
-      "phrase": "add a new prop to table-ui",
-      "should_route_to_author": true,
-      "expected_shape": "modify-primitive",
-      "rationale": "Modify existing primitive — add a prop."
-    },
-    {
-      "id": "author-modify-02",
-      "phrase": "fix the CSS in card-ui to handle the new bleed variant",
-      "should_route_to_author": true,
-      "expected_shape": "modify-primitive",
-      "rationale": "Modify existing primitive CSS."
-    },
-    {
-      "id": "author-modify-03",
-      "phrase": "update the input-ui yaml to add a placeholder attribute",
-      "should_route_to_author": true,
-      "expected_shape": "modify-primitive",
-      "rationale": "Update the yaml SoT for an existing primitive."
-    },
-
-    {
-      "id": "author-shell-01",
-      "phrase": "build the chat-shell composition with the new sidebar slot",
-      "should_route_to_author": true,
-      "expected_shape": "shell",
-      "rationale": "Shell authoring."
-    },
-    {
-      "id": "author-shell-02",
-      "phrase": "author a new web-module shell at packages/web-modules/editor/editor-shell",
-      "should_route_to_author": true,
-      "expected_shape": "shell",
-      "rationale": "Explicit web-modules + shell."
-    },
-    {
-      "id": "author-shell-03",
-      "phrase": "add a pane behaviour to admin-shell per the bespoke shell-tier convention",
-      "should_route_to_author": true,
-      "expected_shape": "shell",
-      "rationale": "Bespoke shell-tier (ADR-0023 shape) work."
-    },
-
-    {
-      "id": "author-promote-01",
-      "phrase": "promote this inline content to a shared web-modules module",
-      "should_route_to_author": true,
-      "expected_shape": "module-promotion",
-      "rationale": "Promote inline → module."
-    },
-    {
-      "id": "author-promote-02",
-      "phrase": "this content keeps repeating across apps, extract to a shared module",
-      "should_route_to_author": true,
-      "expected_shape": "module-promotion",
-      "rationale": "Repetition trigger."
-    },
-    {
-      "id": "author-promote-03",
-      "phrase": "lift this billing-summary block from apps/saas to web-modules",
-      "should_route_to_author": true,
-      "expected_shape": "module-promotion",
-      "rationale": "Lift inline page content to a reusable module."
-    },
-
-    {
-      "id": "author-audit-01",
-      "phrase": "audit the four-axis contract for table-ui",
-      "should_route_to_author": true,
-      "expected_shape": "drift-audit",
-      "rationale": "Contract drift audit."
-    },
-    {
-      "id": "author-audit-02",
-      "phrase": "check the token usage in card-ui for drift",
-      "should_route_to_author": true,
-      "expected_shape": "drift-audit",
-      "rationale": "Token audit procedure."
-    },
-    {
-      "id": "author-audit-03",
-      "phrase": "lifecycle audit on dropdown-ui — symmetric connected/disconnected?",
-      "should_route_to_author": true,
-      "expected_shape": "drift-audit",
-      "rationale": "Lifecycle audit."
-    },
-
-    {
-      "id": "author-llm-01",
-      "phrase": "extend the LLM bridge to add a new provider",
-      "should_route_to_author": true,
-      "expected_shape": "llm-bridge",
-      "rationale": "Extend @adia-ai/llm."
-    },
-    {
-      "id": "author-llm-02",
-      "phrase": "modify createAdapter in @adia-ai/llm to add chunk-shape support",
-      "should_route_to_author": true,
-      "expected_shape": "llm-bridge",
-      "rationale": "Explicit createAdapter + @adia-ai/llm mention."
-    },
-    {
-      "id": "author-llm-03",
-      "phrase": "set up the LLM-bridge surface for a new tool-call provider",
-      "should_route_to_author": true,
-      "expected_shape": "llm-bridge",
-      "rationale": "LLM-bridge trigger phrase."
-    },
-
-    {
-      "id": "author-demo-01",
-      "phrase": "author a demo for the billing-overview composite",
-      "should_route_to_author": true,
-      "expected_shape": "composite-demo",
-      "rationale": "Composite-demo authoring."
-    },
-    {
-      "id": "author-demo-02",
-      "phrase": "compose the examples.html for dashboard-layout",
-      "should_route_to_author": true,
-      "expected_shape": "composite-demo",
-      "rationale": "'compose examples.html for Y' trigger."
-    },
-    {
-      "id": "author-demo-03",
-      "phrase": "write the demo for <integrations-page-ui> in packages/web-modules/settings",
-      "should_route_to_author": true,
-      "expected_shape": "composite-demo",
-      "rationale": "'write the demo for <module-ui>' + web-modules path."
-    },
-
-    {
-      "id": "author-adv-01",
-      "phrase": "compose this Figma mock into AdiaUI components for our consumer app",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-compose (adia-factory plugin)",
-      "rationale": "Adversarial — consumer-side composition (screens FROM existing primitives). The description NEG-fences it."
-    },
-    {
-      "id": "author-adv-02",
-      "phrase": "cut a release of the next version and publish the npm packages",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-release",
-      "rationale": "Adversarial — release territory."
-    },
-    {
-      "id": "author-adv-03",
-      "phrase": "tune the zettel composition coverage; eval is at 38%",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-a2ui",
-      "rationale": "Adversarial — a2ui pipeline internals (compose strategies, eval coverage)."
-    },
-    {
-      "id": "author-adv-04",
-      "phrase": "build a user profile card with avatar and edit actions",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-compose (adia-factory plugin)",
-      "rationale": "Adversarial — canonical consumer-composition task (build UI from intent)."
-    },
-    {
-      "id": "author-adv-05",
-      "phrase": "deploy the api service to the hosting platform",
-      "should_route_to_author": false,
-      "expected_alternative": "adia-deploy",
-      "rationale": "Adversarial — deployment/ops territory."
-    },
-    {
-      "id": "author-adv-06",
-      "phrase": "explain how React hooks work",
-      "should_route_to_author": false,
-      "expected_alternative": null,
-      "rationale": "Adversarial — generic framework knowledge; no AdiaUI skill should activate."
-    }
+  "positives": [
+    "add a new button-ui primitive component",
+    "build a new <toggle-ui> component from scratch",
+    "create a new primitive web component in packages/web-components",
+    "add a new prop to table-ui",
+    "fix the CSS in card-ui to handle the new bleed variant",
+    "update the input-ui yaml to add a placeholder attribute",
+    "build the chat-shell composition with the new sidebar slot",
+    "author a new web-module shell at packages/web-modules/editor/editor-shell",
+    "add a pane behaviour to admin-shell per the bespoke shell-tier convention",
+    "promote this inline content to a shared web-modules module",
+    "this content keeps repeating across apps, extract to a shared module",
+    "lift this billing-summary block from apps/saas to web-modules",
+    "audit the four-axis contract for table-ui",
+    "check the token usage in card-ui for drift",
+    "lifecycle audit on dropdown-ui \u2014 symmetric connected/disconnected?",
+    "author a demo for the billing-overview composite",
+    "compose the examples.html for dashboard-layout",
+    "write the demo for <integrations-page-ui> in packages/web-modules/settings"
   ],
-
-  "evaluator_notes": {
-    "current_state": "27 cases (21 trigger + 6 adversarial). Each of the 7 task shapes has 3 trigger cases. The old corpus's 3 Teach-mode cases were dropped (skill-teaching is estate-level maintenance now, not a product-skill mode).",
-    "promotion_criteria": "Promote to a CI gate (warn → hard-fail) when F1 ≥ 0.85 on this corpus across 3+ consecutive runs without description edits.",
-    "review_cadence": "Re-run on every adia-author description edit. Add 1-2 new cases per checkpoint reflecting newly-observed routing failure modes.",
-    "known_limitations": "module-promotion and composite-demo phrases overlap semantically ('lift to web-modules' vs 'author demo for module') — the heuristic scorer may not disambiguate; the harness with file-path context will (the demo path pattern also fires the demo-postwrite-pattern-gate hook regardless of routing)."
+  "negatives": [
+    "compose this Figma mock into AdiaUI components for our consumer app",
+    "cut a release of the next version and publish the npm packages",
+    "tune the zettel composition coverage; eval is at 38%",
+    "build a user profile card with avatar and edit actions",
+    "deploy the api service to the hosting platform",
+    "explain how React hooks work",
+    "the gemini adapter is dropping usage tokens on streamed responses",
+    "fix the openai stopReason mapping in the llm client",
+    "extend the LLM bridge to add a new provider",
+    "modify createAdapter in @adia-ai/llm to add chunk-shape support",
+    "set up the LLM-bridge surface for a new tool-call provider"
+  ],
+  "_measured": {
+    "as_of": "2026-07-18",
+    "scorer": "routing_eval.py (nonoun-plugins/forge)",
+    "f1": 0.971,
+    "precision": 1.0,
+    "recall": 0.944,
+    "exit_code": 0
   }
 }

package/skills/adia-author/references/anti-patterns.md

@@ -376,7 +376,7 @@ disconnected() {
 
 ```javascript
 // WRONG — chart.js (pre-fix)
-class AdiaChart extends AdiaElement {
+class UIChart extends UIElement {
   connected() { /* ... */ this.#ro = new ResizeObserver(...); }
 
   disconnected() {
@@ -408,8 +408,8 @@ disconnected() {
 ### AP-L3 · Missing `super.connected()` / `super.disconnected()`
 
 ```javascript
-// WRONG — AdiaFormElement subclass missing super call
-class AdiaInput extends AdiaFormElement {
+// WRONG — UIFormElement subclass missing super call
+class UIInput extends UIFormElement {
   connected() {
     // super.connected() NOT called
     this.#inputEl = this.querySelector('input');
@@ -479,7 +479,7 @@ updateConfig(opts) {
 
 ```javascript
 // WRONG — drawer.js (pre-fix)
-class AdiaDrawer extends AdiaElement {
+class UIDrawer extends UIElement {
   static template = () => html``;   // ← looks harmless. It isn't.
 
   connected() {
@@ -489,7 +489,7 @@ class AdiaDrawer extends AdiaElement {
 }
 ```
 
-**What went wrong:** `AdiaElement`'s base `connectedCallback` runs an effect that calls `stamp(template(this), this)`. `stamp` calls `mount`, which calls `container.replaceChildren(fragment)`. Even an "empty" `html\`\``produces a non-null result, so`replaceChildren`runs and clears every authored child (header/section/footer) out of the host element. The component's own`render()` then tries to migrate children that no longer exist.
+**What went wrong:** `UIElement`'s base `connectedCallback` runs an effect that calls `stamp(template(this), this)`. `stamp` calls `mount`, which calls `container.replaceChildren(fragment)`. Even an "empty" `html\`\``produces a non-null result, so`replaceChildren`runs and clears every authored child (header/section/footer) out of the host element. The component's own`render()` then tries to migrate children that no longer exist.
 
 Symptom: drawers render with a close button in an empty panel; all authored content is gone. Hard to debug because the children WERE in the DOM at `connected()` time — they get wiped milliseconds later when the effect runs.
 
@@ -497,8 +497,8 @@ Symptom: drawers render with a close button in an empty panel; all authored cont
 
 ```javascript
 // RIGHT — no template override
-class AdiaDrawer extends AdiaElement {
-  // base AdiaElement.template returns null → stamp() is skipped →
+class UIDrawer extends UIElement {
+  // base UIElement.template returns null → stamp() is skipped →
   // authored light-DOM children survive through render().
 
   connected() { /* ... */ }

package/skills/adia-author/references/api-contract.md

@@ -4,7 +4,7 @@ Deep dive on declaring component APIs in AdiaUI. Read this when adding a new pro
 
 ## The `static properties` block
 
-Every `AdiaElement` subclass declares its public API as a `static properties` object. Keys are camelCase JS names; values describe type, default, reflection, and attribute mapping.
+Every `UIElement` subclass declares its public API as a `static properties` object. Keys are camelCase JS names; values describe type, default, reflection, and attribute mapping.
 
 ```javascript
 static properties = {
@@ -141,21 +141,21 @@ Reserve `error` for validation state (`[error]` on form inputs matches ARIA patt
 The component has three names that must agree:
 
 - **File path:** `packages/web-components/components/foo/foo.js`
-- **Class name:** `class AdiaFoo extends AdiaElement`
-- **Custom element tag:** `customElements.define('foo-ui', AdiaFoo)`
+- **Class name:** `class UIFoo extends UIElement`
+- **Custom element tag:** `customElements.define('foo-ui', UIFoo)`
 
 A fourth consistency requirement: the CSS file at `packages/web-components/components/foo/foo.css` uses `@scope (foo-ui)`.
 
-## Extending `AdiaFormElement`
+## Extending `UIFormElement`
 
-Form-participating components extend `AdiaFormElement` (which extends `AdiaElement`) and get `ElementInternals` wiring, form-reset handling, and `.form` / `.labels` / `.validity` accessors for free.
+Form-participating components extend `UIFormElement` (which extends `UIElement`) and get `ElementInternals` wiring, form-reset handling, and `.form` / `.labels` / `.validity` accessors for free.
 
 ```javascript
-import { AdiaFormElement } from '../../core/form.js';
+import { UIFormElement } from '../../core/form.js';
 
-class AdiaInput extends AdiaFormElement {
+class UIInput extends UIFormElement {
   static properties = {
-    ...AdiaFormElement.properties, // inherit name, value, disabled, required, etc.
+    ...UIFormElement.properties, // inherit name, value, disabled, required, etc.
     placeholder: { type: String, default: '', reflect: true },
   };
 
@@ -180,7 +180,7 @@ Key details:
 
 - **Always `super.connected()` and `super.disconnected()`** — without them, form-association doesn't register.
 - **`this.syncValue(str)`** — call this whenever the value changes to update the form-submitted string. Accepts a string.
-- **Inheriting properties** — spread `AdiaFormElement.properties` into your own `static properties` so you don't re-declare `name`, `disabled`, `required`.
+- **Inheriting properties** — spread `UIFormElement.properties` into your own `static properties` so you don't re-declare `name`, `disabled`, `required`.
 
 ## Event conventions
 

package/skills/adia-author/references/authoring-cycle.md

@@ -9,8 +9,8 @@ The 5-step procedure run AFTER [primitive-audit.md](primitive-audit.md) clears (
 Before writing or editing, load these four files. They are the ground truth:
 
 - `.claude/docs/specs/component-token-contract.md` — the authoritative invariants. Skim the whole thing if you haven't read it this session; focus on "Variants vs Modes" and "Sanctioned Mode Attributes" if you're adding a new layout-affecting attribute.
-- `packages/web-components/core/element.js` — `AdiaElement` base class. The `static properties` schema, `connected()`/`disconnected()`/`render()` lifecycle, and attribute-mapping conventions are all defined here.
-- `packages/web-components/core/form.js` — `AdiaFormElement`. Only needed if the new component participates in forms (inputs, selects, checkboxes, etc.).
+- `packages/web-components/core/element.js` — `UIElement` base class. The `static properties` schema, `connected()`/`disconnected()`/`render()` lifecycle, and attribute-mapping conventions are all defined here.
+- `packages/web-components/core/form.js` — `UIFormElement`. Only needed if the new component participates in forms (inputs, selects, checkboxes, etc.).
 - At least one good-citizen reference that matches the shape of what you're building. Pick from: `button-ui`, `card-ui`, `input-ui`, `textarea-ui`, `check-ui`. Read both the `.js` and the `.css`.
 
 ## Step 2 — Classify the work before you write
@@ -41,7 +41,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 5. **Reserved-name anti-patterns.** Avoid: `title` (collides with HTML tooltip attribute), `active` on parent components (use `value` for a selection or `step` for an index — per-item `active` on children is fine), `error` in variant names (use `danger`; reserve `error` for validation state), `disabled` on non-form-participating components (use `readonly`), `multiple` with exclusion semantics (use a negated positive like `single`).
 
-6. **Element tag ends in `-ui`; JS class is `Adia<Component>`.** `<foo-ui>` ↔ `class AdiaFoo extends AdiaElement`. Three-way consistency: filename, class name, custom-element tag. The sanctioned `-n` carve-out is `cot-ui` (the chain-of-thought streaming component); `nav-ui` was deprecated in favor of the `-ui` replacements. New `-n` tags require a contract-doc update — see `.claude/docs/specs/component-token-contract.md`.
+6. **Element tag ends in `-ui`; JS class is `UI<Component>`.** `<foo-ui>` ↔ `class UIFoo extends UIElement`. Three-way consistency: filename, class name, custom-element tag. The sanctioned `-n` carve-out is `cot-ui` (the chain-of-thought streaming component); `nav-ui` was deprecated in favor of the `-ui` replacements. New `-n` tags require a contract-doc update — see `.claude/docs/specs/component-token-contract.md`.
 
 ### CSS
 
@@ -86,7 +86,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 1. **Every `addEventListener` in `connected()` has a matching `removeEventListener` in `disconnected()`.** Handler must be a stable `#field` arrow (`#onClick = (e) => { ... }`), never an inline arrow passed to `addEventListener`. Inline arrows can't be removed — `removeEventListener` needs reference equality.
 
-2. **`AdiaFormElement` subclasses call `super.connected()` and `super.disconnected()`.** `ElementInternals` registration depends on it. Omitting `super` strands the form-association.
+2. **`UIFormElement` subclasses call `super.connected()` and `super.disconnected()`.** `ElementInternals` registration depends on it. Omitting `super` strands the form-association.
 
 3. **Timers and observers are torn down.** `clearInterval`, `clearTimeout`, `ResizeObserver.disconnect()`, `MutationObserver.disconnect()`, `IntersectionObserver.disconnect()` all in `disconnected()`.
 
@@ -164,7 +164,7 @@ Before declaring the work done, run through this checklist. If anything fails, f
 - [ ] Every `static properties` entry uses `attribute:` (not `attr:`).
 - [ ] Every state-bearing Boolean has `reflect: true`.
 - [ ] No reserved-name anti-patterns (`title`, parent-level `active`, `error` variant, `disabled` on non-form, exclusion-`multiple`).
-- [ ] Element tag ends in `-ui`; class is `Adia<Component>`.
+- [ ] Element tag ends in `-ui`; class is `UI<Component>`.
 
 ### CSS
 
@@ -179,11 +179,29 @@ Before declaring the work done, run through this checklist. If anything fails, f
 
 - [ ] Every `addEventListener` in `connected()` has a paired `removeEventListener` in `disconnected()`.
 - [ ] All handlers passed to `addEventListener` are stable `#field` arrows (or bound method refs), not inline arrows.
-- [ ] If the class extends `AdiaFormElement`, both `connected()` and `disconnected()` call `super`.
+- [ ] If the class extends `UIFormElement`, both `connected()` and `disconnected()` call `super`.
 - [ ] Every timer/observer created in `connected()` is disposed in `disconnected()`.
 - [ ] Cached DOM refs (`this.#fooEl`) are nulled in `disconnected()`.
 - [ ] Class declares `disconnected()` exactly once.
 
+## Step 4b — Author the yaml SoT (+ regenerate the sidecar)
+
+A component isn't just its `.js`/`.css` — the `<name>.yaml` is the SOURCE OF
+TRUTH the whole pipeline reads (docs site, A2UI registries, consumer
+harnesses, `.d.ts` codegen). Every new primitive ships one; every prop/slot/
+event change updates it. Field-by-field contract:
+[yaml-contract.md](yaml-contract.md). Then regenerate — never hand-edit the
+sidecar (`sidecar-prewrite-guard` blocks it anyway):
+
+```bash
+npm run build:components            # yaml → <name>.a2ui.json + catalog + .d.ts
+node scripts/build/components.mjs --verify   # "clean — N files up-to-date"
+```
+
+A primitive also needs BOTH barrel registrations — the CSS `@import` in
+`styles/components.css` AND the JS `export` in `components/index.js`
+(`scripts/audit/check-components-js-barrel.mjs` gates the second).
+
 ## Step 5 — Run the project's verification gates
 
 Before committing, run the project's verify scripts. These catch the drift-shaped bugs the checklist can miss:
@@ -206,4 +224,5 @@ If a gate fails, fix before declaring done.
 - [lifecycle-patterns.md](lifecycle-patterns.md) — timers, observers, popovers, listener patterns
 - [anti-patterns.md](anti-patterns.md) — full failure-mode catalogue, file:line refs
 - [worked-example.md](worked-example.md) — badge-ui + counter-ui walkthroughs
+- [yaml-contract.md](yaml-contract.md) — the `<name>.yaml` SoT schema (Step 4b)
 - [token-contract.md](token-contract.md) — token audit (post-implementation check)

package/skills/adia-author/references/code-style.md

@@ -210,7 +210,7 @@ Native DOM accessors (`textContent`, `innerHTML`) get clobbered if declared in `
 Every `addEventListener` in `connected()` must be paired with a `removeEventListener` in `disconnected()`. Every timer cleared, every observer disconnected, every popover removed. Handlers must be stable `#field` arrows so `removeEventListener` finds them via reference equality.
 
 ```js
-class AdiaBadge extends AdiaElement {
+class UIBadge extends UIElement {
   #onRemove = (e) => { /* ... */ };  // stable handler
 
   connected() {
@@ -226,7 +226,7 @@ class AdiaBadge extends AdiaElement {
 
 Inline arrows passed to `addEventListener` look fine and leak quietly — `removeEventListener` no-ops because the new arrow has different identity. Three components in one audit cycle bit on this exact bug.
 
-If the class extends `AdiaFormElement`, `connected()` and `disconnected()` MUST call `super.*` — `ElementInternals` registration depends on it. And declare `disconnected()` exactly once per class; the second silently overrides the first.
+If the class extends `UIFormElement`, `connected()` and `disconnected()` MUST call `super.*` — `ElementInternals` registration depends on it. And declare `disconnected()` exactly once per class; the second silently overrides the first.
 
 Full lifecycle patterns in [lifecycle-patterns.md](lifecycle-patterns.md).
 
@@ -276,11 +276,11 @@ When transparency-mixing colors, use `oklab` not `oklch` for the interpolation s
 
 ## Legacy avoidance
 
-The library was renamed from `@agent-ui-kit/*` to `@adia-ai/*`; tokens went from `--n-*` to `--a-*`; the base class went from `NanoElement` to `AdiaElement`. Don't use the legacy forms in new code. Don't reference `nano-ui` in notes, commit messages, CHANGELOG entries, or any AdiaUI artifact.
+The library was renamed from `@agent-ui-kit/*` to `@adia-ai/*`; tokens went from `--n-*` to `--a-*`; the base class went `NanoElement` → `AdiaElement` → `UIElement` (ADR-0016 class rename). Don't use the legacy forms in new code. Don't reference `nano-ui` in notes, commit messages, CHANGELOG entries, or any AdiaUI artifact.
 
 ```js
 // right
-import { AdiaElement } from '@adia-ai/web-components';
+import { UIElement } from '@adia-ai/web-components/core';
 :where(:scope) { --button-bg: var(--a-primary-bg); }
 
 // wrong
@@ -319,7 +319,6 @@ For component source under `packages/web-components/components/**`, the gate is
 - [css-patterns.md](css-patterns.md) — full @scope + variant/mode CSS architecture
 - [lifecycle-patterns.md](lifecycle-patterns.md) — timers, observers, popovers, listeners
 - [token-contract.md](token-contract.md) — token audit procedure
-- [llm-bridge.md](llm-bridge.md) — extend @adia-ai/llm
 - [module-promotion.md](module-promotion.md) — promote inline → module
 - [anti-patterns.md](anti-patterns.md) — failure-mode catalogue with file:line refs
 - **adia-a2ui** (sibling skill) — generator / corpus / MCP pipeline

package/skills/adia-author/references/lifecycle-patterns.md

@@ -1,13 +1,13 @@
 # Lifecycle Patterns — Listeners, Timers, Observers, Popovers
 
-Deep dive on symmetric `connected()` / `disconnected()` in AdiaUI components. Read when adding any side effect (listener, timer, observer, popover) to a component, or when inheriting from `AdiaFormElement`.
+Deep dive on symmetric `connected()` / `disconnected()` in AdiaUI components. Read when adding any side effect (listener, timer, observer, popover) to a component, or when inheriting from `UIFormElement`.
 
 ## The symmetry rule
 
 Every side effect set up in `connected()` has a matching teardown in `disconnected()`. The teardown is authored at the same time as the setup, not later — if you leave `disconnected()` for tomorrow, tomorrow won't happen.
 
 ```javascript
-class AdiaWidget extends AdiaElement {
+class UIWidget extends UIElement {
   static properties = { /* ... */ };
   static template = () => null;
 
@@ -150,16 +150,16 @@ disconnected() {
 
 **Lesson:** a class must declare `disconnected()` exactly once. If you need to add teardown, edit the existing method. Duplicate method names silently shadow — no error, no warning.
 
-## `AdiaFormElement` — `super` discipline
+## `UIFormElement` — `super` discipline
 
-Form-participating components inherit `ElementInternals` wiring from `AdiaFormElement`. That wiring only works if `super.connected()` and `super.disconnected()` are called:
+Form-participating components inherit `ElementInternals` wiring from `UIFormElement`. That wiring only works if `super.connected()` and `super.disconnected()` are called:
 
 ```javascript
-import { AdiaFormElement } from '../../core/form.js';
+import { UIFormElement } from '../../core/form.js';
 
-class AdiaInput extends AdiaFormElement {
+class UIInput extends UIFormElement {
   static properties = {
-    ...AdiaFormElement.properties,
+    ...UIFormElement.properties,
     placeholder: { type: String, default: '', reflect: true },
   };
 
@@ -296,7 +296,7 @@ Especially important for components that are attached/detached frequently (modal
 - **Inline arrow + `removeEventListener`** — the listener isn't really being removed. Silent leak.
 - **Forgot to create `disconnected()`** — if `connected()` adds side effects, `disconnected()` must exist. No exceptions.
 - **Two `disconnected()` methods in the same class** — the second silently wins; the first's cleanup is lost.
-- **`super.connected()` missing in `AdiaFormElement` subclass** — form participation silently fails.
+- **`super.connected()` missing in `UIFormElement` subclass** — form participation silently fails.
 - **Popover / tooltip never cleaned up** — stays in `document.body` forever.
 - **Observer recreated on every render** — re-observing without disconnecting first leaks observer refs.
 - **Timer fired after component removed** — not cleared in `disconnected()`, fires on a dead component. Can cause null-deref crashes or phantom re-renders.

package/skills/adia-author/references/llm-bridge.md

@@ -1,5 +1,12 @@
 # LLM Bridge extension — @adia-ai/llm
 
+**Superseded 2026-07-18 — `@adia-ai/llm` internals are `adia-llm-internals`'s charter, not
+`adia-author`'s.** That skill's references (`adapter-contract.md`, `streaming-sse.md`,
+`model-registry.md`, `bridge-facade.md`, `browser-proxy-boundary.md`, `add-a-provider.md`)
+are the current, maintained source — this file is kept only as a historical pointer and is
+no longer linked from `adia-author`'s task-shape table or `code-style.md`. Route provider/
+streaming/bridge work to `adia-llm-internals`.
+
 Use when adding a 4th provider, modifying `createAdapter()`, changing the streaming chunk shape, or extending `packages/llm/server.js`.
 
 This reference is about **modifying** the package. For day-to-day consumption (import + call), the README at `packages/llm/README.md` is sufficient.

package/skills/adia-author/references/token-contract.md

@@ -14,7 +14,7 @@ Every component's `.css` file must follow the **two-block @scope** pattern:
 /* Block 1: token declarations on :where(:scope) — zero specificity */
 @scope (my-component-ui) {
   :where(:scope) {
-    --my-bg: var(--a-surface-1);
+    --my-bg: var(--a-bg);
     --my-text: var(--a-fg);
     --my-radius: var(--a-radius-md);
   }
@@ -30,8 +30,8 @@ Every component's `.css` file must follow the **two-block @scope** pattern:
 
   /* Variants override TOKENS, not base styles */
   :scope[variant="danger"] {
-    --my-bg: var(--a-danger-surface);
-    --my-text: var(--a-danger-text);
+    --my-bg: var(--a-danger-bg);
+    --my-text: var(--a-danger-fg);
   }
 }
 ```
@@ -40,7 +40,7 @@ Every component's `.css` file must follow the **two-block @scope** pattern:
 
 1. **Zero raw color values** anywhere in component CSS
    - No `#fff`, `rgb(...)`, `oklch(...)` literals
-   - All colors must reference `--a-chrome-*`, `--a-data-0..9`, `--a-fg*`, `--a-surface-*`, or family tokens (`--a-brand-*`, `--a-primary-*`, etc.)
+   - All colors must reference `--a-chrome-*`, `--a-data-0..9`, `--a-fg*`, `--a-bg-*`, or family tokens (`--a-brand-*`, `--a-primary-*`, etc.)
 2. **Two-block pattern** — token declarations separate from style rules
 3. **Variants override tokens** — never rewrite base styles inside `[variant]` selectors. Change token values; the base styles absorb the change.
 4. **`:where(:scope)`** for token defaults — zero specificity lets consumers override tokens from outside
@@ -75,7 +75,7 @@ Every component's `.css` file must follow the **two-block @scope** pattern:
 4. **Check token usage in parent stylesheet**
 
    ```bash
-   grep -n "--a-chrome\|--a-data\|--a-fg\|--a-surface" \
+   grep -n -- "--a-chrome\|--a-data\|--a-fg\|--a-bg" \
      packages/web-components/components/<name>/*.css
    ```