@adia-ai/adia-ui-forge 0.8.37 → 0.8.39

package/skills/package-release/scripts/package-paths.mjs

@@ -2,21 +2,21 @@
 // standalone CHANGELOG helpers.
 //
 // THE PROBLEM (bit all 6 a2ui packages at the v0.7.14 cut):
-//   The 6 a2ui packages live on disk under `packages/a2ui/<x>/` but carry the
+//   The 6 a2ui packages live on disk under `packages/gen-ui/a2ui/<x>/` but carry the
 //   flat npm-name `a2ui-<x>` everywhere else in the tooling (release-pack.mjs,
 //   dispatch-publish.mjs, tag-lockstep.mjs all use the NAME form). The two
 //   standalone helpers (promote-unreleased.mjs, insert-stub.mjs) joined
 //   `packages/<arg>/CHANGELOG.md` with the raw arg, so calling them with the
 //   name form silently 404'd: `CHANGELOG.md not found at packages/a2ui-corpus/`.
-//   release-pack.mjs maps internally (`a2ui-corpus` → `packages/a2ui/corpus`),
+//   release-pack.mjs maps internally (`a2ui-corpus` → `packages/gen-ui/a2ui/corpus`),
 //   so the two forms diverged: name-form failed standalone, path-form failed
 //   when handed to the orchestrator-style callers.
 //
 // THE FIX:
 //   Accept BOTH forms. Try `packages/<arg>` first (path form, backward-compat).
 //   If that directory is absent AND the arg matches `a2ui-<x>`, fall back to
-//   `packages/a2ui/<x>`. So `a2ui-corpus` (name) and `a2ui/corpus` (path) both
-//   resolve to `packages/a2ui/corpus/`.
+//   `packages/gen-ui/a2ui/<x>`. So `a2ui-corpus` (name) and `a2ui/corpus` (path) both
+//   resolve to `packages/gen-ui/a2ui/corpus/`.
 //
 // Pure Node, stdlib only — keeps the scripts free of runtime deps.
 
@@ -55,12 +55,11 @@ import path from 'node:path';
 // trip-wire (check-release.mjs's per-tag `checkTag` lookup) reads the FULL
 // roster unfiltered — every pushed tag, lockstep or not, still needs its
 // package.json/CHANGELOG validated, so it must recognize a class-B tag too.
-// `shim` (added ADR-0048 P5): `true` marks an old npm name riding exactly ONE
-// cut as a re-export shim before retirement. It changes NOTHING about how the
-// cut treats the entry — a shim versions, tags, publishes and changelogs like
-// any other lockstep member. It exists so P7's retirement PR has a mechanical
-// answer to "which rows go away", instead of a name list someone has to
-// re-derive from a doc. Absent = a permanent package.
+//
+// `shim: true` (ADR-0048 P5) marked the six retired a2ui-* names for their
+// single 0.8.37 bridge cut; the P7 follow-up PR deleted those rows together
+// with packages/shims/. No row carries the flag anymore, and none may — a
+// future one-cut bridge re-introduces the marker with its own retirement PR.
 //
 // Every lockstep-scoped consumer must filter `p.lockstep !== false` itself
 // (this module intentionally does NOT pre-filter PACKAGE_NAMES/PACKAGE_DIRS —
