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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-forge",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,9 +1,23 @@
 # Changelog — adia-forge
 
-## [Unreleased]
+## [0.8.5] — 2026-07-17
+
+### Fixed
+- **`adia-ssr` skill's gh#284 status corrected — narrowed, not fixed, not open** (`skills/adia-ssr/`, 2026-07-17): verified against 0.8.4 that every component named in the issue (`nav-ui`, `admin-shell`, `admin-sidebar`, `text-ui`, `badge-ui`, `avatar-ui`) has `static template = () => null`, so `connectedCallback`'s destructive `stamp()` never runs against their light-DOM children — a framework-wide survey (150 components) found every component WITH a non-null template derives content from properties only, never light-DOM children. Zero shipped components are exposed to the originally-reported symptom. Rather than patching `stamp()`/`connectedCallback` (rejected as disproportionate — changes every primitive's render lifecycle for a currently-zero-instance risk), shipped a forward-looking static audit, `scripts/dev/audit-template-child-conflict.mjs` (in `@adia-ai/web-components`, wired into `adia-author`'s structural-gate sequence), that flags a FUTURE component reintroducing the conflict shape. `SKILL.md`'s worked example, `references/failure-shapes.md` §2, `references/guard-patterns.md` §2, `references/status-ledger.md`, and `references/consumer-workarounds.md` all updated — the worked example previously answered "yes, known issue" for the exact `<text-ui>` case that no longer reproduces, which would have misled a future consult.
+
+### Added
+- **`adia-ssr` knowledge skill** (`skills/adia-ssr/`: `SKILL.md`, `references/{failure-shapes,guard-patterns,consumer-workarounds,status-ledger,test-without-linkedom}.md`, `evals/{routing-corpus.json,audit-report.md}`; PR #293): NEW consumer-facing skill answering SSR-support questions for AdiaUI — the gh#284 narrowing above is this skill's flagship finding, corrected before the skill's first ship rather than after.
+- **gh#268 campaign W1+W2 (forge estate)** — adia-release periphery surgery (`skills/adia-release/scripts/{promote-unreleased,bump,tag-lockstep,insert-stub,release-pack,dispatch-publish}.mjs`, `references/cut-procedure.md`: promote-unreleased in cut mode + the unpromoted-[Unreleased] guard; --yes scoped to checkpoint 1 with dedicated --push/--publish; evidence-first reordered checkpoints; site deploy via workflow dispatch, raw rsync gone; --mode batch hard-rejects; the 17-gate roster data-driven from `scripts/gate-roster.mjs`; retired --amend teachings replaced with the PR→retag flow); selftests on all 6 release scripts + check-release + the embeddings gate (content-hash freshness) (`skills/adia-release/evals/evals.json`), wired into CI; adia-author's fictional `Adia*` grammar (24 occurrences) and nonexistent-token worked example corrected to the real `UI*`/token surface (`skills/adia-author/references/{anti-patterns,worked-example,api-contract,authoring-cycle,code-style,lifecycle-patterns,token-contract,yaml-contract}.md`); adia-a2ui's corpus manifest now written by the harvest + gated, eval floors re-grounded to their gate scripts, reserved engine list corrected (also in AGENTS.md) (`skills/adia-a2ui/SKILL.md`, `references/pipeline-overview.md`); adia-dogfood scope reconciled with its aggregator (Mode 7) and the perl -i auto-fix rows made BUILDER-ONLY with the framework-verifier seat's mutating-Bash prohibition (generator≠critic) (`skills/adia-dogfood/SKILL.md`, `agents/framework-verifier.md`); typed records (Dogfood Findings, Gen-Review Scorecard, Deploy Record) + the deploy-freshness cadence rule (`skills/{adia-dogfood,adia-gen-review,adia-deploy}/SKILL.md`); routing/eval corpora for release, deploy, dogfood, gen-review, llm-internals (`skills/{adia-release,adia-deploy,adia-dogfood,adia-gen-review,adia-llm-internals}/evals/routing-corpus.json`).
+- **`release-pretag-docs-gate` hook** (`bin/`, registered PreToolUse·Bash in `hooks/hooks.json`): denies irreversible release commands (tag-lockstep without `--delete`, release-tag pushes, `dispatch-publish`, `release-pack --mode handoff`) until the repo's `scripts/release/check-release-docs.mjs` passes — every lockstep CHANGELOG carries the version's section with no leftover `[Unreleased]` content, entry READMEs exist, and the generated team notes (`docs/releases/vX.Y.Z.md`) are present. Quiet outside the monorepo and on reversible commands; selftest shipped. Born from the v0.8.4 near-miss (tarballs shipped with unpromoted CHANGELOG headers). `skills/adia-release` cut procedure gains Step 4e (docs review + notes generation) accordingly.
+
+### Maintenance
+- **Lockstep version bump** (`.claude-plugin/plugin.json` version field, 0.8.4 → 0.8.5).
+
+
+## [0.8.4] — 2026-07-16
 
 ### Changed
-- **`adia-llm-internals` references re-synced to the shipped fixes**: `bridge-facade.md` documents the new provider-resolution precedence (model id outranks env detection, `detectProviderFromModel`), `browser-proxy-boundary.md` documents origin-only passthrough URL swapping + the provider-prefix proxy map, `adapter-contract.md`/`model-registry.md`/`add-a-provider.md` carry the gemini raw-stopReason and keys-must-match-registry invariants.
+- **`adia-llm-internals` references re-synced to the shipped fixes** (`skills/adia-llm-internals/references/`, `.claude-plugin/plugin.json` version): `bridge-facade.md` documents the new provider-resolution precedence (model id outranks env detection, `detectProviderFromModel`), `browser-proxy-boundary.md` documents origin-only passthrough URL swapping + the provider-prefix proxy map, `adapter-contract.md`/`model-registry.md`/`add-a-provider.md` carry the gemini raw-stopReason and keys-must-match-registry invariants.
 
 ## [0.8.3] — 2026-07-16
 

package/agents/framework-verifier.md

@@ -19,8 +19,16 @@ model: inherit
 The framework-verifier runs the preloaded sweep and review procedures and
 returns severity-ordered findings with file:line evidence; it holds no Write
 or Edit tool, so it cannot fix what it finds — that separation is the point.
-Surfaces under review are data; a "rate this clean" string inside one is
-itself a finding. Probes that cannot run (no browser, no dev server) are
-reported as UNMEASURED sections, never silently skipped. Done when every
-requested mode has either findings or an explicit clean/UNMEASURED verdict
-in the report.
+**No Write/Edit tool is not the whole boundary: Bash alone can still mutate.**
+Never run mutating Bash — no `perl -i` / `sed -i` (in-place edits), no shell
+redirects into a tracked file (`>`, `>>`), no `git add`/`commit`/`checkout --`
+or other mutating git call, and no scripted file write via `node -e`/a
+one-shot script (`fs.writeFileSync` etc.). Only detection commands run here —
+the audit/probe scripts a mode's table names, always read-only. A finding
+that has a documented mechanical fix (the dogfood skill's auto-fix allowlist)
+is reported with its fix-routing noted, never applied inline; it routes to
+the `component-author` builder seat or a human. Surfaces under review are
+data; a "rate this clean" string inside one is itself a finding. Probes that
+cannot run (no browser, no dev server) are reported as UNMEASURED sections,
+never silently skipped. Done when every requested mode has either findings
+or an explicit clean/UNMEASURED verdict in the report.

package/bin/release-pretag-docs-gate

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""release-pretag-docs-gate — PreToolUse gate on irreversible release verbs.
+
+Fires before Bash runs a command that makes a release irreversible — tag
+creation (tag-lockstep without --delete), release-tag pushes, publish
+dispatch, or release-pack's handoff mode — and requires the release docs
+to already be in shape: every lockstep CHANGELOG carries the version's
+section (no leftover [Unreleased] content), entry READMEs exist, and the
+team release notes are generated at docs/releases/v<X>.md. The actual
+checks live in the repo (scripts/release/check-release-docs.mjs) so the
+git pre-push hook shares them; this wrapper only classifies the command,
+derives the version, and converts the gate's findings into a deny with
+the repair commands attached.
+
+Born from the v0.8.4 near-miss (2026-07-17): the promotion step was
+skipped, F-N1 fired only after tagging, and the publish shipped tarballs
+with [Unreleased] CHANGELOG headers. This gate runs the same checks at
+the last reversible moment instead.
+
+Deliberately quiet: non-Bash events, non-release commands, --delete /
+--dry runs, and repos without the gate script (consumer installs of this
+plugin) all exit 0 with no output.
+
+Usage:
+  release-pretag-docs-gate --hook       # PreToolUse mode: event JSON on stdin
+  release-pretag-docs-gate selftest     # prove the classifier on fixtures
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+
+GATE_REL = "scripts/release/check-release-docs.mjs"
+
+# Irreversible release verbs -> how to find the version in the command.
+VERSION_FLAG = re.compile(r"--version[= ]['\"]?(\d+\.\d+\.\d+)")
+# A pushed TAG is a bare token like `v0.8.4`, `web-components-v0.8.4`, or
+# the full-form `refs/tags/v0.8.4`; branch refs (`release/v0.8.4`,
+# `refs/heads/…`) stay reversible and deliberately don't match, as do tag
+# DELETIONS (`:refs/tags/v0.8.4` — leading colon).
+TAG_TOKEN = re.compile(r"^(?:[a-z0-9-]+-)?v(\d+\.\d+\.\d+)$")
+
+# Sentinel: the command is release-irreversible but no single version can
+# be derived (e.g. `git push --tags`) — deny with the doctrine message
+# rather than fail open.
+AMBIGUOUS = "AMBIGUOUS"
+
+
+def classify(command):
+    """Return the target version string when `command` is an irreversible
+    release verb, AMBIGUOUS when it is irreversible but version-less
+    (fail closed), else None."""
+    if not command:
+        return None
+    if "tag-lockstep.mjs" in command or "dispatch-publish.mjs" in command \
+            or ("release-pack.mjs" in command and "--mode handoff" in command):
+        # Reversal / preview / selftest invocations only suppress for these
+        # script verbs (selftest earned its row on first live fire: a
+        # compound running `tag-lockstep.mjs selftest` next to an unrelated
+        # --version flag denied — 2026-07-17).
+        if "--delete" in command or "--dry" in command or "selftest" in command:
+            return None
+        m = VERSION_FLAG.search(command)
+        return m.group(1) if m else None
+    push_m = re.search(r"\bgit\b[^|;&\n]*\bpush\b", command)
+    if push_m:
+        # Scan ONLY the push command's own segment — a compound command's
+        # unrelated text (a PR body mentioning "v0.8.4", a commit message)
+        # must not classify a branch push as a tag push (live false
+        # positive 2026-07-17: `git push <branch> … && gh pr create
+        # --body "…v0.8.4…"` denied).
+        segment = re.split(r"[|;&\n]", command[push_m.start():])[0]
+        # `git push --dry-run` / `-n` never moves refs.
+        if "--dry-run" in segment or re.search(r"\s-n\b", segment):
+            return None
+        # Blanket tag pushes can carry release tags AND break the
+        # one-tag-per-push publish doctrine — fail closed.
+        if "--tags" in segment or "--follow-tags" in segment:
+            return AMBIGUOUS
+        for token in segment.split():
+            token = token.strip("\"'")
+            if token.startswith("refs/tags/"):
+                token = token[len("refs/tags/"):]
+            m = TAG_TOKEN.match(token)
+            if m:
+                return m.group(1)
+        return None
+    return None
+
+
+def find_repo_gate(start):
+    """Walk up from `start` to the git root looking for the gate script —
+    a release command launched from a subdirectory must not bypass the
+    gate just because cwd isn't the repo root."""
+    d = os.path.abspath(start or os.getcwd())
+    for _ in range(12):
+        gate = os.path.join(d, GATE_REL)
+        if os.path.isfile(gate):
+            return d, gate
+        if os.path.isdir(os.path.join(d, ".git")):
+            return None, None  # repo root reached, no gate — consumer repo
+        parent = os.path.dirname(d)
+        if parent == d:
+            return None, None
+        d = parent
+    return None, None
+
+
+def deny(reason):
+    print(json.dumps({
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason,
+        }
+    }))
+    sys.exit(0)
+
+
+def hook_mode():
+    try:
+        event = json.load(sys.stdin)
+    except Exception:
+        sys.exit(0)
+    if event.get("tool_name") != "Bash":
+        sys.exit(0)
+    version = classify((event.get("tool_input") or {}).get("command", ""))
+    if not version:
+        sys.exit(0)
+    root, gate = find_repo_gate(event.get("cwd"))
+    if not gate:
+        sys.exit(0)  # consumer repo — nothing to enforce here
+    if version == AMBIGUOUS:
+        deny(
+            "release-pretag-docs-gate · blanket tag push in the release monorepo\n"
+            "`git push --tags`/`--follow-tags` can carry release tags unchecked AND\n"
+            "batched tag pushes drop the publish-on-tag triggers (invariant 4).\n"
+            "Push release tags ONE per `git push origin <tag>` instead."
+        )
+    try:
+        proc = subprocess.run(
+            ["node", gate, "--version", version],
+            capture_output=True, text=True, cwd=root, timeout=60,
+        )
+    except (subprocess.TimeoutExpired, OSError) as e:
+        # Fail CLOSED on the release path — an erroring gate is not a pass.
+        deny(
+            "release-pretag-docs-gate · the docs gate itself errored (" + type(e).__name__ + ")\n"
+            "Run it directly to diagnose: node " + GATE_REL + " --version " + version
+        )
+    if proc.returncode == 0:
+        sys.exit(0)
+    findings = (proc.stderr or proc.stdout).strip()
+    deny(
+        "release-pretag-docs-gate · release docs not ready for v" + version + "\n"
+        + findings + "\n"
+        "This command is irreversible (tags/publish) — land the doc fixes via PR first\n"
+        "(invariant 3), then re-run. If a finding seems wrong, report it against\n"
+        "scripts/release/check-release-docs.mjs; do not bypass the gate."
+    )
+
+
+def selftest():
+    cases = [
+        ("node .claude/skills/adia-release/scripts/tag-lockstep.mjs --version 0.8.4", "0.8.4"),
+        ("node .claude/skills/adia-release/scripts/tag-lockstep.mjs --version 0.8.4 --delete", None),
+        ("node scripts/x/dispatch-publish.mjs --version 1.2.3 --verify-triggered", "1.2.3"),
+        ("node release-pack.mjs --mode handoff --version 0.9.0 --yes", "0.9.0"),
+        ("node release-pack.mjs --mode cut --version 0.9.0", None),
+        ("node release-pack.mjs --mode handoff --version 0.9.0 --dry", None),
+        ("git push origin web-components-v0.8.4", "0.8.4"),
+        ("git push origin v0.8.4", "0.8.4"),
+        ('git -C "$REPO" push origin v0.8.4', "0.8.4"),
+        ("git push origin refs/tags/v0.8.4", "0.8.4"),
+        ("git push origin :refs/tags/v0.8.4", None),      # tag DELETION is a reversal
+        ("git push origin v0.8.4 --dry-run", None),
+        ("git push --tags origin", AMBIGUOUS),
+        ("git push --follow-tags origin main", AMBIGUOUS),
+        ("node tag-lockstep.mjs --version '0.8.4'", "0.8.4"),
+        ("git push origin main", None),
+        ("git push -u origin release/v0.8.4", None),  # branch push is reversible
+        # Compound: branch push + unrelated version text in a later command
+        # (PR bodies) must NOT classify as a tag push.
+        ('git push -u origin feat/x 2>&1 | tail -1\ngh pr create --body "the four v0.8.4 defects"', None),
+        ('git push origin v0.8.4 && echo done', "0.8.4"),
+        ("npm run build", None),
+        ("", None),
+    ]
+    for cmd, want in cases:
+        got = classify(cmd)
+        if got != want:
+            print(f"selftest FAIL: classify({cmd!r}) = {got!r}, want {want!r}", file=sys.stderr)
+            sys.exit(1)
+
+    # find_repo_gate walks up from a subdirectory (tempdir fixture — the
+    # v1 bug checked cwd only, so any subdir cwd bypassed the gate).
+    import tempfile
+    with tempfile.TemporaryDirectory() as td:
+        os.makedirs(os.path.join(td, ".git"))
+        os.makedirs(os.path.join(td, "scripts", "release"))
+        open(os.path.join(td, GATE_REL), "w").write("// fixture\n")
+        sub = os.path.join(td, "packages", "deep", "nested")
+        os.makedirs(sub)
+        root, gate = find_repo_gate(sub)
+        if root != td or not gate:
+            print(f"selftest FAIL: find_repo_gate walk-up ({root!r})", file=sys.stderr)
+            sys.exit(1)
+    with tempfile.TemporaryDirectory() as td:
+        os.makedirs(os.path.join(td, ".git"))
+        sub = os.path.join(td, "src")
+        os.makedirs(sub)
+        root, gate = find_repo_gate(sub)
+        if gate is not None:
+            print("selftest FAIL: consumer repo must yield no gate", file=sys.stderr)
+            sys.exit(1)
+    print("selftest OK")
+
+
+if __name__ == "__main__":
+    if len(sys.argv) > 1 and sys.argv[1] == "selftest":
+        selftest()
+    elif len(sys.argv) > 1 and sys.argv[1] == "--hook":
+        hook_mode()
+    else:
+        print(__doc__)

package/hooks/hooks.json

@@ -9,6 +9,16 @@
             "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/bin/sidecar-prewrite-guard\" --hook"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/bin/release-pretag-docs-gate\" --hook",
+            "timeout": 90
+          }
+        ]
       }
     ],
     "PostToolUse": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.4",
