@adia-ai/adia-ui-factory 0.8.55 → 0.8.57

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.55",
+  "version": "0.8.57",
   "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",
@@ -15,5 +15,6 @@
     "web-components",
     "app-authoring",
     "consumer"
-  ]
+  ],
+  "hooks": "./adapters/claude/hooks.json"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.55",
+  "version": "0.8.57",
   "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.55", "gen-ui"]
+      "args": ["-y", "@adia-ai/mcp@0.8.57", "gen-ui"]
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog — adia-ui-kit-factory
 
+## [0.8.57] — 2026-09-01
+
+### Fixed
+- **Plugin passes `author-cross-harness-plugins`'s cross-harness validator, modulo one documented, permanent, irreconcilable exception (gh#2668).** `${CLAUDE_PLUGIN_ROOT}`/`$ARGUMENTS`/the `` !`command` `` auto-injection syntax removed from shared `app-migration`, `theme-audit`, `screen-composition`, `project-scaffolding`, `app-planning`, `surface-qa`, and `find-unused` SKILL.md bodies, all eight `commands/*.md` bodies, and their linked reference docs (`surface-qa/references/verification.md`, `find-unused/references/recon-and-audits.md`) — portable `<plugin-root>` prose / "named in the current request" phrasing throughout; `screen-composition`/`app-planning`'s Claude-only auto-injected context block became an explicit "run this yourself" instruction, since Codex has no equivalent auto-injection surface. `hooks/hooks.json` moved to `adapters/claude/hooks.json` (unchanged, `${CLAUDE_PLUGIN_ROOT}`-based); new root `hooks.json` mirrors the same event/matcher/action signature with a monorepo-root-relative command path for Codex's convention-discovered hook surface — an unverified-but-honest fallback documented in `HARNESS-NOTES.md`. **The one exception:** every skill's `disable-model-invocation:`/`user-invocable:` frontmatter — required, explicitly, by this repo's own blocking `check:skills` gate (`plugin-estate-v2.md`'s species-pinning charter) — collides head-on with the validator's opposite requirement on the exact same file, and Codex is hard-pinned to read root `skills/` directly (no adapter escape). The repo's own charter is not weakened; `npm run check:cross-harness-plugins` (`scripts/verify/check-cross-harness-plugins.mjs`, wrapping the vendored `scripts/verify/vendor/validate_cross_harness.py`) treats only this one exact finding shape as accepted (logged as INFO) and still fails on every other portability class. Full reasoning in `HARNESS-NOTES.md`.
+
+### Docs
+- **`skills/pattern-catalog/references/pattern-index.md` regenerated for `page-scroll`'s addition (gh#2639, ADR-0098 Fork 4).** `build:patterns-index`'s re-extraction picked up `admin-dashboard.contents.html`/`admin-shell.contents.html`'s tag-list changes under the page-chrome consolidation (`admin-page*` → `page-ui[band]`, `admin-scroll` → `page-scroll`).
+
+### Changed
+- **`adia-lint` rewritten as a thin Node CLI (`adia-lint.mjs`) consuming a shared generated lint-rule bank, retiring the Python script (gh#2638, LLD-0016, ADR-0099).** The consumer-app structural checks (the forge-shared rules plus SSR-DOUBLE-ROUTER, SSR-TOPLEVEL-IMPORT, HARDCODED-OPEN, SHELL-NESTING, SHELL-RESIZE, LLM-KEY-IN-CLIENT, GENUI-UNVALIDATED, GENUI-DOC-CONFLICT) now live as individually-fixtured rule modules under `scripts/lint/rules/` in the repo root, built into `scripts/lint/generated/rule-bank.mjs` and vendored byte-identically into this plugin, `adia-ui-forge`, and the gen-ui MCP's factory vendor tree (`npm run build:lint-rules`, freshness gated by `npm run check:lint-rules-fresh`). `hooks/hooks.json`'s PostToolUse command changes from `python3 ".../adia-lint" --hook` to `node ".../adia-lint.mjs" --hook`; the CLI contract (including `-h`/`--help`), exit codes, and PostToolUse never-block invariant are unchanged. `npm run check:lint-rules-selftest` proves finding-parity against the retired script's own `selftest()` fixtures. The gen-ui MCP factory server's `lint` tool (`audit_structure`) now spawns the Node CLI directly instead of shelling through `python3`.
+
+### Maintenance
+- **`.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.
+- **`agents/` touched in this release window** (1 file(s), e.g. `agents/surface-qa-agent.md`) — carried by the entries above.
+- **`prompts/` touched in this release window** (8 file(s), e.g. `prompts/app-audit.md`) — carried by the entries above.
+
+## [0.8.56] — 2026-08-31
+
+### Added
+- **`theme-audit` skill, `/theme-audit` command, and `scripts/adia-theme-audit.mjs` runner (lld-0012 B1–B3, gh#2257).** Audits a consumer app's `theme.css` for the four redundancy classes (restated defaults, token re-derivations, dead selectors, hand-built components) across every sitemap route, with a Playwright class-1 toggle and route discovery (#2308, #2312, #2413). Fixtures under `scripts/theme-audit-fixtures/`; report shape in `skills/theme-audit/references/report-shape.md`; Codex/Pi/Hermes manifests derived (`skills/theme-audit/agents/openai.yaml`, `prompts/theme-audit.md`).
+- **`HARNESS-NOTES.md`** pointer for non-Claude harnesses (gh#2449) — points at `AGENTS.md`/README rather than duplicating install prose.
+
+### Changed
+- **`scripts/adia-probe.mjs`** gains the route-discovery + class-1 toggle hooks the theme-audit runner drives (#2413); `agents/surface-qa-agent.md` cites the extended probe.
+- **`skills/token-selection/references/a-alias-layer.md`** documents the 15 new `--a-*` aliases from tokens batch C0 and the advisory reroute gate (gh#2240, #2243).
+- **`skills/pattern-catalog/references/{pattern-index.md,annotations.yaml}`** pick up the sidebar-modal pattern (#2226) and the registration/NPI-search and errors surfaces (#2242, #2270); `skills/table-composition/references/base-table.md` follows `table-toolbar-ui`'s count-cluster redesign (#2190); `skills/find-unused/SKILL.md` wording tightened.
+
+### Maintenance
+- **`.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.
+- **`commands/` touched in this release window** (1 file(s), e.g. `commands/theme-audit.md`) — carried by the entries above.
+
 ## [0.8.55] — 2026-08-28
 
 ### Changed

package/README.md

@@ -51,7 +51,7 @@ posture (ADR-0040) is about this plugin working standalone in any consumer
 repo once installed some other way (no monorepo path assumptions in its own
 scripts) — it does not add an npm-sourced marketplace entry.
 
-## Skills (19 — `skills/` on disk is the roster; `check:plugin-count-claims` guards this header count)
+## Skills (20 — `skills/` on disk is the roster; `check:plugin-count-claims` guards this header count)
 
 | Skill | Species | Job |
 |---|---|---|
@@ -74,6 +74,7 @@ scripts) — it does not add an npm-sourced marketplace entry.
 | `app-migration` | procedural | version upgrades + port-to-adia sweeps (breaking changes) |
 | `find-unused` | procedural | what a *non*-breaking upgrade left unused — inert opt-in layers, stale workarounds |
 | `surface-qa` | procedural | browser + a11y + composition exit gate |