@@ -69,9 +68,9 @@ import path from 'node:path';
 export const PACKAGE_ROSTER = [
   { name: 'web-components',  dir: 'packages/web-components',           lockstep: true },
   { name: 'web-modules',     dir: 'packages/web-modules',               lockstep: true },
-  { name: 'llm',             dir: 'packages/llm',                       lockstep: true },
-  { name: 'agent',           dir: 'packages/agent',                     lockstep: true },
-  { name: 'persona',         dir: 'packages/persona',                   lockstep: true },
+  { name: 'llm',             dir: 'packages/llm/core',                       lockstep: true },
+  { name: 'agent',           dir: 'packages/llm/agent',                     lockstep: true },
+  { name: 'persona',         dir: 'packages/llm/persona',                   lockstep: true },
   // ── ADR-0048 P5 — the estate split's published names ────────────────────
   //
   // The successors of the six old a2ui-* names. `a2ui`/`gen-ui` join here,
@@ -83,32 +82,19 @@ export const PACKAGE_ROSTER = [
   // `mcp` (gh#1240, operator ruling 2026-08-14, roster 17 → 16): folds what
   // were TWO planned rows — `gen-ui-mcp` (P2 rename target) and
   // `a2ui-protocol-mcp` (minted fresh at P4) — into ONE published name,
-  // `@adia-ai/mcp`, at `packages/mcp/`. Neither predecessor name ever
+  // `@adia-ai/mcp`, at `packages/gen-ui/mcp/`. Neither predecessor name ever
   // published a 0.8.x, so this fold has no npm deprecation cycle to run —
-  // unlike the SIX old a2ui-* shims below, which really did publish and need
-  // one. The two-SERVER decision (ADR-0048 §3) is unchanged; only the
-  // npm-distribution row count dropped by one.
-  { name: 'a2ui',              dir: 'packages/a2ui',                    lockstep: true },
-  { name: 'gen-ui',            dir: 'packages/gen-ui',                  lockstep: true },
-  { name: 'mcp',               dir: 'packages/mcp',                     lockstep: true },
-  // ── ADR-0048 P5 — the six old names, riding EXACTLY ONE cut as shims ────
-  //
-  // `npm unpublish` is impossible, so each retired name gets one final publish
-  // as a re-export shim (packages/shims/<name>, generated by
-  // scripts/build/generate-shims.mjs) plus an `npm deprecate` pointer run
-  // post-publish. They are on the roster only so that cut versions, tags,
-  // CHANGELOGs and publish workflows treat them like any other package.
-  //
-  // `shim: true` is the retirement marker, not decoration: P7's follow-up PR
-  // deletes exactly the entries carrying it, together with packages/shims/,
-  // their publish workflows, and resolvePackageDir's `shims/` fallback below.
-  // Nothing else in the roster is allowed to carry it.
-  { name: 'a2ui-runtime',    dir: 'packages/shims/a2ui-runtime',        lockstep: true, shim: true },
-  { name: 'a2ui-compose',    dir: 'packages/shims/a2ui-compose',        lockstep: true, shim: true },
-  { name: 'a2ui-corpus',     dir: 'packages/shims/a2ui-corpus',         lockstep: true, shim: true },
-  { name: 'a2ui-mcp',        dir: 'packages/shims/a2ui-mcp',            lockstep: true, shim: true },
-  { name: 'a2ui-retrieval',  dir: 'packages/shims/a2ui-retrieval',      lockstep: true, shim: true },
-  { name: 'a2ui-validator',  dir: 'packages/shims/a2ui-validator',      lockstep: true, shim: true },
+  // unlike the SIX old a2ui-* names, which really did publish and got one
+  // (shim rows retired below). The two-SERVER decision (ADR-0048 §3) is
+  // unchanged; only the npm-distribution row count dropped by one.
+  { name: 'a2ui',              dir: 'packages/gen-ui/a2ui',                    lockstep: true },
+  { name: 'gen-ui',            dir: 'packages/gen-ui/engine',                  lockstep: true },
+  { name: 'mcp',               dir: 'packages/gen-ui/mcp',                     lockstep: true },
+  // The six retired a2ui-* names (a2ui-runtime/-compose/-corpus/-mcp/
+  // -retrieval/-validator) rode EXACTLY the 0.8.37 cut here as `shim: true`
+  // rows under packages/shims/, then the P7 follow-up PR deleted them
+  // (cut-procedure.md §0.8.38 precondition 1). Their npm names are
+  // deprecated pointers; nothing may re-add them.
   // Plugins joined the lockstep 2026-07-15 (check-lockstep.mjs POLICY note);
   // each carries a .claude-plugin/plugin.json that bumps with package.json.
   { name: 'adia-ui-factory', dir: 'packages/plugins/adia-ui-factory',   lockstep: true, plugin: true },
@@ -135,19 +121,17 @@ export const PACKAGE_DIRS = PACKAGE_ROSTER.map((p) => p.dir);
 // require the directory to exist (so callers can render a legible not-found
 // error against the resolved path).
 export function resolvePackageDir(repo, pkg) {
+  // Roster name-form first (ADR-0049): `llm` must resolve to the roster's
+  // `packages/llm/core`, never to the bare `packages/llm/` FAMILY GROUPING
+  // dir that now exists on disk (no package.json, no CHANGELOG) — an
+  // existsSync-first probe would hit the grouping dir and silently target
+  // a non-package. Same for `gen-ui` → `packages/gen-ui/engine`.
+  const row = PACKAGE_ROSTER.find((p) => p.name === pkg);
+  if (row) return path.relative('packages', row.dir);
   if (fs.existsSync(path.join(repo, 'packages', pkg))) return pkg;
-  // ADR-0048 P3 — the old a2ui-* names now live at packages/shims/<old-name>.
-  // Tried before the legacy packages/a2ui/<x> nesting below so the shim wins
-  // while both could exist; both fallbacks die when P5 retires the shims.
-  if (/^a2ui-/.test(pkg)) {
-    const shim = path.join('shims', pkg);
-    if (fs.existsSync(path.join(repo, 'packages', shim))) return shim;
-  }
-  const m = /^a2ui-(.+)$/.exec(pkg);
-  if (m) {
-    const nested = path.join('a2ui', m[1]);
-    if (fs.existsSync(path.join(repo, 'packages', nested))) return nested;
-  }
+  // (The historical a2ui-* fallbacks — packages/shims/<old-name> and the
+  // pre-split packages/gen-ui/a2ui/<x> nesting — died with the shim-deletion
+  // follow-up PR after the 0.8.37 cut; a2ui-gen-ui-split.md ruled both dead.)
   // Plugins live under packages/plugins/<name> but carry the flat name form
   // (adia-ui-forge) in the release tooling — same name-vs-path split as a2ui.
   if (/^adia-ui-/.test(pkg)) {

package/skills/package-release/scripts/release-pack.mjs

@@ -222,8 +222,8 @@ function help() {
     --gh-notes-file /tmp/release-v$X.Y.Z.md \\
     --substantive "<one-line>" \\
     --xref "packages/web-modules/CHANGELOG.md#0$X$Y$Z--YYYY-MM-DD" \\
-    --substantive-packages web-components,web-modules,a2ui/corpus \\
-    --stub-packages llm,a2ui-compose,a2ui-mcp,a2ui-retrieval,a2ui-runtime,a2ui-validator
+    --substantive-packages web-components,web-modules,gen-ui \\
+    --stub-packages llm,agent,persona,a2ui,mcp,adia-ui-factory,adia-ui-forge
 
 Flags: --go   (single-authorization: the operator's cut-start go covers the
                whole cycle — auto-confirms ALL checkpoints; stops only on
@@ -704,8 +704,9 @@ function step5Commit(args) {
     ...LOCKSTEP_ROSTER.flatMap(({ name, dir, plugin }) => {
       // Roster-driven (H3): each package stages its manifest + CHANGELOG;
       // plugins also stage .claude-plugin/plugin.json (the /plugin-update
-      // cache key, moved by bump.mjs); factory additionally pins a2ui-mcp in
-      // .mcp.json (SKILL invariant 8 — bump.mjs moves the pin too).
+      // cache key, moved by bump.mjs); factory additionally pins the
+      // generation MCP (@adia-ai/mcp) in .mcp.json (SKILL invariant 8 —
+      // bump.mjs moves the pin too).
       const files = [`${dir}/package.json`, `${dir}/CHANGELOG.md`];
       if (plugin) files.push(`${dir}/.claude-plugin/plugin.json`);
       if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`);
@@ -1167,7 +1168,13 @@ function selftest() {
       guardFailed = true;
       guardOut = (e.stdout || '') + (e.stderr || '');
     }
-    if (!guardFailed || !guardOut.includes('ride-along') || !guardOut.includes('a2ui-validator')) {
+    // The expected ride-alongs are DERIVED from the roster (everything but
+    // the one --substantive-packages entry above), never transcribed — a
+    // hard-coded name here went stale when the shim-deletion follow-up PR
+    // shrank the roster 16 → 10 (the same never-transcribe rule the cut
+    // docs enforce on every other roster projection).
+    const expectedRideAlongs = PACKAGES.filter((p) => p !== 'web-components');
+    if (!guardFailed || !guardOut.includes('ride-along') || !expectedRideAlongs.every((p) => guardOut.includes(p))) {
       console.error('selftest FAIL: from-scratch without --stub-packages must hard-reject at parse time, naming the ride-alongs');
       process.exit(1);
     }

package/skills/package-release/scripts/tag-lockstep.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // tag-lockstep.mjs — create the lockstep tag set (umbrella vX.Y.Z + one
 // per-package <pkg>-vX.Y.Z per roster entry — package-paths.mjs is the
-// live census; 17 tags as of gh#1240) at HEAD or at a specified SHA.
+// live census; 11 tags as of gh#1282) at HEAD or at a specified SHA.
 //
 // Usage:
 //   node tag-lockstep.mjs --version 0.6.22

package/skills/primitive-authoring/references/common-gotchas.md

@@ -125,7 +125,7 @@ async #loadContent(route) {
 
 ## 7. Minting a wrapper-shaped component before its registry.js entry lands — site-a2ui silently deletes the node, not just mis-types it
 
-**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/a2ui/registry.js`'s hand-maintained `registry` map — inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved — `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either — `reverseRegistry` is a one-time init snapshot, not live. Regenerate a site-a2ui row for a demo using a component minted in the SAME change, before its `registry.js` line lands, and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183) — same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after — "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all — not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh`/`verify:site-a2ui` both report clean.
+**Pattern**: a tag is gated first and only, for `*-ui` tags, by `packages/gen-ui/a2ui/registry.js`'s hand-maintained `registry` map — inverted into `reverseRegistry` at `transpiler-maps.js`'s module init, consulted first thing in `compose/transpiler/transpiler.js:149-150`. `registry.js` is hand-edited, not generated by `node scripts/build/components.mjs` (that script writes sidecars/prop-catalog data, consumed only for prop-extraction fidelity on tags the transpiler ALREADY resolved — `transpiler-maps.js:22-26`); a runtime `registerType()` call doesn't rescue a stale row either — `reverseRegistry` is a one-time init snapshot, not live. Regenerate a site-a2ui row for a demo using a component minted in the SAME change, before its `registry.js` line lands, and the tag falls through to `transpiler.js`'s "Unknown → Column" branch (line 180-183) — same mechanism as gh#535's toolbar-group breakage, which at least rendered visibly-wrong. A NEW component is usually wrapper-shaped (one child, author-defined attributes like `anchor="bottom"` the transpiler doesn't map to any real A2UI prop). That shape trips a SECOND, separate rule right after — "single-child container chains flatten" (`transpiler.js:282-285`): a retyped Column with exactly one child and zero recognized props is discarded outright, and its child is spliced directly into the PARENT's children in its place. The wrapper's own id and node are never pushed to the tree at all — not visible-but-wrong, just gone. The row is then internally self-consistent (content hash matches source) so `check:chunks-fresh`/`verify:site-a2ui` both report clean.
 
 **Example**: minting `anchor-bar-ui` (gh#495, PR #569) and regenerating the `bulk-action-toolbar` pattern's site-a2ui row before the worktree's `registry.js` entry for it existed. Git-verified on the pre-fix commit (`ebf71832d`): `site-a2ui/pages/site__patterns__bulk-action-toolbar.a2ui.json` contains zero occurrences of `pat-bulk-float-bar` (the anchor-bar-ui's own authored id) anywhere — not retyped-and-visible, genuinely absent — while its single child (the toolbar content) survived, reparented one level up. `verify:site-a2ui` reported 321/321 clean.
 

package/skills/primitive-authoring/references/css-patterns.md

@@ -223,7 +223,7 @@ AdiaUI is light-DOM. Slotted children are just children. Style them with attribu
 }
 
 :scope > header > [slot="heading"] {
-  font-weight: var(--a-font-weight-strong);
+  font-weight: var(--a-weight-semibold);
 }
 
 /* WRONG — ::slotted() is for shadow DOM */

package/skills/primitive-authoring/references/llm-bridge.md

@@ -7,9 +7,9 @@ are the current, maintained source — this file is kept only as a historical po
 no longer linked from `primitive-authoring`'s task-shape table or `code-style.md`. Route provider/
 streaming/bridge work to `llm-client-maintenance`.
 
-Use when adding a 4th provider, modifying `createAdapter()`, changing the streaming chunk shape, or extending `packages/llm/server.js`.
+Use when adding a 4th provider, modifying `createAdapter()`, changing the streaming chunk shape, or extending `packages/llm/core/server.js`.
 
-This reference is about **modifying** the package. For day-to-day consumption (import + call), the README at `packages/llm/README.md` is sufficient.
+This reference is about **modifying** the package. For day-to-day consumption (import + call), the README at `packages/llm/core/README.md` is sufficient.
 
 ---
 
@@ -18,7 +18,7 @@ This reference is about **modifying** the package. For day-to-day consumption (i
 - Adding a new provider adapter (e.g., DeepSeek, Cohere, Mistral)
 - Changing `maxTokens`, `temperature`, or another bridge default
 - Extending the streaming chunk type set (currently: `text` / `thinking` / `done` / `error`)
-- Adding a new endpoint to `packages/llm/server.js`
+- Adding a new endpoint to `packages/llm/core/server.js`
 - Modifying the bridge's `complete()` / `stream()` shape
 - Debugging "why does my LLM call return truncated JSON?"
 
@@ -112,7 +112,7 @@ If you add a new endpoint, document it in the npm README under "Browser proxy mo
 
 ### Step 1: Create the adapter
 
-`packages/llm/adapters/<name>.js` exports a single object matching the shape used by anthropic / openai / gemini:
+`packages/llm/core/adapters/<name>.js` exports a single object matching the shape used by anthropic / openai / gemini:
 
 ```js
 import { readSSE } from './sse.js';
@@ -139,7 +139,7 @@ export const myProvider = {
 
 ### Step 2: Register in the facade
 
-Edit `packages/llm/adapters/index.js`:
+Edit `packages/llm/core/adapters/index.js`:
 
 ```js
 import { myProvider } from './myprovider.js';
@@ -154,7 +154,7 @@ function detectProvider(model) {
 
 ### Step 3: Subpath export
 
-Edit `packages/llm/package.json`:
+Edit `packages/llm/core/package.json`:
 
 ```json
 "exports": {
@@ -216,19 +216,19 @@ const DEFAULT_MODELS = {
 Run the smoke tests against the new provider:
 
 ```bash
-MYPROVIDER_API_KEY=*** node packages/mcp/gen-ui/scripts/smoke-engine-registry.mjs
+MYPROVIDER_API_KEY=*** node packages/gen-ui/mcp/gen-ui/scripts/smoke-engine-registry.mjs
 ```
 
 Then run real-LLM eval at low intent count:
 
 ```bash
-LLM_PROVIDER=myprovider node packages/mcp/gen-ui/scripts/eval-diff.mjs --semantic
+LLM_PROVIDER=myprovider node packages/gen-ui/mcp/gen-ui/scripts/eval-diff.mjs --semantic
 ```
 
 ## Pitfalls
 
-- **Two proxy shapes — `proxyUrl` is overloaded.** The bridge supports two architecturally different proxies and the dispatcher in `packages/llm/adapters/index.js` chooses between them by URL shape. Get this wrong and you get silent 401s in the browser even though `node packages/llm/server.js` works fine.
-  - **Smart proxy** (`packages/llm/server.js`, route `POST /api/chat`): accepts a **provider-neutral body** `{ provider, model, messages, ... }`, holds the API key server-side, and dispatches internally to the right adapter. Headers are just `content-type: application/json`.
+- **Two proxy shapes — `proxyUrl` is overloaded.** The bridge supports two architecturally different proxies and the dispatcher in `packages/llm/core/adapters/index.js` chooses between them by URL shape. Get this wrong and you get silent 401s in the browser even though `node packages/llm/core/server.js` works fine.
+  - **Smart proxy** (`packages/llm/core/server.js`, route `POST /api/chat`): accepts a **provider-neutral body** `{ provider, model, messages, ... }`, holds the API key server-side, and dispatches internally to the right adapter. Headers are just `content-type: application/json`.
   - **Passthrough proxy** (Vite dev `/api/llm/<provider>/<rest>` → real upstream URL `https://api.<provider>.com/<rest>`): expects the **real upstream body shape** (Anthropic-shaped for `/anthropic/`, OpenAI-shaped for `/openai/`, etc.) plus the **adapter's own auth headers** (`x-api-key` + `anthropic-version`, or `Authorization: Bearer …`). The proxy is dumb — it just rewrites the URL and forwards bytes.
   - Dispatcher: `chat()` and `streamChat()` in `adapters/index.js` call `isPassthroughProxy(proxyUrl)` (regex `/\/api\/llm\/[a-z]+(\/|$)/`). If true, they call `passthroughRequest()` which builds the real upstream body via `adapter.buildRequest()` then swaps in `proxyUrl`. If false, they call `proxyRequest()` with the provider-neutral body.
   - **When adding a new provider**, make sure: (1) `buildRequest()` omits the API key header when `proxyUrl` is the smart proxy (already handled), (2) `buildRequest()` _includes_ the API key header when called from `passthroughRequest()` (also already handled — passthroughRequest forwards adapter headers). The adapter's `buildRequest()` is the single source of truth for upstream-shape body + headers. Don't fork it for proxy mode.
@@ -246,7 +246,7 @@ After any extension:
 npm run check:lockstep         # @adia-ai/llm version must match the others
 npm run smoke:engines          # engines still register; pick still works
 npm run test:a2ui              # 22 pass / 0 fail / 1 skipped
-node packages/llm/server.js    # boots cleanly; .env auto-loads
+node packages/llm/core/server.js    # boots cleanly; .env auto-loads
 ```
 
 If you added a new SSE chunk type to the streaming protocol, verify all 7 consumers (chat-shell, generator.js, synthesis.js, eval-chunk-synthesis, eval-refine-synthesis, playgrounds/chat, apps/genui) still handle it correctly or fall through gracefully.
@@ -256,4 +256,4 @@ If you added a new SSE chunk type to the streaming protocol, verify all 7 consum
 - [code-style.md](code-style.md) — general AdiaUI conventions (this is a specialty path; start there if you need broader context)
 - **a2ui-maintenance** (sibling skill) — generator / MCP / zettel synthesis (consumes the bridge)
 - Spec: `.claude/docs/specs/package-architecture.md` § 11 (Phase 5 — engine registry)
-- README: `packages/llm/README.md` — consumer-facing docs
+- README: `packages/llm/core/README.md` — consumer-facing docs

package/skills/primitive-authoring/references/module-promotion.md

@@ -119,7 +119,7 @@ The "stripped" consumer. Same structural change minus persistence.
 
 ### Phase 4 — Migrate the chunk corpus
 
-The harvested training-corpus chunk (`packages/a2ui/corpus/chunks/<name>.json`) embeds the consumer's HTML as an escaped string. Update it so the LLM sees the new authoring shape.
+The harvested training-corpus chunk (`packages/gen-ui/a2ui/corpus/chunks/<name>.json`) embeds the consumer's HTML as an escaped string. Update it so the LLM sees the new authoring shape.
 
 1. **Preferred** — re-run the harvester:
 
@@ -144,7 +144,7 @@ The harvested training-corpus chunk (`packages/a2ui/corpus/chunks/<name>.json`)
 3. **Defensive grep across all chunks** for the legacy markers:
 
    ```bash
-   grep -l 'id="<old-id>"' packages/a2ui/corpus/chunks/*.json
+   grep -l 'id="<old-id>"' packages/gen-ui/a2ui/corpus/chunks/*.json
    ```
 
 4. **Gotcha — hand-edit + later re-harvest** — if you used the fallback (step 2) AND a peer later adds your consumer's directory to harvester SOURCES, the next `harvest:chunks` run will overwrite your hand-edit with the live consumer HTML. Usually that's _good_ (the re-harvest captures the live state, including any post-edit consumer updates), but diff before assuming. Concrete example: theme-panel's `playground-app-shell.json` was hand-edited, then re-harvested after `playgrounds/` was added to SOURCES — the re-harvest captured the `<aside-ui>` → `<admin-sidebar>` bespoke conversion that the hand-edit missed.

package/skills/primitive-authoring/references/token-contract.md

@@ -114,13 +114,32 @@ Every file under `packages/web-components/styles/` answers two questions — whi
 - Spatial / size / radius / motion / elevation primitives → `styles/foundation/` (one file per dimension)
 - Type scale (L1/L2), roles (L3), native-element defaults → `styles/type/`
 - Color layers → `styles/colors/` (parameters · primitives-* · surfaces · scrims · semantics/*)
-- The global attribute API (`[size]` `[density]` `[gap]` `[padding]` `[margin]` …) → `styles/api/{sizing,text,layout}.css` — the ONLY home for global `[attr]` selectors
+- The global attribute API (`[size]` `[density]` `[gap]` `[padding]` `[margin]` …) → `styles/api/{sizing,text,layout}.css` — the ONLY home for global `[attr]` selectors (governed by the grammar spec below)
 - `tokens.css`, `typography.css`, `colors/semantics.css`, etc. remain **compat barrels** at their public paths — they only `@import`; never add declarations to them
 
 Enforced by `scripts/release/check-foundation-layer-placement.mjs` (wired into `npm run check`): header tags present, primitive files free of attribute selectors, the attribute API confined to `api/`, no orphan files. Import order inside `colors/semantics/` is load-bearing (`aliases.css` last) and asserted in file headers.
 
 Source: ADR-0035.
 
+## The global attribute grammar — read the spec before naming an attribute
+
+The global attribute API is a *designed system* with its own spec:
+`.claude/docs/specs/attribute-api-system.md` (companion audit:
+`.claude/docs/specs/attribute-api-audit.md`). That spec — not this checklist —
+owns the grammar. Two rules an author must know exist (read the spec for the
+mechanics; never work from this summary alone):
+
+- **Explicit vs ambient** (spec §5.2): `[gap]`/`[padding]`/`[margin]` are
+  *explicit* per-element overrides (non-inheriting), while `[size]`/`[density]`
+  are *ambient* context-setters (inheriting by design). Which axis an attribute
+  sits on decides its `@property` registration and how components read it.
+- **No shadowing** (`docs/adr/adr-0053-no-shadowing-global-attributes.md`): a
+  component-local attribute may not share a name with any global attribute —
+  the global name always means the global thing. Before minting any attribute
+  in a component yaml, check it against the spec's attribute inventory; the
+  only sanctioned collisions live in the spec's §11 Global-Attribute Exemption
+  List (first entries: `swatch-ui[color]` / `noodles-ui[color]`, ADR-0054).
+
 ## When to update this reference
 
 If you add a new token category (like `--a-chrome-*` was added), update both this file and `.claude/docs/specs/component-token-contract.md`. The spec doc is the live source of truth; this file is the practitioner's checklist.

package/skills/site-deployment/SKILL.md

@@ -88,9 +88,9 @@ delete-adjudication classes.
 1. Build from clean, fully-merged `main`. In a fresh worktree,
    `npm run build -w @adia-ai/llm` runs **before** `build:site` — llm compiles
    at publish time and its outputs are gitignored, so without it
-   `/packages/llm/index.js` 404s and component registration breaks site-wide
+   `/packages/llm/core/index.js` 404s and component registration breaks site-wide
    (found live 2026-06-09).
-2. Dry-run `rsync -azni --delete --exclude='packages/a2ui/corpus/feedback/'`
+2. Dry-run `rsync -azni --delete --exclude='packages/gen-ui/a2ui/corpus/feedback/'`
    and bucket **every** `*deleting` line into a known-safe class; any
    unexplained served-content delete aborts the deploy. The exclude protects
    prod-only runtime-written files (feedback logs wiped 2026-06-10).

package/skills/site-deployment/references/deploy-playbooks.md

@@ -129,8 +129,8 @@ itself is unavailable.
      ```
      The `llm` package **compiles its JS at publish time** and its outputs are
      **gitignored** — so a fresh worktree (or any tree that hasn't published llm
-     locally) has no `packages/llm/index.js`, `build:site` copies nothing, and
-     **`/packages/llm/index.js` 404s on the deployed site → component registration
+     locally) has no `packages/llm/core/index.js`, `build:site` copies nothing, and
+     **`/packages/llm/core/index.js` 404s on the deployed site → component registration
      breaks on every `/site/components/*` page** (the docs components reference it). Found
      **live 2026-06-09**; the **0-delete dry-run proved it had never been deployed** (the
      file was absent on the server, so there was nothing to delete — not a regression, a
@@ -145,22 +145,22 @@ itself is unavailable.
      deploy gaps). After any package add/rename, check `site.mjs` before deploying.
 2. **Dry-run first, and adjudicate every delete — BEFORE the real rsync, never after:**
    ```sh
-   rsync -azni --delete --exclude='packages/a2ui/corpus/feedback/' \
+   rsync -azni --delete --exclude='packages/gen-ui/a2ui/corpus/feedback/' \
      dist/ <host>.exe.xyz:/srv/<app>/dist/   # -n simulates · -i itemizes
    ```
    - **Exclude server-side runtime-written paths.** Some files exist ONLY on prod —
      written by the running service at runtime, never present in a local build — so
      `--delete` wipes them on every deploy. Known class on ui-kit:
-     `packages/a2ui/corpus/feedback/*.jsonl` (the gen-UI canvas training-feedback log).
+     `packages/gen-ui/a2ui/corpus/feedback/*.jsonl` (the gen-UI canvas training-feedback log).
      Found **live 2026-06-10** (the deploy deleted the day's feedback log; restored from
      the pre-deploy snapshot). Carry the same `--exclude` list on BOTH the dry-run and
      the real rsync; when a new runtime-written path appears, add it here.
    - `*deleting` lines = files removed from prod. Bucket **every one** into a known-safe
      class; **abort if any served-content delete is unexplained.** Safe classes seen on
      ui-kit: gallery review artifacts (`apps/genui/.../review/cycle-*/`), stale
-     `packages/a2ui/retrieval/` + eval reports, **content-hash-rotated** CodeMirror
+     `packages/gen-ui/a2ui/retrieval/` + eval reports, **content-hash-rotated** CodeMirror
      chunks (`code/{chunk,dist}-<hash>.js` — old hash deleted, new hash sent = rotation,
-     not loss), restructured `packages/llm/*.js` dist copies, `node_modules/`
+     not loss), restructured `packages/llm/core/*.js` dist copies, `node_modules/`
      symlink-farm dirs, and refactor-orphaned app files. None are served HTML.
    - **Don't panic at the send count.** A fresh local build never mtime-aligns with the
      remote, so `rsync -a` flags ~every file as a send (`<f..t` = mtime-only touch). Only
@@ -176,7 +176,7 @@ itself is unavailable.
    mutating in place. Restore with `rm -rf dist && mv dist.bak-<date> dist`.
 4. **Deploy** (the dry-run, minus `-n` — SAME excludes):
    ```sh
-   rsync -az --delete --exclude='packages/a2ui/corpus/feedback/' \
+   rsync -az --delete --exclude='packages/gen-ui/a2ui/corpus/feedback/' \
      dist/ <host>.exe.xyz:/srv/<app>/dist/
    ```
 5. **Verify the FILE, not the route.** A SPA returns `200` + the app shell for *any*
@@ -205,7 +205,7 @@ itself is unavailable.
 >
 > **The one exception — `@adia-ai/llm` (2026-06-09):** llm is NOT a source-tree
 > component; it **builds its JS at publish** (gitignored outputs), so `build:site` copies
-> nothing for it in a fresh worktree and `/packages/llm/index.js` 404s → component
+> nothing for it in a fresh worktree and `/packages/llm/core/index.js` 404s → component
 > registration breaks site-wide. Run `npm run build -w @adia-ai/llm` **before** `build:site`
 > (step 1 above). This is exactly why step 5 render-checks a **`/site/components/*`** page,
 > not just a fixture file — the 404 is invisible to file-presence and to the SPA shell.

package/skills/site-docs-authoring/intent.md

@@ -49,7 +49,7 @@ before they start typing.
 
 ## fences
 - NOT for `packages/web-components/components/*/*.examples.html` component demo pages (primitive-authoring)
-- NOT for `site/pages/examples/**`, `site/pages/gen-ui/**`, `packages/a2ui/corpus/exemplars/**` — pure primitive-composition training-harvest surfaces with their own no-style-block rule (`composition-and-examples.md`, a2ui-maintenance)
+- NOT for `site/pages/examples/**`, `site/pages/gen-ui/**`, `packages/gen-ui/a2ui/corpus/exemplars/**` — pure primitive-composition training-harvest surfaces with their own no-style-block rule (`composition-and-examples.md`, a2ui-maintenance)
 - NOT for the A2UI generation pipeline itself, chunk corpus, or MCP tools (a2ui-maintenance)
 
 ## assertions