@adia-ai/adia-ui-factory 0.2.2 → 0.2.3

package/.claude-plugin/plugin.json

@@ -1,12 +1,21 @@
 {
   "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.",
+  "version": "0.2.3",
+  "description": "Author and verify apps built on the adia-ui (@adia-ai) light-DOM web-component framework \u2014 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"]
+  "keywords": [
+    "adia-ui",
+    "a2ui",
+    "web-components",
+    "app-authoring",
+    "ssr",
+    "spa",
+    "scaffolding",
+    "llm-ui"
+  ]
 }

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.2.3] — 2026-06-10
+
+- **Consumer-portability arc complete (T6).** `bin/adia-scaffold` now emits a working consumer serving setup — a `vite.config.js` + `package.json` in the SPA scaffold and `/node_modules/@adia-ai/...` paths (Vite-resolved) with a commented import-map/CDN fallback — replacing the monorepo-absolute paths that blank-screened bare consumers (GAP-1 P0). Doc gaps closed: `adia-ui-verify` `CLAUDE_PLUGIN_ROOT` gloss, `shell-embed.md` live worked example, `spa-architecture.md` consumer note (GAP-2/3/4). The 4 producer-command leaks in consumer migration guidance (`adia-ui-migration` + `adia-ui-kit/references/migration.md`) rewritten to consumer-portable verification — now enforced by the monorepo's **blocking** `check:factory-bare-repo` CI gate (the consumer-instruction half of ADR-0040, alongside `audit:plugin-coupling`).
+
+- **Consumer agent roster (2 cards) — dogfood-gated promotion.** The R5/T1 dogfood gate cleared: `screen-composer` composed the `embedded-app` patient-labs Live tab, passed `adia-ui-verify` (adia-lint 0 findings, browser render PASS, 7 `button-ui` / 0 raw natives, tab routing + Order action verified) — T1 evidence in `/tmp/t1-dogfood/`. Per the T1 Part-3 evidence the roster is **2 cards**: `app-architect` (Intent+Plan; pure read/orient, no scaffold) materialized + `screen-composer` (Execute + self-Evaluate) promoted DRAFT→PROMOTED. **`composition-reviewer` is a MODE of `screen-composer`** (it held the verify gate itself in the dogfood), not a separate card; **`app-migrator` is deferred** (promotion gate = a real consumer migration task). Routing-eval corpus added (`agents/routing-corpus.json` + `eval:agent-routing`, 92.9% accuracy). Bare-repo portability fixes folded from the prior cut: `adia-ui-spa` monorepo-path fix + `adia-ui-migration` producer-gate removal.
+
 ## [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`.

package/README.md

@@ -2,7 +2,7 @@
 
 **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).
+> **Status: v0.2.3 — consumer agent roster (2 cards).** Eleven skills + 2 agent cards (`app-architect` + `screen-composer`). The R5 dogfood gate cleared (screen-composer composed the embedded-app patient-labs Live tab, passed adia-ui-verify) and the **T1 keystone evidence** set the roster: `app-architect` (Intent+Plan) is materialized; **`composition-reviewer` is a MODE of `screen-composer`** (it held the verify gate itself in the dogfood), not a separate card; **`app-migrator` is deferred** until a real consumer migration task. The skills are built to plugins-factory's hardened standard (cold-start · modes · verify target · `[gate]` rubric · §SelfAudit · load-when references).
 
 ## The shape
 
@@ -11,6 +11,10 @@
 ```text
 adia-ui-factory/
 ├── .mcp.json                 → wires @adia-ai/a2ui-mcp@0.7.8 (npx) — catalog, retrieval, generate_ui, validate
+├── agents/                   (2) — the consumer-app-author roster (dogfood-gated; see roster design note)
+│   ├── app-architect.md      Intent + Plan — disambiguate brief, §SpecToUi, Orientation Record [PROMOTED]
+│   └── screen-composer.md    Execute + Evaluate — compose, scaffold, wire, then self-verify [PROMOTED]
+│                             (composition-review = screen-composer's mode, not a card · app-migrator deferred — T1 evidence)
 ├── 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
@@ -29,6 +33,25 @@ adia-ui-factory/
 └── hooks/                    hooks.json — runs adia-lint on writes; advisory, never blocks
 ```
 