+| `theme-audit` | procedural | classify a consumer theme.css against the framework's own defaults/tokens/primitives — restated defaults, re-derived tokens, dead selectors, hand-built component work; audit + report only, no rewrites (gh#2257) |
 
 ## Agents (4)
 
@@ -97,11 +98,20 @@ surface-qa-agent) · `component-model.md` · the `references/contracts/` twins.
 
 ## Commands
 
-`/project-scaffolding` · `/app-planning` · `/surface-qa` · `/app-migration` · `/find-unused` · `/gen-ui-wiring` · `/app-audit`
+`/project-scaffolding` · `/app-planning` · `/surface-qa` · `/app-migration` · `/find-unused` · `/gen-ui-wiring` · `/app-audit` · `/theme-audit`
+
+## Scripts
+
+Consumer-runnable checks shipped as plain Node scripts under `scripts/`, no
+MCP server required: `adia-probe.mjs` (the browser-QA gate; see
+`surface-qa`), `adia-preflight.mjs` (every CI-step prerequisite, each
+failure named with its remedy), `adia-contract-check.mjs` (authored markup
+attributes vs. the shipped component contracts), and `adia-theme-audit.mjs`
+(the theme.css redundancy classifier; see `theme-audit`).
 
 ## MCP
 
-`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.55` (tool SoT:
+`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.57` (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`,
@@ -120,6 +130,12 @@ 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.
 
+`theme-audit`'s `adia-theme-audit` bin runs identically on every harness — a
+plain Node script with no Claude-specific runtime dependency; the
+`/theme-audit` command degrades to invoking the skill directly on Codex and
+Hermes, and becomes a genuine `prompts/theme-audit.md` Pi command via
+`build:harness-manifests`.
+
 - **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 —

package/__init__.py

@@ -263,7 +263,7 @@ def register(ctx):
     ctx.register_skill(
         name="find-unused",
         path=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).",
+        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); NOT for CSS-only redundancy in a theme file (theme-audit — the CSS-side sibling).",
     )
     ctx.register_skill(
         name="gen-ui-wiring",
@@ -310,6 +310,11 @@ def register(ctx):
         path=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="theme-audit",
+        path=Path(os.path.join(_HERE, "skills", "theme-audit", "SKILL.md")),
+        description="Classifies a consumer app's theme.css against what the adia-ui framework already ships — restated defaults, re-derived tokens, dead selectors, and hand-built component work. Runs `adia-theme-audit` against a theme file + app root; audits and reports, never rewrites. Use when a theme.css is suspected of restating the kit, after bumping `@adia-ai/web-components`, or before a `find-unused` sweep. NOT for rendering/grading a surface (surface-qa); NOT for picking a token going forward (token-selection); NOT for JS/markup an upgrade left unused (find-unused — the CSS-side sibling); NOT for the framework's OWN token layer in packages/web-components (forge's component-token-audit).",
+    )
     ctx.register_skill(
         name="token-selection",
         path=Path(os.path.join(_HERE, "skills", "token-selection", "SKILL.md")),

package/agents/surface-qa-agent.md

@@ -9,6 +9,7 @@ description: |
 tools: Read, Grep, Glob, Bash
 skills:
   - surface-qa
+  - theme-audit
 # Explicit pin (gh#618, tier corrected gh#1045): a review/critic seat's
 # verdict must not depend on the caller's model tier — never `inherit`.
 # Operator's explicit standing instruction for this seat family: sonnet + xhigh.
@@ -38,7 +39,7 @@ a surface can pass the browser gate and still be a keyword-driven premature
 render (D1) that never traced to a resolved plan. Every claim in the
 proof cites its evidence (the probe JSON, the screenshot path, the element
 inspected). The structure row's evidence comes from running
-`python3 "${CLAUDE_PLUGIN_ROOT}/scripts/adia-lint"` over the surface's files via
+`node "${CLAUDE_PLUGIN_ROOT}/scripts/adia-lint.mjs"` over the surface's files via
 Bash — the PostToolUse hook never fires for a seat that writes nothing. A
 gate that cannot run (no dev server, Playwright missing) is reported
 UNMEASURED with the reason, never silently skipped; a dispatch without a

package/commands/app-audit.md

@@ -6,9 +6,11 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Probe the project context. **$ARGUMENTS**
+Probe the project context named in the current request (a directory, if given).
 
-Run `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/adia-info" $ARGUMENTS` and present
+Run `python3 "<plugin-root>/scripts/adia-info" [dir]` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT`
+in Claude Code; the plugin's installed directory in Codex) with the directory named in the
+current request, 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

package/commands/app-migration.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Migrate this codebase. **$ARGUMENTS**
+Migrate this codebase to the target version named in the current request.
 
 Invoke **`app-migration`**: read the shipped guide for the span
 (`node_modules/@adia-ai/web-components/MIGRATION.md` — install/upgrade the

package/commands/app-planning.md

@@ -6,10 +6,11 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Orient in this repo. **$ARGUMENTS**
+Orient in this repo, answering the path or question named in the current request.
 
 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.
+`python3 "<plugin-root>/scripts/record-lint" -` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in
+Claude Code; the plugin's installed directory in Codex) before returning it.

package/commands/find-unused.md

@@ -6,12 +6,12 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Find what this app is not using. **$ARGUMENTS**
+Find what this app is not using, scoped to the target version named in the current request.
 
 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
+per package — declared range, installed, and the target: **the version named in the current request
+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

package/commands/gen-ui-wiring.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Build a gen-UI experience. **$ARGUMENTS**
+Build the gen-UI experience or surface named in the current request.
 
 Invoke **`gen-ui-wiring`** and run its generate → validate → render → iterate
 loop; generated A2UI is validated as data before it is serialized, and the

package/commands/project-scaffolding.md

@@ -6,10 +6,11 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Scaffold an adia-ui surface. **$ARGUMENTS**
+Scaffold the adia-ui surface named in the current request.
 
 Invoke **`project-scaffolding`** to classify the project shape and target, then use
-`${CLAUDE_PLUGIN_ROOT}/scripts/adia-scaffold` for the mechanical skeleton. Shapes
+`<plugin-root>/scripts/adia-scaffold` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in Claude
+Code; the plugin's installed directory in Codex) 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

package/commands/surface-qa.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 ---
 
-Verify a composed surface. **$ARGUMENTS**
+Verify the composed surface named in the current request.
 
 Dispatch the **surface-qa-agent** agent on the named surface/URL — the exit
 gate runs ISOLATED from whatever context built the surface (generator ≠

package/commands/theme-audit.md

@@ -0,0 +1,28 @@
+---
+wraps: theme-audit
+description: Classify a consumer app's theme.css against what the adia-ui framework already ships — restated defaults, re-derived tokens, dead selectors, hand-built component work. Audit and report only; no rewrites.
+argument-hint: "[--theme <file>] [--app <root>]"
+disable-model-invocation: false
+user-invocable: true
+---
+
+Audit the theme stylesheet named in the current request.
+
+Run `node "<plugin-root>/scripts/adia-theme-audit.mjs" --theme <file>
+--app <root>` (add `--json`/`--json-out <path>` for a structured report,
+`--strict` to exit non-zero on any `high`-confidence finding, `--class
+1,2,3,4` to narrow scope). No `@adia-ai/web-components` resolvable from
+`<app>` → the tool reports `E_NO_FRAMEWORK` with the install remedy; pass
+`--framework-root <checkout>` to audit against an unreleased framework
+checkout instead. No `--base-url`/Playwright unreachable → class 3's
+rendered census degrades to `UNMEASURED` and the run still exits `0`
+(unless `--strict`); static `last-wins` detection still runs.
+
+Return the human-readable summary and per-class tables (theme-audit
+§Reading the report). Findings route back to the owning skill — a
+restated default or re-derived token deletes from the theme file directly;
+a hand-built-component finding routes to `screen-composition` to swap in
+the primitive; a dead selector still needs a human's confirmation before
+removal (the census may not have covered every interaction state). Never
+apply a fix inline from this command — theme-audit and its runner never
+rewrite the file, and neither does this wrapper.

package/hermes-mcp.yaml

@@ -6,5 +6,5 @@ mcp_servers:
     command: "npx"
     args:
       - "-y"
-      - "@adia-ai/mcp@0.8.55"
+      - "@adia-ai/mcp@0.8.57"
       - "gen-ui"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-factory",
-  "version": "0.8.55",
+  "version": "0.8.57",
   "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",
@@ -19,6 +19,9 @@
   "bugs": {
     "email": "kim.granlund@adia.ai"
   },
+  "bin": {
+    "adia-theme-audit": "./scripts/adia-theme-audit.mjs"
+  },
   "pi": {
     "skills": ["./skills"],
     "prompts": ["./prompts"],

package/plugin.yaml

@@ -1,4 +1,4 @@
 name: "adia-ui-kit-factory"
-version: "0.8.55"
+version: "0.8.57"
 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

@@ -3,9 +3,11 @@ description: "Probe this repo's adia-ui project context — declared vs installe
 argument-hint: "[dir]"
 ---
 
-Probe the project context. **$ARGUMENTS**
+Probe the project context named in the current request (a directory, if given).
 
-Run `python3 "${CLAUDE_PLUGIN_ROOT}/scripts/adia-info" $ARGUMENTS` and present
+Run `python3 "<plugin-root>/scripts/adia-info" [dir]` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT`
+in Claude Code; the plugin's installed directory in Codex) with the directory named in the
+current request, 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

package/prompts/app-migration.md

@@ -3,7 +3,7 @@ description: "Migrate consumer code across @adia-ai versions (or port a foreign
 argument-hint: "[target version]"
 ---
 
-Migrate this codebase. **$ARGUMENTS**
+Migrate this codebase to the target version named in the current request.
 
 Invoke **`app-migration`**: read the shipped guide for the span
 (`node_modules/@adia-ai/web-components/MIGRATION.md` — install/upgrade the

package/prompts/app-planning.md

@@ -3,10 +3,11 @@ description: "Orient in an existing adia-ui app — classify rendering mode, pro
 argument-hint: "[path or question]"
 ---
 
-Orient in this repo. **$ARGUMENTS**
+Orient in this repo, answering the path or question named in the current request.
 
 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.
+`python3 "<plugin-root>/scripts/record-lint" -` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in
+Claude Code; the plugin's installed directory in Codex) before returning it.

package/prompts/find-unused.md

@@ -3,12 +3,12 @@ description: "Find what a clean @adia-ai upgrade left unused — opt-in layers n
 argument-hint: "[target version]"
 ---
 
-Find what this app is not using. **$ARGUMENTS**
+Find what this app is not using, scoped to the target version named in the current request.
 
 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
+per package — declared range, installed, and the target: **the version named in the current request
+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

package/prompts/gen-ui-wiring.md

@@ -3,7 +3,7 @@ description: "Author a generative-UI experience — wire the a2ui runtime, gener
 argument-hint: "[experience or surface]"
 ---
 
-Build a gen-UI experience. **$ARGUMENTS**
+Build the gen-UI experience or surface named in the current request.
 
 Invoke **`gen-ui-wiring`** and run its generate → validate → render → iterate
 loop; generated A2UI is validated as data before it is serialized, and the

package/prompts/project-scaffolding.md

@@ -3,10 +3,11 @@ description: "Scaffold a new adia-ui app, page, or component skeleton (scripts/a
 argument-hint: "[spa|ssr|page|component|inventory|selftest] [name or app-root]"
 ---
 
-Scaffold an adia-ui surface. **$ARGUMENTS**
+Scaffold the adia-ui surface named in the current request.
 
 Invoke **`project-scaffolding`** to classify the project shape and target, then use
-`${CLAUDE_PLUGIN_ROOT}/scripts/adia-scaffold` for the mechanical skeleton. Shapes
+`<plugin-root>/scripts/adia-scaffold` (`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in Claude
+Code; the plugin's installed directory in Codex) 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

package/prompts/surface-qa.md

@@ -3,7 +3,7 @@ description: "Run the consumer-side exit gate on a composed surface — dispatch
 argument-hint: "[url or surface] [key selectors]"
 ---
 
-Verify a composed surface. **$ARGUMENTS**
+Verify the composed surface named in the current request.
 
 Dispatch the **surface-qa-agent** agent on the named surface/URL — the exit
 gate runs ISOLATED from whatever context built the surface (generator ≠

package/prompts/theme-audit.md

@@ -0,0 +1,25 @@
+---
+description: "Classify a consumer app's theme.css against what the adia-ui framework already ships — restated defaults, re-derived tokens, dead selectors, hand-built component work. Audit and report only; no rewrites."
+argument-hint: "[--theme <file>] [--app <root>]"
+---
+
+Audit the theme stylesheet named in the current request.
+
+Run `node "<plugin-root>/scripts/adia-theme-audit.mjs" --theme <file>
+--app <root>` (add `--json`/`--json-out <path>` for a structured report,
+`--strict` to exit non-zero on any `high`-confidence finding, `--class
+1,2,3,4` to narrow scope). No `@adia-ai/web-components` resolvable from
+`<app>` → the tool reports `E_NO_FRAMEWORK` with the install remedy; pass
+`--framework-root <checkout>` to audit against an unreleased framework
+checkout instead. No `--base-url`/Playwright unreachable → class 3's
+rendered census degrades to `UNMEASURED` and the run still exits `0`
+(unless `--strict`); static `last-wins` detection still runs.
+
+Return the human-readable summary and per-class tables (theme-audit
+§Reading the report). Findings route back to the owning skill — a
+restated default or re-derived token deletes from the theme file directly;
+a hand-built-component finding routes to `screen-composition` to swap in
+the primitive; a dead selector still needs a human's confirmation before
+removal (the census may not have covered every interaction state). Never
+apply a fix inline from this command — theme-audit and its runner never
+rewrite the file, and neither does this wrapper.

package/references/authoring-components.md

@@ -109,4 +109,4 @@ The mechanizable smells the framework audits — these seed the phase-(c) hook a
 | Hardcoded `open` on `<modal-ui>`/`<drawer-ui>` | drive via `.open = true` |
 | `new URL('…', import.meta.url)` literal for a corpus path | hold the path in a variable first |
 
-Run the plugin's `scripts/adia-lint` on changed files, the framework's `audit:*` gates when you have the repo, and `mcp__a2ui__check_anti_patterns` / `validate_schema` on generated markup.
+Run the plugin's `scripts/adia-lint.mjs` on changed files, the framework's `audit:*` gates when you have the repo, and `mcp__a2ui__check_anti_patterns` / `validate_schema` on generated markup.

package/references/composed-surface-rubric.md

@@ -72,5 +72,5 @@ Verdict: <shippable | blocked: D#…>
 
 _Provenance: the two-axis COMPOSE/REALIZE defect-quadrant model is adapted from a component-grading
 rubric; the audit tool names and slot contracts here are the factory plugin's own (`adia-lint`,
-`adia-probe`, the current primitive catalog). Verify a named audit rule against `scripts/adia-lint`'s
+`adia-probe`, the current primitive catalog). Verify a named audit rule against `scripts/adia-lint.mjs`'s
 actual rule set before citing it._

package/references/shell-admin.md

@@ -89,7 +89,7 @@ SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only th
 
 - **Piecemeal import** → `AdminSidebar`/`AdminCommand` unregistered; `.toggle()/.show()` undefined. Import the barrel.
 - **Wrapping shell children in `<col-ui>`/`<row-ui>`** → breaks the grid (it reads tag selectors). Generics go _inside_ `admin-content`/`admin-page-body`.
-- **Raw `<header>` vs `<header-ui>` inside `<admin-page-header>`**: both work — the shell CSS targets `admin-page-header > :is(header, header-ui)` identically (css/admin-shell.templates.css:39), and the CHANGELOG's canonical composition uses raw `<header>`. Pick either; just don't wrap the header in a layout primitive.
+- **Raw `<header>` vs `<header-ui>` inside `<admin-page-header>`**: always use `<header-ui>`. The shell CSS targets `admin-page-header > :is(header, header-ui)` identically for geometry (css/admin-shell.templates.css:39), but only `<header-ui>` has the shadow DOM that routes `slot="heading"` / `slot="description"` / `slot="icon"` / `slot="action"` children — a raw `<header>` matches the CSS rhythm but silently drops every named slot.
 - **`[resizable]` without a child `<div data-sidebar-resize>`** → no drag handle.
 - **Hardcoded `[collapsed]`** → won't auto-clear on resize; use `.collapse()/.expand()`.
 - **Multiple `<admin-page>` in one `<admin-scroll>`** → single-axis scroll breaks; one page per scroll.