@adia-ai/adia-ui-factory 0.2.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "adia-ui-factory",
+  "version": "0.2.2",
+  "description": "Author and verify apps built on the adia-ui (@adia-ai) light-DOM web-component framework — scaffold, compose, wire, and verify across both SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
+  "author": {
+    "name": "Kim",
+    "email": "kim@sublimeheroics.com"
+  },
+  "homepage": "https://github.com/adiahealth/gen-ui-kit",
+  "license": "MIT",
+  "keywords": ["adia-ui", "a2ui", "web-components", "app-authoring", "ssr", "spa", "scaffolding", "llm-ui"]
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "a2ui": {
+      "command": "npx",
+      "args": ["-y", "@adia-ai/a2ui-mcp@0.7.8"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+## [0.2.2] — 2026-06-04
+
+- **The design intent is now a precondition of making — a soft gate.** Before the maker converges on structure or UI, the app's **design intent** (the `BRIEF` — what this UI is reaching for) must be **at least lightly named**; composition reasoned toward _nothing_ drifts to "build the catalog" / feature improvisation. `adia-ui-project` gains a **"Step 0 — name the design intent [soft-gate]"** section before picking the shape (name a provisional pull, trace it in `spec/BRIEF` or inline); `adia-ui-compose` and `adia-ui-genui` each add a short design-intent soft-gate check before their loop (and for genui it also grounds corpus retrieval); `/adia-scaffold` and `/adia-genui` gain a one-line gate near the top. It is a _soft_ blocker throughout — cleared by **naming** a revisable direction, never by stopping, and "lightly declared and developed over time" is the healthy state. Mirrors the generalized rule in plugins-factory `operational-roles.md`.
+
+## [0.2.1] — 2026-06-04
+
+- **Quoted `argument-hint` frontmatter.** `/adia-migrate`, `/adia-scaffold`, and `/adia-wire` used multi-bracket hints (e.g. `[spa|ssr] [app name]`) that YAML parsed as a flow sequence with trailing tokens → parse error → the loader dropped their **entire** frontmatter (description + hint) at load. All command hints are now quoted strings.
+
+## [0.2.0] — 2026-06-03
+
+The v0.2 re-carve: from 6 skills to **11**, each rebuilt to plugins-factory's hardened skill-architecture standard (cold-start surface · modes · per-mode verify target · a `[gate]` rubric · §SelfAudit · load-on-demand references), now covering the full consumer authoring lifecycle for adia-ui apps. See `reviews/2026-06-03-v0.2-recarve.md`.
+
+**New skills:** `adia-ui-project` (project shapes · four-axis · page-trio/DUO), `adia-ui-shells` (admin/chat/editor/simple + the forthcoming embed), `adia-ui-data` (hydration · fetch/CRUD · section wiring · hybrid SPA-in-SSR), `adia-ui-genui` (the a2ui generative-UI loop + corpus), `adia-ui-migrate` (version-upgrade / port sweep discipline). **Hardened:** the orchestrator + compose/spa/ssr/llm/verify. **Tooling:** `bin/adia-scaffold` gains `page`/`component`; `bin/adia-lint` gains `RAW-PX` + `NATIVE-PRIMITIVE` + `LEGACY-SHELL`. **16 references** + two new commands (`/adia-migrate`, `/adia-genui`).
+
+### Red-team (plugins-factory 9-critic council) — fixes folded
+
+No runtime Critical (trust boundary universal across all 11 skills, MCP pinned, hook never-blocks, no agent-trifecta). Folded:
+
+- **Cut 0.2.0** (8/9 critics; 2 flagged the drift Critical): bumped `plugin.json` 0.1.0→0.2.0, added the 2 missing skill `version`s (spa/ssr), rewrote the README to the 11-skill shape, dated this entry.
+- **Commands ↔ skills** (Steve/Charity): fixed the dangling "Step 0" reference in 3 commands; repointed `/adia-scaffold`→`adia-ui-project` and `/adia-wire`→`adia-ui-data`; added `/adia-migrate` + `/adia-genui`; documented the curated spine.
+- **`[gate]` honesty** (Andrej K./Charity): corrected the false "framework `audit:*` is the mechanized layer" claim (those run in the app repo, not here) and marked the render / validate-before-render / a11y gates as **self-verified**, distinct from the `adia-lint`-mechanized ones.
+- **MCP ledger** (Chip H.): added `refine_ui` to `a2ui-mcp-tools.md`; **shell-ref links** made reference-lint-guardable; **scaffolder claim** (Elon): the project skill no longer implies the bin one-shots rollup/shared-foundation.
+- **Accepted tension** (Elon vs Steve/Boris/Chip H.): keep 11 skills (the signed-off carve); the genui↔llm and migrate↔verify merges were weighed and declined — the boundaries are clean (Chip H. verified) and comprehensiveness was the chosen trade.
+
+### Build (phases 1a–5)
+
+- **Phase 1a** — rebuilt the `adia-ui-factory` orchestrator to the hardened standard: four cited-signal classifiers (rendering mode incl. **hybrid** · project shape · shell · task), an **Orientation Record** verify target with a `[gate]` rubric (route only on evidence, never a guess), §SelfAudit, §Teach, and a load-when references manifest. Added `references/project-shapes.md` (the shapes · four-axis · page-trio/DUO + an embedded structure rubric `[gate]`). The routing table targets the full 11-skill roster (`project` · `shells` · `data` · `genui` · `migrate` marked _building_).
+- **Phase 1b** — added the `adia-ui-project` skill (modes: new-app · add-surface · add-page · add-component · inventory; the page-trio/DUO choice as a `[gate]`; the `project-shapes.md` structure rubric as the verify target; the layout **mechanized** by the scaffolder, not hand-rolled). Extended `bin/adia-scaffold` with `page` (trio default, `--duo` for declarative) and `component` sub-commands — both emit lint-clean output and are covered by the scaffolder selftest.
+- **Phase 2 — shells.** Added the `adia-ui-shells` skill (one skill: a shell-selection decision table · the shared conventions · a shell-composition rubric `[gate]` as the verify target) with load-on-demand per-shell references `shell-admin.md` · `shell-chat.md` · `shell-editor.md` · `shell-simple.md`, plus `shell-embed.md` — the forthcoming `adia-embed-shell`, documented from the embedded-app pattern and clearly labeled emerging (`[PATTERN]` not `[SHELL-API]`). Extended `bin/adia-lint` with `NATIVE-PRIMITIVE` (raw `<button>`/`<input>` where a `*-ui` exists; slotted-trigger exception) and `LEGACY-SHELL` (retired ADR-0024 data-attribute shapes) audits — both selftested, generated scaffold output stays clean.
+- **Phase 3 — data & hydration.** Added the consolidated `adia-ui-data` skill (data-flow-pattern + hydration-path decision tables; the attribution `[gate]`; a data-flow rubric `[gate]` — single-owner state · projections-only · attribution · property-API · one reactive path — as the verify target) over `references/data-and-hydration.md` (the five patterns with code shapes, the three hydration paths incl. the **hybrid SPA-island-in-SSR**, section registration, the `router-ui` query-param pattern). Hardened `adia-ui-spa` + `adia-ui-ssr` to the standard (verify target + §SelfAudit) and reconciled both to defer the shared data depth to `adia-ui-data`, with the hybrid boundary called out.
+- **Phase 4 — generative UI.** Added the `adia-ui-genui` skill (the consumer build → generate → validate → render → refine loop; mount `<a2ui-root>` / `<gen-root>`; `registerResolver`; corpus core-vs-roll-your-own; a gen-UI rubric `[gate]` — validate-before-render · resolvers-registered · one-root-per-surface · grounded corpus) over `references/genui-a2ui.md` (render roots, the A2UI message union, resolvers, the loop, corpus). Hardened `adia-ui-llm` to the standard (verify target + an LLM-feature rubric `[gate]`: no-key-in-browser · all-stream-branches-handled · untrusted-output · right-path) and re-pointed UI generation to `adia-ui-genui`.
+- **Phase 5 — verify · migrate · compose.** Added the `adia-ui-migrate` skill (migration-type decision table; the 5-step discipline read→audit→sweep→verify→report; a migration rubric `[gate]` — audited-before-swept · sweeps-verified · judgment-items-flagged · no-leftover-drift) over `references/migration.md` (the real v0.0.20 / v0.4.0 / token-rename history + sweep patterns + leftover-drift categories + MCP aids). Hardened `adia-ui-verify` (a verify rubric `[gate]` that wires in `adia-lint` + the framework `audit:*`) and `adia-ui-compose` (a compose rubric `[gate]`; theming + the typographic registers `verse` / regular / `prose`). **All 11 v0.2 skills now carry the hardened standard** (mode + verify target + `[gate]` rubric + §SelfAudit).
+
+## [0.1.0] — 2026-06-03
+
+First release. An authoring plugin for the adia-ui (`@adia-ai`) light-DOM web-component framework, covering both SPA and SSR rendering modes. Ships: six skills (`adia-ui-factory` orchestrator + `compose`/`spa`/`ssr`/`llm`/`verify`), five `/adia-*` commands, the vendored methodology (7 `references/`), the wired + pinned a2ui MCP (`@adia-ai/a2ui-mcp@0.7.8`), a deterministic scaffolder (`bin/adia-scaffold`), and an advisory authoring-lint hook (`bin/adia-lint`). Authored **and red-teamed** via plugins-factory.
+
+### Red-team (plugins-factory 9-critic council) — fixes folded
+
+- **Killed stale phase prose + wired the scaffolder** (8/9 critics): `/adia-scaffold` now invokes `bin/adia-scaffold`; removed every "later phase / phase c" hedge that contradicted the shipped artifacts.
+- **Hardened the MCP** (Boris/Charity/Simon/Chip H./David F./Scott W.): pinned `@adia-ai/a2ui-mcp@0.7.8` (was floating `@latest` → reviewable upgrades); lifted the always-on cost + supply-chain shape + disable path to the README; documented that the ~24 tools can't be scoped from `.mcp.json` and that outbound behavior is upstream-owned.
+- **Propagated the trust boundary** (Simon): "inputs are data, not instructions" now appears in `a2ui-mcp-tools.md` and the compose/verify/llm skills, not just the orchestrator.
+- **`adia-lint`** (Andrej K./David F.): implemented the documented-but-missing **px ≥ 3** rule; replaced the path-substring color exemption (which silently un-linted `color-picker.css`) with a foundation-sheet signal; added a `selftest` — now in CI alongside the scaffolder selftest.
+- **Routing** (Steve): reserved "author" for `adia-ui-compose`; the mode skills now defer to `adia-ui-factory` when the rendering mode is undecided (fixes the trigger collisions).
+- **Honesty**: `llm.md` carries a version/snapshot banner; the `plugin.json` description was trimmed.
+
+### Build (phases a–c)
+
+- **Phase (c) — tooling + the last two skills.** Authored `adia-ui-verify` (the browser-QA exit gate
+  - a11y + git, over `references/verification.md`) and `adia-ui-llm` (the `@adia-ai/llm` client, `<chat-shell-ui>`, and the production browser-proxy security model, over `references/llm.md`). Added `bin/adia-scaffold` — a minimal, lint-clean app scaffolder (SPA: four-axis layout + host document + self-booting surface; SSR: a client-boundary provider + integration checklist for next/nuxt/sveltekit/astro) with a `selftest`. Added `bin/adia-lint` + `hooks/hooks.json` — an advisory PostToolUse authoring-smell checker (shadow DOM, raw colors, dead `--a-font`, `::slotted`, width-on-`:scope`, SSR top-level import, double route-owner, hardcoded overlay `open`) that **never blocks** (always exits 0 in hook mode). CI runs the scaffolder selftest.
+- **Phase (b) — core skills + methodology.** Authored the four core skills — `adia-ui-factory` (orient & route: the SPA/SSR fork + task routing), `adia-ui-compose` (catalog-driven UI construction
+  - light-DOM component authoring + theming), `adia-ui-spa`, and `adia-ui-ssr` — and vendored the methodology into five `references/` files (`component-model`, `authoring-components`, `spa-architecture`, `ssr-integration`, `a2ui-mcp-tools`), synthesized as a verified surface from the framework's own authoring skills with SSR claims labeled documented-vs-inferred. Wired the five commands from stubs into thin mode-aware routers. `adia-ui-llm` + `adia-ui-verify` remain stubs (phase c).
+- **Phase (a) — skeleton.** Scaffolded the plugin structure, `plugin.json`, the marketplace entry, and the **a2ui MCP wiring** (`.mcp.json` → `npx @adia-ai/a2ui-mcp`). Six skills and five commands stubbed with real frontmatter (routing surface live); content authored in later phases. Authored via plugins-factory.

package/README.md

@@ -0,0 +1,44 @@
+# adia-ui-factory
+
+**Author and verify apps built on the adia-ui (`@adia-ai`) framework** — a zero-dependency, light-DOM vanilla web-component library. A self-contained Claude Code plugin: it bundles the _authoring methodology_ and wires the framework's existing **a2ui MCP** as the live substrate for catalog retrieval, UI generation, and validation.
+
+> **Status: v0.2.2 — feature-complete, red-teamed.** Eleven skills across the full app-authoring lifecycle, the vendored methodology (16 load-on-demand references), the pinned a2ui MCP, two bins (`adia-scaffold` + `adia-lint`), and the advisory hook are in; the plugins-factory 9-critic council pass has been run and its fixes folded (`CHANGELOG.md`). Every skill is built to plugins-factory's hardened skill-architecture standard (cold-start surface · modes · per-mode verify target · a `[gate]` rubric · §SelfAudit · load-when references).
+
+## The shape
+
+`adia-ui-factory` is organized as the **app-authoring lifecycle** (orient → scaffold → compose/shell → wire → verify → migrate) over the load-bearing **rendering-mode** fork:
+
+```text
+adia-ui-factory/
+├── .mcp.json                 → wires @adia-ai/a2ui-mcp@0.7.8 (npx) — catalog, retrieval, generate_ui, validate
+├── skills/                   (11)
+│   ├── adia-ui-factory/      orient & route — classify mode + shape + shell + task (the hub)
+│   ├── adia-ui-project/      project shapes · four-axis layout · page-trio/DUO · scaffold
+│   ├── adia-ui-compose/      construct the UI — catalog literacy, component authoring, theming + registers
+│   ├── adia-ui-shells/       choose & compose a shell — admin · chat · editor · simple · embed (forthcoming)
+│   ├── adia-ui-spa/          SPA architecture — static host, content-less <router-ui>
+│   ├── adia-ui-ssr/          SSR integration — Next/Nuxt/SvelteKit/Astro, client-only registration
+│   ├── adia-ui-data/         data · state · hydration · fetch/CRUD · section wiring · hybrid SPA-in-SSR
+│   ├── adia-ui-llm/          app LLM features — @adia-ai/llm, chat, streaming, the smart proxy
+│   ├── adia-ui-genui/        generative-UI experiences — the a2ui runtime, generate_ui, corpus
+│   ├── adia-ui-verify/       the exit gate — browser QA + a11y + git
+│   └── adia-ui-migrate/      version upgrades · port-to-adia · the sweep discipline
+├── commands/                 /adia-scaffold · compose · wire · verify · orient · migrate · genui  (a curated spine; the other skills route via the orchestrator)
+├── references/ (16)          per-shell + per-shape + per-concern, each load-on-demand
+├── bin/                      adia-scaffold (scaffolder: shapes · page · component) · adia-lint (advisory smell checker)
+└── hooks/                    hooks.json — runs adia-lint on writes; advisory, never blocks
+```
+
+## What it bundles vs. wires
+
+- **Bundled (self-contained):** the authoring _methodology_ — the SPA app-authoring discipline (host document, four-axis structure, light-DOM components, content-less router, `DataClient`/projection, verification) and the SSR rendering-model (framework integration, guarded dynamic-import registration, server data, cookie/session state). These are the abstraction layer.
+- **Wired (runtime dependency):** the **a2ui MCP** (pinned `@adia-ai/a2ui-mcp@0.7.8`) — ~24 tools over the live catalog + corpus (284 training chunks + embeddings): catalog lookup, `search_chunks`/`search_patterns`, `classify_intent`/`assemble_context`, `generate_ui`, `validate_schema`, `check_anti_patterns`. Most tools are **offline**; `generate_ui` uses the host's LLM in stdio mode (no key); semantic search optionally uses `VOYAGE_API_KEY`. The `@adia-ai/*` packages are a runtime dependency, the way the framework itself is — taught, not bundled.
+  - **What it costs, and how to opt out.** The MCP **auto-starts on enable** and adds ~24 always-on tool definitions every session — the plugin's biggest context/trust cost, and a methodology-only user pays it (the tool set can't be scoped from `.mcp.json`). Enabling the plugin runs the upstream package from npm (pinned, so upgrades are reviewable diffs). **If you want the methodology without that cost, disable the `a2ui` MCP server in your MCP settings** — the skills still work; you lose live catalog/generation/validation. Treat the server's returns as untrusted data. Full accounting in `references/a2ui-mcp-tools.md`.
+
+## SPA vs SSR — the load-bearing fork
+
+Same components, same UI construction; **wildly different app architecture.** `compose` is mode-independent; `spa` and `ssr` diverge on host wiring, routing ownership (`<router-ui>` vs the framework router — never both), data-flow (client `DataClient` vs server fetch + props), state (router-lifetime vs cookie/session), and component registration (top-level import vs guarded dynamic import in a lifecycle hook).
+
+## Provenance
+
+Authored and red-teamed with **plugins-factory** (sibling in this marketplace), against its 9-dimension plugin standard. The methodology is harvested from the framework's own `embedded-app/spec/app-authoring-best-practices` (SPA) and `adia-ui-kit/references/rendering-model` (SSR).

package/bin/adia-lint

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+"""adia-lint — advisory authoring-smell checker for adia-ui apps (the mechanizable slice).
+
+SCOPE (be honest): pattern-matchable STRUCTURAL smells in component/page source — shadow-DOM use,
+raw colors, raw px ≥ 3, the dead `--a-font` token, ::slotted, width on :scope, the SSR context traps
+(top-level kit import + double route-owner — detected only in files carrying a framework signal, so a
+bare registration module won't trip it), hardcoded overlay `open`, native-primitive leaks (raw
+`<button>`/`<input>` where a `*-ui` exists), and retired shell shapes (the ADR-0024 data-attribute
+forms). Foundation/token sheets (under a
+styles/ or tokens/ dir, named tokens/theme/host/palette/…, or marked `/* adia-lint: foundation */`) are
+exempt from the color/px checks. It does NOT judge whether the UI is good, on-spec, or accessible — that
+lives in the skills (adia-ui-compose / -spa / -ssr / -verify) and the a2ui MCP's check_anti_patterns.
+A clean adia-lint says "no structural tells," never "this is right."
+
+Shared core: the regex bank below (RAW-COLOR/PX, SCOPE-EXTENT, NATIVE-PRIMITIVE, LEGACY-SHELL,
+the _is_foundation_css exemption) is mirrored in the sibling MAINTAINER plugin's
+adia-ui-forge/bin/forge-lint. They are deliberate VENDORED copies — the catalog forbids
+cross-plugin imports (each plugin installs copy-alone) — so any change to a shared rule must be
+reconciled in BOTH files. adia-lint keeps the consumer/app traps (SSR double-router, top-level
+import, hardcoded overlay open) that forge-lint drops; that divergence is the point.
+
+Usage:
+  adia-lint <file>...        # lint files; exit 1 if any smell found, else 0
+  adia-lint -                # lint stdin as a generic source file
+  adia-lint --hook           # PostToolUse hook mode: read event JSON on stdin, lint the written
+                             #   source file, print advisory findings, ALWAYS exit 0 (never blocks)
+  adia-lint selftest         # run built-in fixtures (seeded smells + a clean file + the hook exit-0 invariant)
+Stdlib only (Python 3.8+).
+"""
+import json
+import os
+import re
+import sys
+
+CODE_EXT = (".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx")
+STYLE_EXT = (".css",)
+MARKUP_EXT = (".html", ".htm", ".vue", ".svelte", ".astro", ".tsx", ".jsx")
+LINT_EXT = tuple(sorted(set(CODE_EXT + STYLE_EXT + MARKUP_EXT)))
+
+SSR_SIGNAL = re.compile(
+    r"""['"]use client['"]|\buseEffect\b|\bonMounted\b|\bonMount\b|"""
+    r"""from\s+['"](?:react|vue|svelte|next|nuxt|@sveltejs|astro)|"""
+    r"""getServerSideProps|defineNuxtComponent""", re.I)
+
+HEXCOLOR = re.compile(r"#[0-9a-fA-F]{3,8}\b")
+FUNCCOLOR = re.compile(r"\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\s*\(")
+DEAD_FONT = re.compile(r"var\(\s*--a-font\s*[,)]")
+SCOPE_EXTENT = re.compile(
+    r":scope(?:\[[^\]]*\])?\s*\{[^{}]*?\b(?:width|height|inline-size|block-size)\s*:", re.S)
+BOOL_TRUE = re.compile(r"\bdefault:\s*true\b")
+ATTR_TYPO = re.compile(r"\battr:\s*['\"]")
+OVERLAY_OPEN = re.compile(r"<(?:modal|drawer)-ui\b[^>]*?(?<![:.\w])\bopen\b(?!\s*=\s*\{)")
+NATIVE_PRIMITIVE = re.compile(r"<(?:button|input|select|textarea|dialog)(?![\w-])")  # raw native, not a *-ui
+LEGACY_SHELL = re.compile(
+    r"data-chat-(?:messages|input|empty|name)|data-editor-body|data-canvas\b|data-sidebar="
+    r"|data-pane-(?:side|grow)|<aside-ui\b|<dialog\s+data-command")  # retired shell shapes (ADR-0024)
+TOPLEVEL_IMPORT = re.compile(r"""^\s*import\s+['"]@adia-ai/web-components['"]\s*;?\s*$""")
+PX_GE = re.compile(r"(?<![\w.-])(\d+)px\b")   # integer px values; fractional (1.5px) deliberately not matched
+FOUNDATION_OPT_IN = re.compile(r"adia-lint:\s*foundation", re.I)
+# Genuine token/foundation SHEETS are exempt from color/px — matched by exact stem or a styles/ dir,
+# NOT a path substring (so a `color-picker` / `theme-toggle` component is still linted).
+FOUNDATION_STEMS = {"tokens", "token", "theme", "themes", "foundation", "foundations",
+                    "palette", "palettes", "host", "reset", "resets", "scheme", "schemes",
+                    "color", "colors"}
+
+
+def _ext(path):
+    return os.path.splitext(path or "")[1].lower()
+
+
+def _is_foundation_css(path, text):
+    """A genuine token/foundation sheet — exempt from color/px (component sheets are not)."""
+    segs = (path or "").replace("\\", "/").split("/")
+    if "styles" in segs or "tokens" in segs:
+        return True
+    stem = os.path.splitext(segs[-1])[0].lower() if segs else ""
+    if stem in FOUNDATION_STEMS:
+        return True
+    return bool(FOUNDATION_OPT_IN.search(text[:1000]))
+
+
+def lint_text(text, path=""):
+    """Return a list of (NAME, line, snippet, why) advisory findings."""
+    ext = _ext(path)
+    findings = []
+    is_ssr = bool(SSR_SIGNAL.search(text)) or ext in (".vue", ".svelte", ".astro")
+    is_tokenish = _is_foundation_css(path, text)
+
+    for i, line in enumerate(text.splitlines(), 1):
+        s = line.strip()[:90]
+        if "attachShadow" in line:
+            findings.append(("SHADOW-DOM", i, s,
+                             "adia-ui is light-DOM — never attachShadow; it breaks the token cascade + @scope"))
+        if "::slotted(" in line:
+            findings.append(("SLOTTED", i, s,
+                             "light DOM has no ::slotted — style projected content via :scope > [slot=\"x\"]"))
+        if ext in STYLE_EXT:
+            if DEAD_FONT.search(line):
+                findings.append(("DEAD-FONT-TOKEN", i, s,
+                                 "--a-font is not a real token (resolves to UA serif) — floor to var(--a-font-family-ui)"))
+            if not is_tokenish:
+                for decl in line.split(";"):  # per-declaration: a literal on a line that also has a var() still counts
+                    d = decl.strip()
+                    if not d or d.startswith(("//", "/*", "*")) or "var(" in decl or "light-dark(" in decl:
+                        continue
+                    if HEXCOLOR.search(decl) or FUNCCOLOR.search(decl):
+                        findings.append(("RAW-COLOR", i, s,
+                                         "component CSS is token-only — replace the literal with var(--a-*) (foundation/token files excepted)"))
+                        break
+            if not is_tokenish and not line.lstrip().startswith("@"):  # skip @media/@container/@scope at-rules
+                for decl in line.split(";"):
+                    if "/*" in decl:                                   # author-annotated carve-out
+                        continue
+                    if any(int(v) >= 3 for v in PX_GE.findall(decl)):
+                        findings.append(("RAW-PX", i, s,
+                                         "no raw px ≥ 3 in component CSS — use var(--a-space-*); 1–2px hairlines exempt, annotate a deliberate exception with a comment"))
+                        break
+        if ext in CODE_EXT:
+            if BOOL_TRUE.search(line):
+                findings.append(("BOOL-DEFAULT-TRUE", i, s,
+                                 "a boolean prop defaulting true can't be turned off by absence — flip the name so absent = false"))
+            if ATTR_TYPO.search(line):
+                findings.append(("ATTR-TYPO", i, s,
+                                 "did you mean `attribute:`? `attr:` is silently ignored in a property definition"))
+        if is_ssr:
+            if "<router-ui" in line:
+                findings.append(("SSR-DOUBLE-ROUTER", i, s,
+                                 "in SSR the framework router owns routing — don't also mount <router-ui> (two route owners)"))
+            if TOPLEVEL_IMPORT.search(line):
+                findings.append(("SSR-TOPLEVEL-IMPORT", i, s,
+                                 "a top-level kit import throws `HTMLElement is not defined` on the server — defer it into a client hook"))
+        if ext in MARKUP_EXT and OVERLAY_OPEN.search(line):
+            findings.append(("HARDCODED-OPEN", i, s,
+                             "drive overlays via the .open property, not a hardcoded `open` attribute (it bricks the page)"))
+        if (ext in MARKUP_EXT and "slot=" not in line and not s.startswith(("<!--", "//", "*", "/*"))
+                and NATIVE_PRIMITIVE.search(line)):
+            findings.append(("NATIVE-PRIMITIVE", i, s,
+                             "use the *-ui primitive (button-ui / input-ui / select-ui / textarea-ui / modal-ui) — raw natives skip focus rings, theming, and form association; a deliberate slotted trigger (with slot=) is the exception"))
+        if LEGACY_SHELL.search(line):
+            findings.append(("LEGACY-SHELL", i, s,
+                             "retired shell shape (ADR-0024, v0.4.0) — use the bespoke tag (chat-thread / chat-composer / chat-empty · admin-sidebar / admin-command · editor-canvas · pane-ui)"))
+
+    if ext in STYLE_EXT:
+        for m in SCOPE_EXTENT.finditer(text):
+            ln = text.count("\n", 0, m.start()) + 1
+            findings.append(("SCOPE-EXTENT", ln, ":scope { … width/height … }",
+                             "the component is size-agnostic — let the consumer own width/height; don't set extent on :scope"))
+
+    findings.sort(key=lambda f: (f[1], f[0]))
+    return findings
+
+
+def _render(path, findings):
+    out = [f"adia-lint: {len(findings)} structural smell(s) in {path or '<stdin>'}"]
+    for name, ln, snip, why in findings:
+        out.append(f"  [{name}] line {ln}: {snip}")
+        out.append(f"      → {why}")
+    return "\n".join(out)
+
+
+def _lint_path(path):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            return lint_text(f.read(), path)
+    except OSError as e:
+        return [("READ-ERROR", 0, path, f"failed to read file: {e}")]
+
+
+def _hook():
+    try:
+        event = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+    ti = event.get("tool_input", {}) or {}
+    path = ti.get("file_path", "") or ""
+    if _ext(path) not in LINT_EXT:
+        return 0  # only component/page source; stay quiet otherwise
+    text = ti.get("content")
+    if text is None:
+        if not os.path.isfile(path):
+            return 0
+        try:
+            with open(path, encoding="utf-8", errors="replace") as f:
+                text = f.read()
+        except OSError:
+            return 0
+    findings = lint_text(text, path)
+    if findings:
+        print(_render(path, findings))
+        print("  (advisory — adia-ui authoring smells; the skills + a2ui MCP own the judgment)")
+    return 0  # NEVER block
+
+
+def _selftest():
+    """Built-in fixtures: each seeded smell must fire, clean files must stay quiet, --hook must exit 0."""
+    import io
+    cases = [
+        ("components/x/x.css",
+         "@scope (x) {\n"
+         "  :scope { color:#f00; width:100%; font-family:var(--a-font); padding:24px; }\n"
+         "  :scope > [slot=a]::slotted(p) { margin:0; }\n"
+         "}",
+         {"RAW-COLOR", "SCOPE-EXTENT", "DEAD-FONT-TOKEN", "SLOTTED", "RAW-PX"}),
+        ("styles/theme.css", ":root { --a-bg: light-dark(#fff, #000); }", set()),
+        ("components/color-picker/color-picker.css",
+         "@scope (color-picker) {\n  :scope { background:#abc; padding:40px; }\n}",
+         {"RAW-COLOR", "RAW-PX"}),
+        ("providers/p.tsx",
+         "'use client';\nimport '@adia-ai/web-components';\n"
+         "export default () => (<admin-shell><router-ui/><modal-ui open>x</modal-ui></admin-shell>);",
+         {"SSR-TOPLEVEL-IMPORT", "SSR-DOUBLE-ROUTER", "HARDCODED-OPEN"}),
+        ("core/clean.js",
+         "import { UIElement } from '@adia-ai/web-components/core/element.js';\n"
+         "class UIX extends UIElement { connected() { this.innerHTML = '<col-ui></col-ui>'; } }",
+         set()),
+        ("markup/natives.html",
+         "<col-ui>\n  <button>Save</button>\n  <input type=\"text\">\n  <button-ui slot=\"trigger\">ok</button-ui>\n</col-ui>",
+         {"NATIVE-PRIMITIVE"}),
+        ("markup/legacy.html",
+         "<chat-shell>\n  <section data-chat-messages></section>\n  <chat-input-ui data-chat-input></chat-input-ui>\n</chat-shell>",
+         {"LEGACY-SHELL"}),
+    ]
+    ok = True
+    for name, text, expected in cases:
+        got = {f[0] for f in lint_text(text, name)}
+        if expected - got:
+            ok = False
+            print(f"selftest: {name} MISSING {sorted(expected - got)} (got {sorted(got)})", file=sys.stderr)
+        if not expected and got:
+            ok = False
+            print(f"selftest: {name} expected clean, got {sorted(got)}", file=sys.stderr)
+    saved_in, saved_out = sys.stdin, sys.stdout    # never-block invariant: --hook exits 0 even on smelly input
+    try:
+        sys.stdin = io.StringIO(json.dumps({"tool_input": {"file_path": "x.css",
+                                "content": "@scope (x) {\n :scope { color:#f00; }\n}"}}))
+        sys.stdout = io.StringIO()
+        rc = _hook()
+    finally:
+        sys.stdin, sys.stdout = saved_in, saved_out
+    if rc != 0:
+        ok = False
+        print("selftest: --hook did not exit 0 on smelly input", file=sys.stderr)
+    print("selftest: PASS" if ok else "selftest: FAIL")
+    return 0 if ok else 1
+
+
+def main(argv):
+    if argv and argv[0] == "selftest":
+        return _selftest()
+    if "--hook" in argv:
+        return _hook()
+    args = [a for a in argv if a == "-" or not a.startswith("-")]
+    if not args:
+        print(__doc__.strip().split("\n\n", 1)[0], file=sys.stderr)
+        return 2
+    total = 0
+    for path in args:
+        if path == "-":
+            findings = lint_text(sys.stdin.read(), "<stdin>")
+            path = "<stdin>"
+        else:
+            findings = _lint_path(path)
+        if findings:
+            total += len(findings)
+            print(_render(path, findings))
+    return 1 if total else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))