+### The consumer-app-author agent roster
+
+The **Intent → Plan → Execute → Evaluate → Iterate** loop for consumer app authoring:
+
+```
+app-architect ──▶ screen-composer ──▶ ship
+(Intent+Plan)       (Execute + self-Evaluate; loop if < bar)
+composition-review = screen-composer's verify mode · app-migrator deferred
+```
+
+| Agent | Owns | Model | Status |
+|---|---|---|---|
+| `app-architect` | Intent + Plan: brief → §SpecToUi → Orientation Record | opus | PROMOTED |
+| `screen-composer` | Execute + Evaluate: scaffold + compose + wire + trust gate + self-verify | sonnet | PROMOTED |
+| _composition-review_ | a **mode** of screen-composer (not a separate card) | — | folded |
+| _app-migrator_ | Steward: version upgrades, migration sweeps | — | DEFERRED (not materialized) |
+
+Roster design + 5-critic synthesis: `.brain/notes/factory-agent-roster-design-2026-06-08.md`. Promotion gate (T1) passed 2026-06-08 — see `agents/screen-composer.md` STATUS header.
+
 ## 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.

package/bin/adia-scaffold

@@ -62,6 +62,8 @@ def _spa_files(name):
         f"app/{tag}/src/index.css": _SPA_PAGE_CSS.format(tag=tag),
         f"app/{tag}/src/components/{tag}/{tag}.js": _SPA_JS.format(tag=tag, cls=cls, title=title),
         f"app/{tag}/src/components/{tag}/{tag}.css": _SPA_CSS.format(tag=tag),
+        f"app/{tag}/vite.config.js": _VITE_CONFIG.format(tag=tag),
+        f"app/{tag}/package.json": _PKG_JSON.format(tag=tag, title=title),
     }
 
 
