@adia-ai/adia-ui-factory 0.8.48 → 0.8.51

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.48",
+  "version": "0.8.51",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework \u2014 orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.48",
+  "version": "0.8.51",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "adia-gen-ui": {
       "command": "npx",
-      "args": ["-y", "@adia-ai/mcp@0.8.48", "gen-ui"]
+      "args": ["-y", "@adia-ai/mcp@0.8.51", "gen-ui"]
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog — adia-ui-kit-factory
 
+## [0.8.51] — 2026-08-24
+
+### Added
+- Hermes + Pi external-distribution manifests (gh#1954) — `plugin.yaml` +
+  `__init__.py` + `hermes-mcp.yaml` (Hermes) and `prompts/*.md` + a `"pi"`
+  field in `package.json` (Pi), derived from `.claude-plugin/plugin.json` +
+  `skills/` + `commands/` + `.mcp.json` via `npm run
+  build:harness-manifests` (`check:harness-manifests-fresh` gates
+  freshness). Additive: the Claude Code plugin surface is unchanged.
+  **MCP caveat, not parity:** Hermes MCP is user-level config — merge the
+  generated `hermes-mcp.yaml` into `~/.hermes/config.yaml` by hand. Pi core
+  has no native MCP — the `adia-gen-ui` server only reaches Pi through the
+  third-party `pi-mcp-adapter` reading this plugin's `.mcp.json` unmodified.
+  See the README's "Non-Claude harnesses" section before promising Pi/Hermes
+  parity for this plugin's headline MCP-wiring feature.
+
+### Maintenance
+- **`.codex-plugin/` touched in this release window** (1 file(s), e.g. `.codex-plugin/plugin.json`) — carried by the entries above.
+- **`scripts/` touched in this release window** (2 file(s), e.g. `scripts/adia-contract-check.mjs`) — carried by the entries above.
+
+## [0.8.50] — 2026-08-23
+
+### Maintenance
+- **Lockstep bump riding the v0.8.50 cut** (`scripts/release/check-lockstep.mjs`); the headline v0.8.50 work ships in @adia-ai/web-components (prose/verse sheet removal gh#1885 / PR #1918, input/search fill-default posture gh#1856 — see `packages/web-components/CHANGELOG.md#0850--2026-08-23`). Package-local changes are listed below.
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`.codex-plugin/` touched in this release window** (1 file(s), e.g. `.codex-plugin/plugin.json`) — carried by the entries above.
+
+### Docs
+- **`references/` + `skills/` docs refreshed for the release window** — `component-model.md` and `spa-architecture.md` plus the `find-unused` (`recon-and-audits.md`), `host-wiring` (`SKILL.md`, `mode-wiring-detail.md`), and `table-composition` (`base-table.md`) skill references updated to current framework contracts (incl. the gh#1918 `[prose]`/`[verse]` removal and gh#1856 fill-default posture).
+
 ## [0.8.48] — 2026-08-23
 
 ### Added

package/README.md

@@ -98,7 +98,7 @@ surface-qa-agent) · `component-model.md` · the `references/contracts/` twins.
 
 ## MCP
 
-`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.48` (tool SoT:
+`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.51` (tool SoT:
 `packages/gen-ui/mcp/TOOLS.md` — the `gen-ui` section; stability rule in
 `references/contracts/`; pin lives in `.mcp.json` — `check:plugin-count-claims`
 guards this README copy against it). The server is `adia-mcp gen-ui`,
@@ -108,6 +108,35 @@ before either ever published; the pin name and the `mcpServers` key flipped
 in the P7 release commit per the 2026-08-14 config-key ruling — new entries
 for the other subcommands use `adia-protocol` / `adia-factory`).
 
+## Non-Claude harnesses
+
+External install beyond Claude Code (AGENTS.md's own "Non-Claude harnesses"
+section carries the shared degradation table this summarizes). **The MCP
+story is the one place neither non-Claude harness matches Claude Code's
+plug-and-play install** — read this section before promising Pi/Hermes
+support for this plugin specifically, since its whole value proposition is
+wiring the `adia-gen-ui` MCP server.
+
+- **Codex** (gh#1888): `.codex-plugin/plugin.json` + per-skill
+  `agents/openai.yaml`, derived; `mcpServers` points at the same
+  `.mcp.json` Claude Code uses. No manifest key for hooks/commands/agents —
+  a command degrades to invoking its skill directly.
+- **Hermes** (gh#1954): `plugin.yaml` + `__init__.py` at this package's
+  root — point Hermes's plugin loading at the installed
+  `node_modules/@adia-ai/adia-ui-factory` directory. **MCP is user-level
+  config in Hermes, not a plugin field** — merge the generated
+  `hermes-mcp.yaml` into your own `~/.hermes/config.yaml` by hand; there is
+  no automatic wiring. No hooks/agents surface.
+- **Pi** (gh#1954): discovered via the `pi-package` keyword and the `"pi"`
+  field in `package.json`; `prompts/*.md` gives every `/command` a genuine
+  Pi prompt template. **Pi core has no native MCP support at all** — the
+  `adia-gen-ui` server only reaches Pi through the third-party
+  [`pi-mcp-adapter`](https://pi.dev) package, which reads this plugin's
+  `.mcp.json` unmodified (same shape, no substitution needed). Install that
+  adapter first; without it, this plugin's headline feature — the a2ui MCP
+  wiring — silently does nothing on a stock Pi install. No hooks/agents
+  surface.
+
 ## Requirements
 
 Python 3 (hook) + Node 22. Installs standalone in consumer repos (no monorepo

package/__init__.py

@@ -0,0 +1,97 @@
+"""adia-ui-kit-factory — generated by scripts/build/harness-manifests.mjs. Do not edit."""
+import os
+
+_HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def register(ctx):
+    ctx.register_skill(
+        name="app-audit",
+        path=os.path.join(_HERE, "skills", "app-audit", "SKILL.md"),
+        description="Diagnose an EXISTING AdiaUI consumer codebase before touching it — recon, classify manifest/version/spec/capability drift, root-cause a DRIFT-caused wrong-output symptom via four-layer triage (skill/codebase/substrate/spec) instead of patching the surface. Use for \"audit this UI\", \"is this up to date\", \"what should we migrate\", \"doesn't match the reference\", \"looks unstyled/off-brand\", or a suspected-drifted @adia-ai/* consumer's version health check. Produces a ranked, evidence-cited report; hands CONFIRMED sweeps to a builder. NOT greenfield planning (app-planning) or confirmed migration (app-migration); NOT a live blank-screen/console-error check (surface-qa) or chart-specific render behavior (chart-selection); NOT a duplication review (project-scaffolding).",
+    )
+    ctx.register_skill(
+        name="app-migration",
+        path=os.path.join(_HERE, "skills", "app-migration", "SKILL.md"),
+        description="Migrates a consumer adia-ui app. Use when asked to \"migrate to v0.X\", \"upgrade @adia-ai/web-components\", \"fix breaking changes\", \"sweep deprecated attributes\", port @agent-ui-kit/foreign code, or change SPA↔SSR mode — grep audit, mechanical sweep, verify gates. NOT for authoring the MIGRATION GUIDE or cutting releases (package-release, forge plugin).",
+    )
+    ctx.register_skill(
+        name="app-planning",
+        path=os.path.join(_HERE, "skills", "app-planning", "SKILL.md"),
+        description="Cold-start router for adia-ui consumer-app work. Use when the user asks to \"build/start an adia-ui app\", \"add a surface\", \"orient in this repo\" — run FIRST, also on any task whose mode/shape/shell is undecided — classifies four axes on cited signals, emits an Orientation Record, routes onward. NOT for framework-monorepo internals (adia-ui-forge).",
+    )
+    ctx.register_skill(
+        name="chart-selection",
+        path=os.path.join(_HERE, "skills", "chart-selection", "SKILL.md"),
+        description="Which adia-ui component renders a chart, graph, sparkline, gauge, or heatmap, and how to wire its data/legend/theming. Use for \"add a chart\", \"show a graph\", \"visualize this data\", \"add a sparkline/gauge/heatmap\", or \"wire a chart legend\". NOT for the surrounding screen (screen-composition), color tokens (token-selection), or data fetching (data-wiring).",
+    )
+    ctx.register_skill(
+        name="data-wiring",
+        path=os.path.join(_HERE, "skills", "data-wiring", "SKILL.md"),
+        description="Data, state & hydration in an adia-ui app. Use for \"wire up the data\" / \"manage state\" / \"hydrate the island\": pattern choice (signals · shared app store · Service/Command · DataClient · property-API · data-*), hydration per mode (SPA/SSR/hybrid). NOT for host bootstrap/registration (host-wiring) or screen markup (screen-composition).",
+    )
+    ctx.register_skill(
+        name="domain-planning",
+        path=os.path.join(_HERE, "skills", "domain-planning", "SKILL.md"),
+        description="Reasons through a PRD, spec, mockup, schema, or role/user-story BEFORE any UI is chosen — resolves intent, domain entities, roles, tasks, and decisions, then scores a semantic wireframe against the gate dimensions. Use when the input is spec-shaped (not a signed-off wireframe) and no Domain Plan exists yet for it. Preloaded by app-planning-agent; produces the Orientation Record's Domain Plan block. NOT for composing the UI itself (screen-composition) or classifying rendering mode/shape/shell (app-planning).",
+    )
+    ctx.register_skill(
+        name="find-unused",
+        path=os.path.join(_HERE, "skills", "find-unused", "SKILL.md"),
+        description="Finds what a non-breaking @adia-ai upgrade shipped that this app never picked up — the opt-in layers nothing imports, the local workarounds a fixed bug made redundant, retired enum values still sitting in stored state, and the fixes that never reached MIGRATION.md. Use after \"we bumped and nothing broke\", \"what are we missing from 0.8.x\", \"are we actually using what we ship\", \"why is [scale]/[theme] doing nothing\", or when a PATCH span needs adoption rather than repair. NOT for breaking-change repair (app-migration); NOT for a first-time install (adia-scaffold); NOT for diagnosing a broken surface (app-audit).",
+    )
+    ctx.register_skill(
+        name="gen-ui-wiring",
+        path=os.path.join(_HERE, "skills", "gen-ui-wiring", "SKILL.md"),
+        description="Authors a runtime generative-UI experience on the a2ui runtime — mounts a2ui-root/gen-root, wires generate_ui + data resolvers, grounds generation in a corpus (harvest chunks from our own pages, point retrieval at it). Use when END USERS generate UI at runtime. NOT for one-shot 'generate UI for X' screen asks (screen-composition), chat features (llm-wiring), or pipeline/MCP tool ops (adia-forge's a2ui-maintenance).",
+    )
+    ctx.register_skill(
+        name="host-wiring",
+        path=os.path.join(_HERE, "skills", "host-wiring", "SKILL.md"),
+        description="Wires an adia-ui app's host — picks SPA/SSR/hybrid, then that mode's registration, CSS cascade, routing ownership. Use for \"wire the host\", \"set up index.html\", unstyled or non-upgrading elements, \"HTMLElement is not defined\" under Next/Nuxt/SvelteKit/Astro. NOT for screen UI (screen-composition), data/state (data-wiring), app layout (project-scaffolding).",
+    )
+    ctx.register_skill(
+        name="llm-wiring",
+        path=os.path.join(_HERE, "skills", "llm-wiring", "SKILL.md"),
+        description="The @adia-ai/llm client contract — chat/streamChat streaming, StreamChunk, smart-proxy vs passthrough key security, chat-shell wiring. Use when adding a chat box or any LLM feature to an adia-ui app. NOT for runtime gen-UI (gen-ui-wiring), one-shot intent→screen composition (screen-composition), or @adia-ai/llm internals (adia-forge's llm-client-maintenance).",
+    )
+    ctx.register_skill(
+        name="pattern-catalog",
+        path=os.path.join(_HERE, "skills", "pattern-catalog", "SKILL.md"),
+        description="Index of adia-ui's pre-assembled surfaces — hundreds of patterns and template screens (auth, registration, onboarding, settings, dashboards) — see references/pattern-index.md for the current count. Use BEFORE composing any screen from primitives, or when asked \"is there an existing pattern/template for X\", \"start from a pattern\", \"what patterns exist\". Answers and points at source — NOT for composing new UI (screen-composition), shell chrome (shell-selection), or authoring new patterns (primitive-authoring).",
+    )
+    ctx.register_skill(
+        name="project-scaffolding",
+        path=os.path.join(_HERE, "skills", "project-scaffolding", "SKILL.md"),
+        description="Lays out an adia-ui app's on-disk structure — picks the project shape (single-surface / rollup / shared-foundation) and page form, scaffolds via scripts/adia-scaffold, gates on the structure rubric. Use for \"scaffold an app\", \"add a page/surface/component\" WHEN mode/shape are already decided, \"audit its structure\". If mode/shape/shell are still undecided, app-planning classifies first. NOT for the UI inside a screen (screen-composition) or host wiring (host-wiring).",
+    )
+    ctx.register_skill(
+        name="screen-composition",
+        path=os.path.join(_HERE, "skills", "screen-composition", "SKILL.md"),
+        description="Composes adia-ui screens from light-DOM catalog primitives — discovers tags/props via the a2ui MCP, themes via --a-* tokens. Use when asked to build or 'generate UI for' a screen, page, form, dashboard, or nav pattern, or when a PRD/spec/mockup needs UI. NOT for shell chrome (shell-selection), host wiring (host-wiring), runtime gen-UI (gen-ui-wiring).",
+    )
+    ctx.register_skill(
+        name="shell-selection",
+        path=os.path.join(_HERE, "skills", "shell-selection", "SKILL.md"),
+        description="Picks and composes an adia-ui page-chrome shell (@adia-ai/web-modules): admin (app frame), chat (LLM), editor (canvas+panes), simple (marketing/error), or embed. Use when asked to \"use a shell\", \"sidebar + topbar layout\", \"embed this surface\", or on shell markup debugging. NOT for screens inside it (screen-composition) or host/SSR wiring (host-wiring).",
+    )
+    ctx.register_skill(
+        name="surface-qa",
+        path=os.path.join(_HERE, "skills", "surface-qa", "SKILL.md"),
+        description="Browser-QA gate for a CONSUMER app's adia-ui surfaces — renders headless with zero console/page errors, non-zero bounding boxes, and a screenshot actually read, plus AdiaUI a11y checks. Use when shipping a surface, on \"verify/QA this page\" or a page that renders blank/empty, or when \"tests pass\" is the only evidence. NOT for composing/fixing UI (screen-composition), structural lint (adia-lint hook), or the framework repo's own dogfood/ demo-page sweep (forge's demo-audit).",
+    )
+    ctx.register_skill(
+        name="table-composition",
+        path=os.path.join(_HERE, "skills", "table-composition", "SKILL.md"),
+        description="Answers how to display/organize tabular data with table-ui: contained vs uncontained chrome, [raw] (consumer-owned body, a separate axis), opt-in striped rows, and resize/sort defaults that flip between JS .columns and declarative col-def forms, plus inline-edit-grid and tree/hierarchical-row patterns. Use for \"how do I show a table\", \"add sorting/filtering\", \"make this table striped\", \"columns aren't resizable\", \"card vs bare table\", \"editable/spreadsheet grid\", \"tree table / nested rows\", \"huge list of rows\". NOT for composing the surrounding screen (screen-composition), data wiring (data-wiring), OTHER non-table patterns (pattern-catalog), or 1000+-row virtualized lists (list-window-ui).",
+    )
+    ctx.register_skill(
+        name="token-selection",
+        path=os.path.join(_HERE, "skills", "token-selection", "SKILL.md"),
+        description="Answers which color token/role an adia-ui surface should use — role grammar, pairing laws, state families, the --a-* alias layer. Use when asked \"which token for this background/text/hover/border\" or \"--a-* or --md-sys-color-*\". ANSWERS only. NOT for composing the screen (screen-composition) or designing/verifying palettes (framework-side).",
+    )
+    ctx.register_skill(
+        name="wave-coordination",
+        path=os.path.join(_HERE, "skills", "wave-coordination", "SKILL.md"),
+        description="Team-pattern mechanics for a multi-screen build under ui-architect's GEAR 2 — who merges parallel screen-composition-agent branches and when, PR/branch mechanics, shared-file conflict rules for shared-foundation shapes, and how to size a wave. Use when planning or running a GEAR-2 dispatch: \"how do two parallel screen-composition-agent branches come back together\", \"who merges\", \"how big should a wave be\", \"what happens when two screens touch the same shared file\". NOT for picking a project's shape (project-scaffolding, which this skill's conflict rules build on) or composing one screen (screen-composition).",
+    )

package/hermes-mcp.yaml

@@ -0,0 +1,10 @@
+# Generated from .mcp.json — Hermes MCP is user-level config,
+# not a plugin manifest field. Merge this fragment into your own
+# ~/.hermes/config.yaml (see this plugin's README, "Non-Claude harnesses").
+mcp_servers:
+  adia-gen-ui:
+    command: "npx"
+    args:
+      - "-y"
+      - "@adia-ai/mcp@0.8.51"
+      - "gen-ui"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-factory",
-  "version": "0.8.48",
+  "version": "0.8.51",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "keywords": [
     "adia-ui",
@@ -8,7 +8,8 @@
     "gen-ui",
     "web-components",
     "app-authoring",
-    "consumer"
+    "consumer",
+    "pi-package"
   ],
   "license": "MIT",
   "author": {
@@ -18,15 +19,23 @@
   "bugs": {
     "email": "kim.granlund@adia.ai"
   },
+  "pi": {
+    "skills": ["./skills"],
+    "prompts": ["./prompts"]
+  },
   "files": [
     ".claude-plugin",
     ".codex-plugin",
     "skills",
     "agents",
     "commands",
+    "prompts",
     "references",
     "scripts",
     "hooks",
+    "plugin.yaml",
+    "__init__.py",
+    "hermes-mcp.yaml",
     ".mcp.json",
     "README.md",
     "CHANGELOG.md",

package/plugin.yaml

@@ -0,0 +1,4 @@
+name: "adia-ui-kit-factory"
+version: "0.8.51"
+description: "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation."
+manifest_version: 1

package/prompts/app-audit.md

@@ -0,0 +1,14 @@
+---
+description: "Probe this repo's adia-ui project context — declared vs installed versions, rendering-mode/framework signals, shells in use, theming knobs, MCP pin, monorepo misroute flag."
+argument-hint: "[dir]"
+---
+
+Probe the project context. **$ARGUMENTS**
+
+Run `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/adia-info" $ARGUMENTS` and present
+the JSON as a short read: each field with the signal it derived from and
+the decision it drives (screen-composition §Current project context carries the
+field→decision table). An `installedVersion` that is null or mismatched vs
+`adiaPackages` means `npm install` before trusting anything else;
+`isFrameworkMonorepo: true` means this is framework territory — route to
+the adia-ui-forge plugin, not this one.

package/prompts/app-migration.md

@@ -0,0 +1,15 @@
+---
+description: "Migrate consumer code across @adia-ai versions (or port a foreign codebase to adia-ui) — guide-driven audit, per-cluster consent, verify gates, Migration Report."
+argument-hint: "[target version]"
+---
+
+Migrate this codebase. **$ARGUMENTS**
+
+Invoke **`app-migration`**: read the shipped guide for the span
+(`node_modules/@adia-ai/web-components/MIGRATION.md` — install/upgrade the
+target version first so the guide covers it; monorepo canon:
+`.claude/docs/MIGRATION GUIDE.md`), audit every breaking item with counts
+before any change, present the per-cluster consent options (sweep ·
+show-diff · skip · manual — a blanket approval never covers judgment
+items), run the verify gates, and return the Migration Report (the skill's
+§Deliverable) with every cluster's consent decision recorded.

package/prompts/app-planning.md

@@ -0,0 +1,12 @@
+---
+description: "Orient in an existing adia-ui app — classify rendering mode, project shape, shell, and state; produce the Orientation Record."
+argument-hint: "[path or question]"
+---
+
+Orient in this repo. **$ARGUMENTS**
+
+Invoke **`app-planning`** and produce the Orientation Record in the skill's
+own contract shape (Rendering mode · Project shape · Shell · Task ·
+Screen plan (start mode) · → Route · Verify target · Open questions), each
+axis citing its signal. Self-check the record with
+`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/record-lint" -` before returning it.

package/prompts/find-unused.md

@@ -0,0 +1,23 @@
+---
+description: "Find what a clean @adia-ai upgrade left unused — opt-in layers nothing imports, workarounds a fixed bug made redundant, retired values in stored state, shipped advice that is wrong for this app."
+argument-hint: "[target version]"
+---
+
+Find what this app is not using. **$ARGUMENTS**
+
+Invoke **`find-unused`**: enumerate every `@adia-ai/*` package each manifest
+declares (never assume `web-components`), recon the three versions that differ
+per package — declared range, installed, and the target: **the version in
+`$ARGUMENTS` when one was given, registry latest only as the default**. Read
+every `node_modules/@adia-ai/*/CHANGELOG.md` section across the
+installed→target span, then run all four audits — inert opt-in layers, redundant local
+workarounds, retired enum values sitting in persisted state, and shipped
+advice that does not fit this app. Report counts and file:line before
+proposing any edit, split mechanical items from judgment items and take
+consent per item, verify each adoption with a check that would fail on
+revert, and write the Adoption Record.
+
+Reach for **`app-migration`** instead when the span carries actual breaking
+changes — that skill is guide-driven and sweeps them with per-cluster
+consent. This one runs when nothing broke and the question is what went
+unused.

package/prompts/gen-ui-wiring.md

@@ -0,0 +1,11 @@
+---
+description: "Author a generative-UI experience — wire the a2ui runtime, generate_ui/refine_ui via the MCP, choose core vs custom corpus."
+argument-hint: "[experience or surface]"
+---
+
+Build a gen-UI experience. **$ARGUMENTS**
+
+Invoke **`gen-ui-wiring`** and run its generate → validate → render → iterate
+loop; generated A2UI is validated as data before it is serialized, and the
+run closes with the Generation Record (the skill's §Deliverable) — the
+validate-before-serialize slot filled, never skipped silently.

package/prompts/project-scaffolding.md

@@ -0,0 +1,13 @@
+---
+description: "Scaffold a new adia-ui app, page, or component skeleton (scripts/adia-scaffold emits the mechanical skeleton; the skill owns the shape decisions)."
+argument-hint: "[spa|ssr|page|component|inventory|selftest] [name or app-root]"
+---
+
+Scaffold an adia-ui surface. **$ARGUMENTS**
+
+Invoke **`project-scaffolding`** to classify the project shape and target, then use
+`${CLAUDE_PLUGIN_ROOT}/scripts/adia-scaffold` for the mechanical skeleton. Shapes
+the bin doesn't one-shot (rollup, shared-foundation) are composed per the
+project-shapes reference. `inventory <app-root>` scores an existing app
+against the structure rubric (4 mechanized gates with cited paths + the 2
+judgment rows the model completes).

package/prompts/surface-qa.md

@@ -0,0 +1,20 @@
+---
+description: "Run the consumer-side exit gate on a composed surface — dispatches the read-only surface-qa-agent seat; returns the completed VerifyProof (ship | hold)."
+argument-hint: "[url or surface] [key selectors]"
+---
+
+Verify a composed surface. **$ARGUMENTS**
+
+Dispatch the **surface-qa-agent** agent on the named surface/URL — the exit
+gate runs ISOLATED from whatever context built the surface (generator ≠
+critic). It runs the shipped probe (`scripts/adia-probe.mjs`: console/page
+errors, bounding boxes, the deviceScaleFactor:2 capture), completes the
+judgment half (`imageRead` carries what the pixels actually show; the a11y
+row checked item by item), and returns the VerifyProof (surface-qa
+§Deliverable) with verdict **ship | hold**.
+
+Findings route back to the owning builder skill (screen-composition · data-wiring ·
+shell-selection · host-wiring) — never fix inline from this command. No running
+app or missing Playwright → the gate reports UNMEASURED with the reason,
+never a silent pass. (Mid-build self-checks still invoke the `surface-qa`
+skill inline; this command is the independent verdict at definition-of-done.)

package/references/component-model.md

@@ -119,7 +119,7 @@ Three levels, all `--a-*`:
 
 ## "Registers" — typographic treatments, opt-in
 
-A _register_ (e.g. `verse`, `prose`) is a typographic treatment applied two ways together: **link the register stylesheet** (`styles/verse.css`) **and** put the **attribute** on the surface (`<my-surface verse>`). One without the other is a no-op — a common smell. Body/UI text defaults to `--a-font-family-ui`; registers opt a subtree into a different family/rhythm.
+A _register_ (e.g. `scale="ui-sm"`, `scale="content-md"`) is a typographic treatment applied two ways together: **link the register stylesheet** (`styles/scale.css`, or wrap the surface in `<theme-provider scale="…">`, which adopts it on demand) **and** put the **attribute** on the surface. One without the other is a no-op — a common smell. Body/UI text defaults to `--a-font-family-ui`; registers opt a subtree into a different family/rhythm.
 
 ## Layout realities
 

package/references/spa-architecture.md

@@ -53,7 +53,7 @@ alternatives:
 - **One registration script** — the side-effecting barrel `import '@adia-ai/web-components'`. Don't piecemeal-import primitives: composites render internal `*-ui` tags (e.g. `chat-input-ui` internally renders `textarea-ui` + `select-ui`) that stay unregistered and collapse to 0px unless the barrel ran.
 - Bespoke shell children need the **cluster barrel** (`@adia-ai/web-modules/shell`, `/chat`, `/editor`, `/simple`) — importing `admin-shell.js` alone registers only the host tag, not `admin-sidebar` / `admin-page` / the other children.
 - Never hand-roll `:where(html,body){}` — the foundation owns the page frame; re-rolling it drifts from the system (the classic serif-leak bug).
-- A `[scale]` register has two halves: link `scale.css` **and** put `scale="…"` (one of the six tiers — `ui-sm | ui-md | ui-lg | content-sm | content-md | content-lg`) on the surface. One without the other is a no-op. `[verse]`/`[prose]` still work as deprecated aliases (`ui-sm`/`content-md`) but are removed at v1.0 — new code should reach for `[scale]` directly.
+- A `[scale]` register has two halves: link `scale.css` **and** put `scale="…"` (one of the six tiers — `ui-sm | ui-md | ui-lg | content-sm | content-md | content-lg`) on the surface. One without the other is a no-op.
 - `themes.css` (named palettes) is **not** in the styles barrel — link it separately. `data-scheme` switches light/dark; `data-theme` picks the named palette.
 - Guards: `defineIfFree(tag, ctor)` (`core/register.js`) for defines; a `#booted` flag in `connected()` — the callback re-fires on DOM moves. And `customElements.whenDefined(name)` never rejects: a `Promise.all([...whenDefined])` boot gate hangs forever on one unimported tag — chrome renders (tag-keyed CSS), the page stays "empty", zero console errors.
 

package/scripts/adia-contract-check.mjs

@@ -12,10 +12,10 @@
 // tag — see resolveA2uiDoc()).
 //
 // v1 scope (stated honestly, per the SPEC's Non-goals): attribute names +
-// enum values on `*-ui` tags; class/id/slot/style/role/data-*/aria-*/
-// framework-global attributes allowlisted; one content-model rule — raw <thead>/
-// <tbody> children of <table-ui> (3 of 3 occurrences broken, gh#924). Slot
-// and composition semantics are v2.
+// enum values on `*-ui` tags; class/id/slot/style/role/tabindex/autocomplete/
+// data-*/aria-*/framework-global attributes allowlisted; one content-model
+// rule — raw <thead>/<tbody> children of <table-ui> (3 of 3 occurrences
+// broken, gh#924). Slot and composition semantics are v2.
 //
 // The shipped contract mixes kebab-case and camelCase attribute names across
 // components (an existing inconsistency in the generated manifest — e.g.
@@ -56,7 +56,20 @@ const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.next', 'co
 // `role` is a host-language global (like `aria-*`) — text.yaml itself documents
 // role="heading" + aria-level as the sanctioned semantic-heading path (gh#1256);
 // globals are never component contract members and never CLASS-5-UNKNOWN.
-const ALLOWLIST_EXACT = new Set(['class', 'classname', 'id', 'slot', 'style', 'key', 'ref', 'part', 'role']);
+// `tabindex` and `autocomplete` are the same class of host-language global
+// (gh#1925): `tabindex` sets DOM focus order on any element (traits like
+// long-press/typeahead and app code use it directly on `*-ui` tags — see
+// e.g. packages/web-components/traits/typeahead/typeahead.examples.html —
+// and it is the sanctioned pattern for post-screen-swap heading focus);
+// `autocomplete` is the standard form-control autofill hint, and at least
+// one component's own yaml SoT instructs authors to set it directly
+// (otp-input.yaml:73, `autocomplete="one-time-code"`) even though the
+// component does not re-declare it as a reflected prop. Neither is ever a
+// component contract member, so neither is ever CLASS-5-UNKNOWN.
+const ALLOWLIST_EXACT = new Set([
+  'class', 'classname', 'id', 'slot', 'style', 'key', 'ref', 'part', 'role',
+  'tabindex', 'autocomplete',
+]);
 const ALLOWLIST_PREFIX = ['data-', 'aria-'];
 
 function normalize(name) {
@@ -346,6 +359,17 @@ function selftest() {
   const roleGlobal = checkMarkup('<text-ui variant="title" role="heading" aria-level="1">Dashboard</text-ui>', 'f.html', index);
   if (roleGlobal.length !== 0) fails.push(`role="heading" aria-level flagged (gh#1256): ${JSON.stringify(roleGlobal)}`);
 
+  // 9a. gh#1925: `tabindex` on any *-ui tag (e.g. text-ui for post-screen-swap
+  //     heading focus) is a host-language global, never CLASS-5-UNKNOWN.
+  const tabindexGlobal = checkMarkup('<text-ui variant="title" tabindex="-1">Dashboard</text-ui>', 'f.html', index);
+  if (tabindexGlobal.length !== 0) fails.push(`tabindex="-1" flagged (gh#1925): ${JSON.stringify(tabindexGlobal)}`);
+
+  // 9b. gh#1925: `autocomplete` is a host-language global too, and otp-input-ui's
+  //     own yaml SoT instructs authors to set it — must never be CLASS-5-UNKNOWN
+  //     even though the component doesn't re-declare it as a reflected prop.
+  const autocompleteGlobal = checkMarkup('<icon-ui name="house" autocomplete="one-time-code"></icon-ui>', 'f.html', index);
+  if (autocompleteGlobal.length !== 0) fails.push(`autocomplete flagged (gh#1925): ${JSON.stringify(autocompleteGlobal)}`);
+
   // 10. Setup-error path (AC-4's 0/1/2 matrix): no @adia-ai/web-components in
   // node_modules anywhere up the tree must resolve to null (drives exit 2 in
   // main()), never a thrown exception or a silent empty-clean pass.
@@ -375,7 +399,7 @@ function selftest() {
     console.error('selftest FAIL: ' + fails.join(' | '));
     return 1;
   }
-  console.log('selftest OK — 11 fixtures (unknown attr, clean, enum, camelCase-normalize, table content-model, unknown tag, seed+un-seed, role/aria globals, setup-error, -h/--help)');
+  console.log('selftest OK — 13 fixtures (unknown attr, clean, enum, camelCase-normalize, table content-model, unknown tag, seed+un-seed, role/aria globals, tabindex/autocomplete globals, setup-error, -h/--help)');
   return 0;
 }
 

package/scripts/adia-probe.mjs

@@ -260,7 +260,13 @@ async function main() {
       const { pathToFileURL } = await import('node:url');
       const path = await import('node:path');
       const req = createRequire(path.join(process.cwd(), 'package.json'));
-      ({ chromium } = await import(pathToFileURL(req.resolve('playwright')).href));
+      // The plugin-cache copy resolves playwright's CJS entry; importing a
+      // CJS module via file URL exposes named exports only through
+      // `.default` (no static analysis to hoist `chromium` onto the
+      // namespace itself) — `mod.chromium` is undefined there, so fall back
+      // to `mod.default.chromium` (gh#1926).
+      const mod = await import(pathToFileURL(req.resolve('playwright')).href);
+      chromium = mod.chromium ?? mod.default.chromium;
     } catch {
       console.error('adia-probe: playwright not installed in this app — npm i -D playwright');
       process.exit(2);
@@ -329,33 +335,53 @@ async function main() {
     const samples = [];
     let skipped = 0;
     const seen = new Set();
-    const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
-    let node;
-    while ((node = walker.nextNode()) && samples.length < 120) {
-      const text = node.textContent.trim();
-      if (!text) continue;
-      const el = node.parentElement;
-      if (!el || ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE'].includes(el.tagName)) continue;
-      const cs = getComputedStyle(el);
-      if (cs.display === 'none' || cs.visibility === 'hidden' || Number(cs.opacity) === 0) continue;
-      const rect = el.getBoundingClientRect();
-      if (rect.width <= 0 || rect.height <= 0) continue;
-      const fgc = parse(cs.color);
-      if (!fgc) continue;
-      const bg = bgFor(el);
-      if (!bg) { skipped += 1; continue; }
-      const fg = fgc.a >= 1 ? fgc.rgb.map(Math.round) : over(fgc.rgb, fgc.a, bg);
-      const fontSizePx = parseFloat(cs.fontSize) || 16;
-      const fontWeight = cs.fontWeight === 'bold' ? 700 : Number(cs.fontWeight) || 400;
-      const key = `${fg.join()}|${bg.join()}|${fontSizePx}|${fontWeight}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      samples.push({
-        text: text.slice(0, 40),
-        element: el.tagName.toLowerCase() + (el.id ? `#${el.id}` : ''),
-        fg, bg, fontSizePx, fontWeight,
-      });
-    }
+    // AdiaUI is light-DOM by convention (AGENTS.md), but a plain
+    // TreeWalker rooted at document.body never descends into a shadow
+    // tree regardless — so any *-ui element that DOES attach a shadow
+    // root (its own internal structure, a third-party element, or a
+    // future exception to the light-DOM stance) went unwalked entirely,
+    // which is why the sampler read checked:0 on custom-element-heavy
+    // pages (gh#1926). Walk every root — document, then recurse into
+    // each element's shadowRoot as it's discovered — so light-DOM slotted
+    // content and shadow-DOM internals both get sampled.
+    const visitRoot = (root) => {
+      const walker = document.createTreeWalker(
+        root,
+        NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT,
+      );
+      let node;
+      while ((node = walker.nextNode())) {
+        if (node.nodeType === 1) {
+          if (node.shadowRoot) visitRoot(node.shadowRoot);
+          continue;
+        }
+        if (samples.length >= 120) return;
+        const text = node.textContent.trim();
+        if (!text) continue;
+        const el = node.parentElement;
+        if (!el || ['SCRIPT', 'STYLE', 'NOSCRIPT', 'TEMPLATE'].includes(el.tagName)) continue;
+        const cs = getComputedStyle(el);
+        if (cs.display === 'none' || cs.visibility === 'hidden' || Number(cs.opacity) === 0) continue;
+        const rect = el.getBoundingClientRect();
+        if (rect.width <= 0 || rect.height <= 0) continue;
+        const fgc = parse(cs.color);
+        if (!fgc) continue;
+        const bg = bgFor(el);
+        if (!bg) { skipped += 1; continue; }
+        const fg = fgc.a >= 1 ? fgc.rgb.map(Math.round) : over(fgc.rgb, fgc.a, bg);
+        const fontSizePx = parseFloat(cs.fontSize) || 16;
+        const fontWeight = cs.fontWeight === 'bold' ? 700 : Number(cs.fontWeight) || 400;
+        const key = `${fg.join()}|${bg.join()}|${fontSizePx}|${fontWeight}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        samples.push({
+          text: text.slice(0, 40),
+          element: el.tagName.toLowerCase() + (el.id ? `#${el.id}` : ''),
+          fg, bg, fontSizePx, fontWeight,
+        });
+      }
+    };
+    visitRoot(document.body);
     return { samples, skipped };
   }).catch(() => null);
   await page.screenshot({ path: screenshotPath, scale: 'device', fullPage: true });

package/skills/find-unused/references/recon-and-audits.md

@@ -85,7 +85,7 @@ proposing any edit.
 opt-in, confirm something imports it:
 
 ```bash
-git grep -n "styles/scale.css\|styles/themes.css\|styles/verse.css\|styles/prose.css"
+git grep -n "styles/scale.css\|styles/themes.css"
 
 # Attributes reach the DOM from markup AND from script — a setAttribute('scale', …)
 # in a .js module counts. Searching templates only produces a false "unused".

package/skills/host-wiring/SKILL.md

@@ -90,7 +90,7 @@ Mode:            SPA | SSR | hybrid                     — signal: <file / dep
 Framework:       <name, or none>                          — [D] documented | [G] inferred, per ssr-integration.md
 Registration:    <file>:<call site>                        — one side-effecting barrel import, client-only
 Route owner:     <router-ui> | <framework router>          — exactly one per scope
-CSS links:       host.css + styles/index.css (+ scale.css, or its deprecated verse.css/prose.css alias) — both live, or primitives render unstyled
+CSS links:       host.css + styles/index.css (+ scale.css) — both live, or primitives render unstyled
 State placement: cookies/localStorage/session | client signal — per mode's lifetime rule
 Gates:           registration / route-owner / CSS-links / state — pass | fail, each
 ```

package/skills/host-wiring/references/mode-wiring-detail.md

@@ -43,8 +43,7 @@ Build order — snippets and the full invariant list in `spa-architecture.md`;
 
 1. **Host document** — npm-consumer paths; cascade order later-wins:
    `host.css` → `styles/index.css` → opt-in `scale.css` (the ancestor
-   `[scale]` register — `verse.css`/`prose.css` are its deprecated,
-   still-working aliases) → page → component CSS. Link BOTH `host.css`
+   `[scale]` register) → page → component CSS. Link BOTH `host.css`
    and `styles/index.css` — the styles barrel is split and `host.css` is
    foundation-only; alone it renders primitives unstyled.
 2. **Surface container** — self-booting custom element rendering in