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

package/skills/package-release/references/cut-procedure.md

@@ -223,7 +223,7 @@ allowlist (never `git add -A`; if peers may have pre-staged files,
 git -C "$REPO" checkout -b "release/vX.Y.Z"
 git -C "$REPO" reset HEAD >/dev/null 2>&1
 git -C "$REPO" add package-lock.json packages/*/package.json packages/*/CHANGELOG.md \
-  packages/a2ui/*/package.json packages/a2ui/*/CHANGELOG.md \
+  packages/gen-ui/a2ui/*/package.json packages/gen-ui/a2ui/*/CHANGELOG.md \
   packages/genui/adia-catalog/base.json packages/genui/adia-catalog/adia-pack.json \
   docs/releases/vX.Y.Z.md   # + in-scope source + Step-3.0 regen outputs
 git -C "$REPO" diff --cached --stat | tail -3   # count must match the allowlist
@@ -276,7 +276,7 @@ The operator's initiating instruction covers the whole cycle — no per-step re-
 
 | Evidence logged before | Content | Why it's still printed |
 | --- | --- | --- |
-| Tagging (Step 6) | The planned tag list (umbrella + 16 per-package) | The log line a recovery diagnoses from |
+| Tagging (Step 6) | The planned tag list (umbrella + 10 per-package) | The log line a recovery diagnoses from |
 | Pushing (Step 8) | The Step 7 F-N1 output + tag list + `origin/main..HEAD` count | F-N1's first real evidence — and its ERROR path still hard-stops unconditionally |
 | Publishing (Step 9) | The current registry snapshot (versions + `dist-tags.latest`) | Ordering is verified against what's LIVE, mechanically |
 | Deploying (Step 10) | The `deploy-site.yml` dispatch (never a raw rsync) | The workflow carries its own GitHub-environment human gate |
@@ -299,7 +299,7 @@ Log the planned tag list (evidence table above), then tag **at `main`'s post-mer
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/tag-lockstep.mjs" \
-  --version X.Y.Z                        # umbrella vX.Y.Z + 16 <pkg>-vX.Y.Z (14 npm + 2 plugins)
+  --version X.Y.Z                        # umbrella vX.Y.Z + 10 <pkg>-vX.Y.Z (8 npm + 2 plugins)
 ```
 
 ## §Step 7 — F-N1 release trip-wire
@@ -395,98 +395,13 @@ Any Step-2 stashes: `git stash pop`; flag conflicts to the operator.
 
 Always author notes at end-of-cycle without being asked — context is freshest now. Single version → [`notes-authoring.md`](notes-authoring.md); ≥2 versions since the last broadcast → its §Rollup section. Surface the draft inline for copy-paste; the operator owns posting. Skip only on an explicit "no notes".
 
-## §The 0.8.37 estate-split cut (ADR-0048 P7 — ONE cut, then delete this section)
-
-Extra steps for the single cut that ships the a2ui/gen-ui split. They ride the
-normal procedure above; nothing here replaces a step.
-
-**It is a PATCH cut, by operator ruling (2026-08-13, gh#1192)** — `0.8.37`, not
-the `0.9.0` MINOR the ADR originally proposed. Two consequences to hold in mind
-before Step 4:
-
-- **Invariant 2 (PATCH asymmetry) applies UNCHANGED — no exception.** Internal
-  `@adia-ai/*` dep ranges stay `^0.8.0` on a patch cut, and that is exactly
-  right here: `targetCaret("0.8.37")` is `^0.8.0`, the three new names
-  (`a2ui`, `gen-ui`, `mcp` — retargeted gh#1240, 2026-08-14: this row named
-  `gen-ui-mcp` before the MCP-distribution fold; that name never published,
-  `mcp` is its real successor) publish `0.8.37` as their FIRST version, and
-  `^0.8.0` resolves to it. The shims' deps on their successors are already
-  `^0.8.0` and need no edit; web-modules' EXACT peer pin moves to `0.8.37` by
-  the normal peer rule (gh#489), which `bump.mjs` does. So nothing in the split
-  needs a hand-written range — if `check:lockstep` asks for one, something else
-  is wrong; do not hand-pin.
-- **A patch-shaped number does NOT relax the MIGRATION GUIDE obligation**
-  (invariant 7). Six published names are being replaced; the guide is owed
-  regardless of what the version looks like. This is the one failure mode the
-  small number invites.
-
-**In the release commit (Step 4/5), not before and not after:**
-
-1. **Flip the factory `.mcp.json` pin NAME** — `@adia-ai/a2ui-mcp` →
-   `@adia-ai/mcp` (retargeted gh#1240, 2026-08-14: this step named
-   `@adia-ai/gen-ui-mcp` before the MCP-distribution fold folded that planned
-   name — and `@adia-ai/a2ui-protocol-mcp` — into `@adia-ai/mcp` before either
-   ever published; the flip target moved, the flip's own timing did not), in
-   `packages/plugins/adia-ui-factory/.mcp.json` AND its README prose echo
-   (invariant 8 covers both files; `bump.mjs` moves the VERSION on either
-   name, so only the name is hand-edited). The pinned args also grow a
-   subcommand: `["-y", "@adia-ai/mcp@0.8.37", "gen-ui"]` — the fold's bin
-   dispatches `adia-mcp gen-ui`/`adia-mcp protocol`, not a bare invocation.
-   **Why here and not at P5:** invariant 8 forces the pin to the CURRENT
-   lockstep version. Before this cut that is `0.8.36`, and `@adia-ai/mcp`
-   has no `0.8.36` on npm — flipping early pins every local-marketplace install
-   to `npx -y @adia-ai/mcp@0.8.36`, i.e. a registry 404. In this commit
-   the version becomes `0.8.37`, which this cut publishes. (The reasoning is
-   unchanged by the 0.9.0 → 0.8.37 ruling, and unchanged again by the
-   gen-ui-mcp → mcp retarget; only the numbers and the name moved.)
-   `check:lockstep` accepts any name this pin has carried (`MCP_PIN_RE`), so
-   the flip is gate-clean regardless of which name is live when this runs.
-
-   **Config-KEY standardization rides the same flip (operator ruling
-   2026-08-14):** the `mcpServers` key names move with the pin so a tool
-   call's prefix always names which server answered. Factory `.mcp.json`:
-   key `a2ui` → `adia-gen-ui`. Repo root `.mcp.json`: key `adia-ui` →
-   `adia-gen-ui`. New entries added later use `adia-protocol` /
-   `adia-factory` for the other subcommands. Key renames change consumers'
-   tool prefixes (`mcp__a2ui__*` → `mcp__adia-gen-ui__*`) — that is the
-   point, and it ships in the same breaking-named cut as everything else.
-
-**After Step 9 (publish), once `npm view <old-name> version` shows the shim on
-the registry — never before:**
-
-2. **Deprecate the six retired names.** The list is projected from the shim
-   generator's SPEC, so it cannot drift from what actually shipped:
-
-   ```bash
-   node scripts/build/generate-shims.mjs --deprecate-commands
-   ```
-
-   It prints the `npm deprecate` lines plus an `npm info <pkg> deprecated`
-   verify line per package. Print-only by design — read them, then run them.
-   **Verify by reading the field back**; a zero exit code is not proof.
-   Deprecating before the shim publishes leaves consumers at a dead end (the
-   pointer text names a package version that isn't there yet).
-
-3. **Verify a shim tarball's CONTENTS, not just the publish exit code** — e.g.
-   `npm pack @adia-ai/a2ui-runtime@0.8.37 && tar -tzf *.tgz`, then import one
-   subpath from a scratch dir and confirm it resolves through to
-   `@adia-ai/a2ui`.
-
-**Follow-up PR (not this cut):** delete `packages/shims/`, the roster rows
-marked `shim: true`, their six `publish-a2ui-*.yml` workflows,
-`resolvePackageDir`'s `shims/` fallback, `scripts/build/generate-shims.mjs`,
-`scripts/verify/check-shim-bridges.mjs`, the `check:shims` gate, and this
-section. Then narrow `MCP_PIN_RE` + `bump.mjs`'s pin pattern back to the single
-new name.
-
----
-
 ## §The 0.8.38 cut (the clean-world cut — delete this section after it lands)
 
 The first cut AFTER the estate-split bridge. Pre-conditions, all verifiable
 before Step 1:
 
-1. **The shim-deletion follow-up PR has MERGED** (the §0.8.37 follow-up above:
+1. **The shim-deletion follow-up PR has MERGED** (the §0.8.37 follow-up — that
+   section deleted itself with the same PR, as designed:
    `packages/shims/` gone, roster shim rows gone, the six `publish-a2ui-*.yml`
    workflows gone, `check:shims`/`check-shim-bridges` retired). The roster file
    is the member count — never transcribe it.

package/skills/package-release/references/gates-catalog.md

@@ -14,7 +14,7 @@ Row layout per gate: **What** · **Typical failure** · **Recovery**.
 
 ### `npm run check:lockstep`
 
-- **What:** all 16 lockstep `@adia-ai/*` packages declare the same `version` (the class-B `adia-plugins` package is excluded — `lockstep: false`, `scripts/package-paths.mjs`); internal `@adia-ai/*` dep ranges match policy (`^X.Y.0` during PATCH cycles, bumped at MINOR).
+- **What:** all 10 lockstep `@adia-ai/*` packages declare the same `version` (the class-B `adia-plugins` package is excluded — `lockstep: false`, `scripts/package-paths.mjs`); internal `@adia-ai/*` dep ranges match policy (`^X.Y.0` during PATCH cycles, bumped at MINOR).
 - **Typical failure:** one package forgot to bump; a peer edited an internal range mid-PATCH; a `^0.0.x` range slipped in.
 - **Recovery:** version drift → `` `${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/bump.mjs` ``; range drift → `npm run check:lockstep:fix` auto-aligns, then re-run.
 - **Why `^0.0.x` is forbidden:** npm pre-1.0 semver only widens the caret when major+minor aren't both zero — `^0.0.6` resolves to `>=0.0.6 <0.0.7`, locked to exactly 0.0.6. An internal dep pinned that way silently installs a *stale* sibling on every fresh `npm i` (this shipped a real ~4-day-latent bug before the lockstep policy). The `^X.Y.0` floor (Y≥1) widens correctly across patches; trust the gate, don't reason about caret semantics by hand. Moot at 1.0.0.
@@ -96,8 +96,8 @@ Also: `check:no-self-import-css` (no transitively self-importing barrel) · `che
 
 ### `npm run check:browser-safe`
 
-- **What:** no top-level `import 'node:*'` in browser-reachable modules (`packages/a2ui/{compose,retrieval,validator}`, `web-components/`, `web-modules/`, `apps/*/app/*.contents.js`).
-- **Recovery:** dual-mode pattern (`IS_NODE` + dynamic `await import(/* @vite-ignore */ 'node:*')` + `import.meta.glob` browser branch); canonical impl: `packages/a2ui/retrieval/component-catalog.js`.
+- **What:** no top-level `import 'node:*'` in browser-reachable modules (`packages/gen-ui/a2ui/{compose,retrieval,validator}`, `web-components/`, `web-modules/`, `apps/*/app/*.contents.js`).
+- **Recovery:** dual-mode pattern (`IS_NODE` + dynamic `await import(/* @vite-ignore */ 'node:*')` + `import.meta.glob` browser branch); canonical impl: `packages/gen-ui/a2ui/retrieval/component-catalog.js`.
 
 Siblings: `check:absolute-imports` (no leading-`/` imports — rewrite relative) · `check:template-interp` (template `${expr}` contract) · `check:yaml-events` (yaml `events:` match runtime `dispatchEvent` calls) · `check:yaml-impl-coverage` (every yaml prop implemented in the JS class).
 
@@ -121,7 +121,7 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 
 ### `npm run verify:corpus`
 
-- **What:** every chunk in `packages/a2ui/corpus/chunks/*.json` is reachable and well-formed.
+- **What:** every chunk in `packages/gen-ui/a2ui/corpus/chunks/*.json` is reachable and well-formed.
 - **Recovery:** corpus remediation routes to the A2UI-pipeline skill, not this one.
 
 ### `npm run check:chunks-fresh`

package/skills/package-release/references/independent-package-release.md

@@ -19,7 +19,7 @@
 | | Class A — lockstep cut | Class B — independent package |
 | --- | --- | --- |
 | Versioning | whole set bumps together | own version line per package |
-| Lockstep gate | enforced (`check:lockstep` 16/16) | **excluded** — a class-B package is not listed in `check-lockstep.mjs`'s `PACKAGES` (`adia-plugins`, the current member, is filtered out via `lockstep: false` — `scripts/package-paths.mjs`) |
+| Lockstep gate | enforced (`check:lockstep` 10/10) | **excluded** — a class-B package is not listed in `check-lockstep.mjs`'s `PACKAGES` (`adia-plugins`, the current member, is filtered out via `lockstep: false` — `scripts/package-paths.mjs`) |
 | Umbrella tag | `vX.Y.Z` + per-package | **none** — per-package tags only (versions differ) |
 | `dist-tag` ordering | cross-package publish order matters | N/A |
 | Demo-site deploy | yes | **none** |
@@ -47,7 +47,7 @@ Substrate fixes (release scripts / lockfile / CHANGELOG), landed once as a norma
 
 ## §Verify target
 
-The published package(s) on the **npm registry** at their independent versions, plus the npm-published `@adia-ai/adia-plugins` manifest referencing the new versions (ADR-0045). NOT "all 16 lockstep packages + the demo site" — that's class A.
+The published package(s) on the **npm registry** at their independent versions, plus the npm-published `@adia-ai/adia-plugins` manifest referencing the new versions (ADR-0045). NOT "all 10 lockstep packages + the demo site" — that's class A.
 
 ## §Gotchas (from the first independent cut, factory v0.2.2 + forge v0.1.2)
 

package/skills/package-release/references/recovery-paths.md

@@ -17,7 +17,7 @@
 
 1. Verify the skip: `npm view <pkg> versions --json | tail` (no X+1 on npm) + `git tag --list 'vX.Y.*'` (no tags). Run pre-flight at the peer's commit to confirm it's shippable.
 2. Correct the version via a **new commit on top** (not amend — the peer's commit stays for history).
-3. Sweep every occurrence of the wrong version: 16 × package.json, 16 × CHANGELOG (headers + body refs — the lockstep roster, `scripts/package-paths.mjs`), any doc/CSS-comment refs, then regenerate the lockfile. Preserve filename references that intentionally encode the original label.
+3. Sweep every occurrence of the wrong version: 10 × package.json, 10 × CHANGELOG (headers + body refs — the lockstep roster, `scripts/package-paths.mjs`), any doc/CSS-comment refs, then regenerate the lockfile. Preserve filename references that intentionally encode the original label.
 4. Commit as `fix(release): correct vX.Y.Z+1 version-skip → vX.Y.Z` documenting the discovery, then resume [`cut-procedure.md`](cut-procedure.md) at Step 5.
 
 ## §Scenario 2 — Batch push
@@ -63,7 +63,7 @@
 
 ## §Scenario 7 — Tags pushed, ZERO publish workflows fired
 
-**Shape:** all 17 tags exist on origin (umbrella + one per lockstep-roster package — `scripts/package-paths.mjs`), but no `publish-<pkg>.yml` run exists for them; npm latest unchanged; nothing errored.
+**Shape:** all 11 tags exist on origin (umbrella + one per lockstep-roster package — `scripts/package-paths.mjs`), but no `publish-<pkg>.yml` run exists for them; npm latest unchanged; nothing errored.
 
 **Root cause:** pushing many tags in **one** `git push` fires a single batched create event that GitHub Actions routinely drops. Re-pushing is a no-op (the tags already exist remotely).
 

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

@@ -41,36 +41,34 @@ const SIBLING_MANIFESTS = Object.fromEntries(
 
 // Cross-package EXACT pins bumped in the same pass — a different shape from a
 // package.json "version" field, so SIBLING_MANIFESTS' regex can't reach them.
-// The factory plugin's .mcp.json pins @adia-ai/a2ui-mcp to the exact lockstep
+// The factory plugin's .mcp.json pins @adia-ai/mcp to the exact lockstep
 // version (SKILL invariant 8 — the consumer never floats). bump.mjs left this
 // untouched through the 0.8.6 + 0.8.7 cuts, forcing a manual edit + amend each
 // time; check-lockstep's mcp-pin guard now catches a drift, this moves it.
 //
 // Each package maps to an ARRAY of pin configs — the factory README's own
-// prose echo of the same pin (`server pinned: @adia-ai/a2ui-mcp@X`) is a
+// prose echo of the same pin (`server pinned: @adia-ai/mcp@X`) is a
 // SECOND file invariant 8 covers, and check:plugin-count-claims' "factory
-// README a2ui-mcp pin" EQUALITY check enforces the two agree. Left out of
-// this array through the 0.8.35 + 0.8.36 cuts, it needed the same manual
+// README generation-MCP pin" EQUALITY check enforces the two agree. Left out
+// of this array through the 0.8.35 + 0.8.36 cuts, it needed the same manual
 // hand-commit .mcp.json used to (gh#1198) — same file set, invariant 8's own
 // scope, so it moves alongside .mcp.json rather than getting its own key.
 //
-// ANY NAME THIS PIN HAS CARRIED (ADR-0048 P5, retargeted gh#1240 2026-08-14):
-// the generation MCP is `@adia-ai/mcp` (its `gen-ui` surface) since the
-// MCP-distribution fold — P2 had planned `@adia-ai/gen-ui-mcp`, which never
-// published — but the pin keeps naming the old package until the P7 cut
-// flips it in the release commit itself (see lockstep-checks.mjs MCP_PIN_RE
-// for why an early flip pins consumers to a 404). Matching every name means
-// the version bump works before AND after either flip, with no cut-day edit
-// to this file.
+// `@adia-ai/mcp` is the single live name since the 0.8.37 estate-split cut
+// flipped the pin in its release commit (ADR-0048 P7). The bridge-window
+// alternation over the retired names (`a2ui-mcp`, the never-published
+// `gen-ui-mcp`) was narrowed back by the shim-deletion follow-up PR, matching
+// lockstep-checks.mjs's MCP_PIN_RE — a retired name in the pin must now fail
+// loudly instead of being bumped along.
 const A2UI_MCP_PIN = {
-  label: 'generation-MCP pin (@adia-ai/{a2ui-mcp,gen-ui-mcp,mcp})',
-  // `@adia-ai/{a2ui-mcp,gen-ui-mcp,mcp}@<from>` (not a prefix of a longer version) → `@<to>`
+  label: 'generation-MCP pin (@adia-ai/mcp)',
+  // `@adia-ai/mcp@<from>` (not a prefix of a longer version) → `@<to>`
   // Escape EVERY regex metacharacter in `from`, not just dots: a prerelease or
   // build-metadata version (`0.9.0-rc+1`) would otherwise inject `+` as a
   // quantifier and silently match the wrong text. Same class as the truncating
   // MCP_PIN_RE suffix CodeRabbit found on PR #1229.
   pattern: (from) =>
-    new RegExp(`(@adia-ai/(?:(?:a2ui|gen-ui)-mcp|mcp)@)${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\d.])`),
+    new RegExp(`(@adia-ai/mcp@)${from.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\d.])`),
   replace: (to) => `$1${to}`,
 };
 const PINNED_REFS = {
@@ -298,38 +296,43 @@ function selftest() {
     console.error('selftest FAIL: corrupted package.json (no version match) not caught'); process.exit(1);
   }
 
-  // PINNED_REFS — the .mcp.json a2ui-mcp pin (invariant 8) moves in lockstep.
+  // PINNED_REFS — the .mcp.json @adia-ai/mcp pin (invariant 8) moves in lockstep.
   const [pinCfg, readmePinCfg] = PINNED_REFS['packages/plugins/adia-ui-factory'];
-  const pinBefore = '{"args":["-y","@adia-ai/a2ui-mcp@0.8.6"]}';
+  const pinBefore = '{"args":["-y","@adia-ai/mcp@0.8.6","gen-ui"]}';
   const pinAfter = bumpPinnedRef(pinBefore, pinCfg, '0.8.6', '0.8.7');
-  if (!pinAfter.includes('@adia-ai/a2ui-mcp@0.8.7') || pinAfter.includes('@0.8.6')) {
-    console.error('selftest FAIL: PINNED_REFS did not bump the .mcp.json a2ui-mcp pin'); process.exit(1);
+  if (!pinAfter.includes('@adia-ai/mcp@0.8.7') || pinAfter.includes('@0.8.6')) {
+    console.error('selftest FAIL: PINNED_REFS did not bump the .mcp.json generation-MCP pin'); process.exit(1);
   }
   // Must NOT prefix-match a longer version (0.8.6 inside 0.8.60).
-  if (bumpPinnedRef('@adia-ai/a2ui-mcp@0.8.60', pinCfg, '0.8.6', '0.8.7') !== '@adia-ai/a2ui-mcp@0.8.60') {
+  if (bumpPinnedRef('@adia-ai/mcp@0.8.60', pinCfg, '0.8.6', '0.8.7') !== '@adia-ai/mcp@0.8.60') {
     console.error('selftest FAIL: PINNED_REFS pattern prefix-matched a longer version'); process.exit(1);
   }
+  // A retired bridge name must NOT be bumped along — it should fail the later
+  // check-lockstep gate loudly, not be silently kept alive by this pass.
+  if (bumpPinnedRef('@adia-ai/a2ui-mcp@0.8.6', pinCfg, '0.8.6', '0.8.7') !== '@adia-ai/a2ui-mcp@0.8.6') {
+    console.error('selftest FAIL: pin pattern matched a retired generation-MCP name'); process.exit(1);
+  }
 
   // gh#1198 — the factory README's OWN prose echo of the same pin
-  // (`server pinned: @adia-ai/a2ui-mcp@X`) must move alongside .mcp.json;
-  // check:plugin-count-claims' "factory README a2ui-mcp pin" EQUALITY check
-  // is what caught this drift on the v0.8.35 + v0.8.36 cuts.
+  // (`server pinned: @adia-ai/mcp@X`) must move alongside .mcp.json;
+  // check:plugin-count-claims' "factory README generation-MCP pin" EQUALITY
+  // check is what caught this drift on the v0.8.35 + v0.8.36 cuts.
   if (readmePinCfg.file !== 'README.md') {
     console.error('selftest FAIL: expected the second factory pin config to target README.md'); process.exit(1);
   }
-  const readmeBefore = '`a2ui` server pinned: `@adia-ai/a2ui-mcp@0.8.6` (tool SoT: `packages/mcp/TOOLS.md`)';
+  const readmeBefore = '`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.6` (tool SoT: `packages/gen-ui/mcp/TOOLS.md`)';
   const readmeAfter = bumpPinnedRef(readmeBefore, readmePinCfg, '0.8.6', '0.8.7');
-  if (!readmeAfter.includes('@adia-ai/a2ui-mcp@0.8.7') || readmeAfter.includes('@0.8.6')) {
-    console.error('selftest FAIL: PINNED_REFS did not bump the README a2ui-mcp prose pin'); process.exit(1);
+  if (!readmeAfter.includes('@adia-ai/mcp@0.8.7') || readmeAfter.includes('@0.8.6')) {
+    console.error('selftest FAIL: PINNED_REFS did not bump the README generation-MCP prose pin'); process.exit(1);
   }
-  if (bumpPinnedRef('@adia-ai/a2ui-mcp@0.8.60', readmePinCfg, '0.8.6', '0.8.7') !== '@adia-ai/a2ui-mcp@0.8.60') {
+  if (bumpPinnedRef('@adia-ai/mcp@0.8.60', readmePinCfg, '0.8.6', '0.8.7') !== '@adia-ai/mcp@0.8.60') {
     console.error('selftest FAIL: README pin pattern prefix-matched a longer version'); process.exit(1);
   }
 
   // web-modules exact peer pins (gh#489) — all three move in one pass; a
   // longer version must not prefix-match.
   const [peerCfg] = PINNED_REFS['packages/web-modules'];
-  const peersBefore = '{"peerDependencies":{"@adia-ai/web-components": "0.8.22","@adia-ai/a2ui-runtime": "0.8.22","@adia-ai/llm": "0.8.22"}}';
+  const peersBefore = '{"peerDependencies":{"@adia-ai/web-components": "0.8.22","@adia-ai/a2ui": "0.8.22","@adia-ai/llm": "0.8.22"}}';
   const peersAfter = bumpPinnedRef(peersBefore, peerCfg, '0.8.22', '0.8.23');
   if ((peersAfter.match(/0\.8\.23/g) || []).length !== 3 || peersAfter.includes('0.8.22')) {
     console.error('selftest FAIL: web-modules peer pins did not all move'); process.exit(1);

package/skills/package-release/scripts/insert-stub.mjs

@@ -144,7 +144,7 @@ function main() {
 function selftest() {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'insert-stub-selftest-'));
   try {
-    const dir = path.join(tmp, 'packages', 'llm');
+    const dir = path.join(tmp, 'packages', 'llm', 'core');
     fs.mkdirSync(dir, { recursive: true });
     const clPath = path.join(dir, 'CHANGELOG.md');
     const anchor = '## [0.1.0] — 2026-01-01';

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/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