@@ -72,15 +74,47 @@ _SPA_HTML = """<!doctype html>
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>{title}</title>
 
-  <!-- Cascade order is load-bearing (later wins). Paths assume the kit is served at
-       /packages/web-components — adjust to how YOU serve @adia-ai (npm, a Vite alias, a CDN). -->
-  <link rel="stylesheet" href="/packages/web-components/styles/host.css" />   <!-- foundation: tokens + resets + page frame -->
-  <link rel="stylesheet" href="/packages/web-components/styles/index.css" />  <!-- barrel: every component's CSS (link BOTH) -->
-  <link rel="stylesheet" href="./index.css" />                               <!-- page framing -->
-  <link rel="stylesheet" href="./components/{tag}/{tag}.css" />              <!-- the surface's chrome -->
+  <!--
+    HOW TO SERVE @adia-ai/web-components — pick one:
+
+    A) Vite (recommended, npm consumer): run `npm install` then `vite` from app/{tag}/.
+       Vite resolves @adia-ai/* bare specifiers from node_modules automatically; the
+       importmap below is NOT needed in this mode (Vite transforms it away).
+       The vite.config.js next to this file wires the dev server root correctly.
+
+    B) Import-map (no bundler, e.g. native browser modules or a CDN):
+       Uncomment the importmap block below and point the paths to wherever the
+       @adia-ai packages are served — a local static server, esm.sh, or unpkg.
+       The CSS <link> hrefs must also point to the same location.
+
+    C) Monorepo / dev server (framework contributors only):
+       The /packages/web-components/... paths below resolve when the monorepo
+       vite dev server is running. This is NOT a consumer deployment mode.
+
+    Cascade order is load-bearing (later wins):
+      foundation (host.css) → barrel components (index.css) → page framing → surface chrome
+  -->
+
+  <!--
+  OPTION B — import-map (uncomment + adjust URLs when not using Vite):
+  <script type="importmap">
+  {{
+    "imports": {{
+      "@adia-ai/web-components": "https://esm.sh/@adia-ai/web-components",
+      "@adia-ai/web-components/": "https://esm.sh/@adia-ai/web-components/"
+    }}
+  }}
+  </script>
+  -->
+
+  <!-- OPTION A/B: CSS — with Vite these resolve via node_modules; without Vite, adjust the hrefs. -->
+  <link rel="stylesheet" href="/node_modules/@adia-ai/web-components/styles/host.css" />   <!-- foundation: tokens + resets + page frame -->
+  <link rel="stylesheet" href="/node_modules/@adia-ai/web-components/styles/index.css" />  <!-- barrel: every component's CSS (link BOTH) -->
+  <link rel="stylesheet" href="./index.css" />                                              <!-- page framing -->
+  <link rel="stylesheet" href="./components/{tag}/{tag}.css" />                            <!-- the surface's chrome -->
 
-  <!-- One registration script: registers every primitive (including router-ui). -->
-  <script type="module" src="/packages/web-components/index.js"></script>
+  <!-- One registration script: registers every primitive (including router-ui).
+       Bare @adia-ai/* specifiers resolve via Vite (node_modules) or the importmap above. -->
   <script type="module" src="./components/{tag}/{tag}.js"></script>
 </head>
 <body>
@@ -89,6 +123,48 @@ _SPA_HTML = """<!doctype html>
 </html>
 """
 
+_VITE_CONFIG = """import {{ defineConfig }} from 'vite';
+import {{ resolve }} from 'node:path';
+
+// Consumer vite config for {tag}.
+// Run: npm install && npx vite
+//
+// Vite resolves @adia-ai/* bare specifiers from node_modules automatically.
+// The root is set to src/ so index.html is the entry point and relative CSS/JS
+// paths resolve correctly without the /node_modules/... prefix needed in the
+// html file when served statically.
+export default defineConfig({{
+  root: 'src',
+  server: {{
+    open: true,
+  }},
+  build: {{
+    outDir: '../dist',
+    emptyOutDir: true,
+  }},
+}});
+"""
+
+_PKG_JSON = """{{
+  "name": "{tag}",
+  "version": "0.1.0",
+  "description": "{title}",
+  "private": true,
+  "type": "module",
+  "scripts": {{
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  }},
+  "dependencies": {{
+    "@adia-ai/web-components": "latest"
+  }},
+  "devDependencies": {{
+    "vite": "^5.0.0"
+  }}
+}}
+"""
+
 _SPA_PAGE_CSS = """/* Page framing — size + center the surface. Tokens only; never re-roll :where(html,body). */
 {tag} {{
   display: block;
@@ -244,9 +320,12 @@ _PAGE_HTML = """<!doctype html>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>{title}</title>
-  <link rel="stylesheet" href="/packages/web-components/styles/host.css" />
-  <link rel="stylesheet" href="/packages/web-components/styles/index.css" />
-  <script type="module" src="/packages/web-components/index.js"></script>
+  <!-- CSS: with Vite these resolve via node_modules; without Vite, adjust the hrefs
+       (or see spa-architecture.md for the importmap / CDN options). -->
+  <link rel="stylesheet" href="/node_modules/@adia-ai/web-components/styles/host.css" />
+  <link rel="stylesheet" href="/node_modules/@adia-ai/web-components/styles/index.css" />
+  <!-- @adia-ai/* bare specifiers resolve via Vite (node_modules) or an importmap. -->
+  <script type="module" src="/node_modules/@adia-ai/web-components/index.js"></script>
 </head>
 <body>
   <main id="page-root"><p>Loading…</p></main>
@@ -336,8 +415,9 @@ def _selftest():
     with tempfile.TemporaryDirectory() as tmp:
         _, w, _ = _scaffold("spa", "Demo App", None, tmp, False)
         need = [f for f in w if f.endswith(("index.html", "demo-app.js", "demo-app.css"))]
-        if not any(f.endswith("index.html") for f in w) or len(w) < 6:
-            print("selftest: SPA scaffold incomplete", file=sys.stderr); ok = False
+        missing = [n for n in ("index.html", "vite.config.js", "package.json") if not any(f.endswith(n) for f in w)]
+        if missing or len(w) < 8:
+            print(f"selftest: SPA scaffold incomplete (missing: {missing}, got {len(w)} files)", file=sys.stderr); ok = False
         for fw in ("next", "nuxt", "sveltekit", "astro"):
             _, w2, _ = _scaffold("ssr", f"demo-{fw}", fw, tmp, False)
             if not any("README.md" == f for f in w2) or len(w2) != 2:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adia-ai/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.",
+  "version": "0.2.3",
+  "description": "Author and verify apps built on the adia-ui (@adia-ai) light-DOM web-component framework \u2014 scaffold, compose, wire, and verify across both SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "keywords": [
     "adia-ui",
     "a2ui",

package/references/shell-embed.md

@@ -28,6 +28,16 @@ An **embedded surface** is a self-contained light-DOM custom element that a _hos
 4. Keep it size-agnostic; let the host place it.
 5. Verify in a host harness (renders, zero console errors, non-zero box) — `adia-ui-verify`.
 
+## Live worked example
+
+The canonical implementation of this pattern is `apps/embedded-app/` in the adia-ui monorepo — the patient-labs and population-health surfaces built to the shared-foundation shape. Use it as the reference when authoring a new embedded surface:
+
+- `apps/embedded-app/app/patient-labs/` — patient-labs surface (full Live/Labs/History/Briefing tab set, DataClient projection wiring, ambient-pill footer)
+- `apps/embedded-app/app/population-health/` — population-health surface (coverage metrics, facility breakdown)
+- `apps/embedded-app/app/shared/` — DataClient, CorpusLoader, mappers, shared tokens
+
+If you have access to the monorepo, read `apps/embedded-app/` before authoring a new embedded surface — the shape is proven and annotated.
+
 ## When it ships
 
 The official `adia-embed-shell` is expected to package this chrome (the panel layout, the host-placement contract, the embed bridge) as a web-module like the others. At that point: register via the cluster barrel, replace the hand-rolled container chrome with the shell, and keep the DataClient/projection + attribution wiring. Until then, the pattern above **is** the contract.

package/references/spa-architecture.md

@@ -26,6 +26,13 @@ One static `index.html` whose job is to load CSS in cascade order and register c
 </html>
 ```
 
+> **Note — monorepo paths vs real npm consumer.** The `/packages/web-components/...` paths above only resolve inside the AdiaUI monorepo dev server. A real npm consumer has two options:
+>
+> - **Vite (recommended):** `npm install @adia-ai/web-components`, add a `vite.config.js` (the `adia-scaffold spa` bin emits one), then replace the paths with `/node_modules/@adia-ai/web-components/styles/host.css` etc. — Vite serves node_modules at that prefix during dev and bundles them at build time. Bare `@adia-ai/*` specifiers in `.js` files resolve automatically.
+> - **Import-map / CDN (no bundler):** add an `<script type="importmap">` mapping `"@adia-ai/web-components"` to your CDN URL (e.g. `https://esm.sh/@adia-ai/web-components`), and adjust the CSS link hrefs to match.
+>
+> The `adia-scaffold spa` output is pre-wired for the Vite path (`vite.config.js` + `package.json` included).
+
 **Cascade order is load-bearing** (later wins): foundation → barrel → register → page → component. Invariants:
 
 - Link **both** `host.css` and `styles/index.css`. Post-0.7.6 the barrel was split — `host.css` is foundation-only, so linking it alone renders primitives unstyled.

package/skills/adia-ui-kit/CHANGELOG.md

@@ -0,0 +1,41 @@
+# adia-ui-kit (factory plugin edition) Changelog
+
+## 0.1.0 (2026-06-07)
+
+**Initial release — consumer distillation per ADR-0040 Phase 1b.**
+
+Creates the shareable consumer `adia-ui-kit` skill inside the
+`adia-ui-factory` plugin. This is the **consumer composition knowledge**
+distilled from `.agents/skills/adia-ui-kit/` v3.11.0, decoupled so a
+consumer with NO `@adia-ai` monorepo can use it. Passes the bare-repo gate
+(`npm run audit:plugin-coupling:strict` → 0 RUNTIME-USE).
+
+**Scope:**
+
+- **SKILL.md** — consumer composition guidance adapted to the portable
+  consumer voice; `@adia-ai` specifics cited as clearly-labeled
+  worked-examples. Excludes maintainer-only material (monorepo-audit gates,
+  `.brain/` ops, repo-maintenance procedures, release/ops coupling).
+- **51 references/** — full consumer reference set: all patterns-*.md,
+  flows-*.md, composition, catalog-lookup, setup, css-policy, mcp, harness,
+  theme, state, migration, rendering-model, figma-make, local-link,
+  spec-to-ui-reasoning, reasoning-gate, mission, recon, gap-detection,
+  diagnostic-output, mode-routing, capabilities, decision-model,
+  component-literacy, pev-rationale, reasoning-methodologies,
+  correction-loop, common-gotchas-consumer, docs-catalog, session-log-*,
+  feedback-authoring, exclusions, response-authoring, teach-protocol,
+  skill-hygiene, version-check, loading-protocol + changelog-archive/.
+  Excluded: audit-scripts.md (monorepo path refs), team-tickets.md,
+  ticket-tooling.md, autocapture.md (all tied to .agents/team/tickets/).
+- **6 scripts/** — consumer-safe only: audit-kit-roster.mjs (standalone,
+  audit-axes inlined — no .agents/shared/ import), validate-session-log.mjs,
+  audit-decision-trace.mjs, changelog-archive.mjs, run-skill-evals.mjs,
+  check-adia-versions.py. Excluded: audit-kit-recipes.mjs (reads
+  packages/web-components/), audit-native-primitive-leak.mjs (same),
+  audit-shell-composition.mjs (same), teach-route.mjs (outputs .agents/
+  paths as suggestions; excluded per task scope), ticket-tool.py (reads
+  .agents/team/).
+- **4 eval corpora** — routing-corpus.json, evals.json,
+  adversarial-content-trust.json, teach-routing-cases.json.
+- **Registration** — factory plugin auto-discovers skills via `skills/*/SKILL.md`
+  directory scan (no explicit plugin.json enumeration needed).