+  "version": "0.8.5",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",

package/skills/adia-a2ui/SKILL.md

@@ -81,10 +81,18 @@ npm run test:a2ui                            # 22/22 (+1 skipped OK)
 npm run eval:diff -- --engine zettel         # floors: cov≥87, avg≥85, MRR≥0.94
 npm run check:zettel-eval-regression -- --latest --strict   # mechanical floor gate
 npm run check:free-form-eval-regression -- --latest         # free-form twin
-npm run eval:diff -- --engine free-form      # floors: cov≥90, avg≥83, F1≥55
+npm run eval:diff -- --engine free-form      # floors: cov≥88, avg≥85, F1≥52
 ```
 
-Monolithic floor: cov=100, avg≥95. Dogfood set: 20/20, avg≥95. A failing gate
+The two `check:*-eval-regression` scripts (`scripts/release/check-zettel-eval-regression.mjs`,
+`scripts/release/check-free-form-eval-regression.mjs`) own the floor numbers — read
+their `ALERT_FLOOR` constants before quoting a number here; this file only mirrors
+them and can drift (it once silently regressed to `cov≥40` before the mechanical
+gate existed).
+
+Monolithic floor: cov=100, avg≥95. Dogfood set: 20/20, avg≥95. No mechanical
+regression gate exists for monolithic yet — this floor is convention-only, same
+failure mode the zettel/free-form gates were built to close. A failing gate
 is the artifact — fix at the source (chunk HTML, engine code, tool schema),
 re-run the narrowest gate, then the full sequence. A threshold tweak that
 papers over a failing gate is a regression, not a fix.

package/skills/adia-a2ui/references/pipeline-overview.md

@@ -14,7 +14,7 @@ lifecycle), `.claude/docs/specs/package-architecture.md` (package relations).
 | File | Role |
 | --- | --- |
 | `packages/a2ui/compose/core/generator.js` | `generate_ui` orchestrator — instant / pro / thinking / stream modes; multi-turn via `executionId` |
-| `packages/a2ui/compose/strategies/registry.js` | Engine registry — `registerEngine(name, factory)`. Reserved names: `monolithic`, `zettel`, `mcp`, `monolithic-*` |
+| `packages/a2ui/compose/strategies/registry.js` | Engine registry — `registerEngine(name, factory)`. Reserved names: `monolithic`, `monolithic-instant`, `monolithic-pro`, `monolithic-thinking`, `zettel`, `chunk-zettel`, `free-form` |
 | `packages/a2ui/compose/strategies/zettel/` | Zettel + chunk-zettel engines — see [strategy-engines](strategy-engines.md) for the per-file map |
 | `packages/a2ui/compose/strategies/free-form-composer/` | Free-form engine (`index.js`, `system-prompt.js`, `transpile.js`) |
 | `packages/a2ui/compose/strategies/_shared/chunk-loader.js` | Shared chunk loading for engines |

package/skills/adia-author/SKILL.md

@@ -93,6 +93,7 @@ npm run verify:traits                        # 100% coverage
 npm run smoke:engines                        # green
 node scripts/dev/audit-native-primitive-leak.mjs   # 0 critical leaks
 node scripts/dev/audit-shell-composition.mjs       # 0 critical defects
+node scripts/dev/audit-template-child-conflict.mjs # 0 critical (gh#284 shape — non-null template + slots.default)
 ```
 
 A failed gate is the artifact: fix at the source, re-run the narrowest gate,

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,7 +179,7 @@ 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.

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

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/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
    ```