@adia-ai/adia-ui-forge 0.8.55 → 0.8.56

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.55",
+  "version": "0.8.56",
   "description": "Maintain the adia-ui (@adia-ai) framework itself \u2014 author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-ui-kit-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.55",
+  "version": "0.8.56",
   "description": "Maintain the adia-ui (@adia-ai) framework itself — author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-ui-kit-factory (the consumer/app-author plugin).",
   "author": {
     "name": "Kim",

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.56] — 2026-08-31
+
+### Added
+- **New `component-md-authoring` skill (gh#2615).** Authors the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — typed directly into the yaml's new `screenReader:`/`behavioral:` fields (component.md itself is a generated shell, never hand-edited). Sits next to `primitive-authoring` in `packages/plugins/adia-ui-forge/skills/`; Codex (`agents/openai.yaml`) and Hermes/Pi (`__init__.py`) manifests regenerated to register it.
+- **`primitive-authoring`'s `yaml-contract.md` gains a semantic-id grammar for `examples[].a2ui` component ids (gh#2492 Phase 1).** The `.claude/docs/specs/a2ui-editor.md:170` "free-form" id convention was written for editor-generated ids only, not authored yaml examples — reading it as license for both produced a corpus-wide drift toward cryptic, positional ids (`q`, `k1`, `k1v`) reported against `blockquote.yaml`, `badge.yaml`, `aside.yaml`, `alert.yaml`, and `anchor-bar.yaml`. New `## examples: field` section documents the grammar (kebab-case, role-descriptive, unique per example, a short-real-word root/wrapper exception) with before/after examples; `a2ui-editor.md:170` amended to scope its own claim to editor-generated ids and cross-reference the new grammar. Phase 2 (a separate dispatch) sweeps the corpus to match.
+- **Phase 2 (gh#2492): the corpus-wide sweep landed and `check-example-ids.mjs` flips from advisory to `npm run check:example-ids:strict` in the `npm run check` chain.** 526 violations across 48 yamls (`packages/web-components`, `packages/web-modules`) renamed to the Phase 1 grammar — see `packages/web-components/CHANGELOG.md` and `packages/web-modules/CHANGELOG.md` for the file list. `yaml-contract.md`'s `## examples: field` section updated to describe the gate as enforced, plus a noted known gap (the checker's positional regex doesn't catch a `letter-digit-letter-digit` chain like `g1i1`, out of scope for this sweep since nothing flagged it). `check-example-ids.mjs` itself gained an entrypoint guard (`if (import.meta.url === ...)`) — the CLI's `main()` was running as a side effect of importing `checkExampleIds` as a library function, which the sweep tooling does.
+
+### Fixed
+- **`package-release`'s Step 5 staging allowlist was missing the factory README's own prose echo of the generation-MCP pin — bump.mjs's `A2UI_MCP_PIN` rewrites both `adia-ui-factory/.mcp.json` and its README, but Step 5 only ever staged `.mcp.json`, so the README edit rode uncommitted through every cut (gh#2473).** `release-pack.mjs`'s Step 5 now also stages `packages/plugins/adia-ui-factory/README.md`. Added a new Step 5.6 unstaged-tracked-files guard right after staging (numbered 5.6, not 5.5 — `cut-procedure.md`'s own §Step 5.5 already names a different, pre-existing manual freshness trip-wire): it fails the cut loudly if any tracked file bump.mjs or a cut-hygiene step touched is still modified-in-the-worktree after Step 5's allowlist ran, so the next allowlist gap is caught at cut time instead of discovered by hand later. `selftest` extended with a direct unit test of the new `unstagedTrackedLeftovers()` parser (plain modifies/deletes, staged-only and untracked exclusions, C-quoted paths, rename/copy new-side reporting) plus a marker asserting the guard's `--dry` code path runs.
+
+### Changed
+- **`package-release`: gate 4 retries once on host-contention timeout (Mode A, gh#2195, #2362)**; `cut-procedure.md` fails fast on a pnpm-shaped `node_modules` in Step 1 and adds Step 12 (restore the pnpm dev layout after a cut) (#2197, #2202); `gates-catalog.md` follows.
+- **`a2ui-maintenance` references follow the A2UI runtime.** `data-model-reactivity.md`, `surface-lifecycle.md`, and `pipeline-overview.md` describe the vendored v1 data model after ADR-0078 P3/P4 (walker retirement, #2271), the `v0_9`→`v1_0` dialect rename (gh#2212, #2241), and the five opt-out-scoped catalogs (gh#2211, #2233, #2216).
+- **`primitive-authoring` references absorb the ADR-drift harvest (#2441) and ADR-0063 wave 2 (#2443)**: `anti-patterns.md`, `api-contract.md`, `authoring-cycle.md`, `code-style.md`, `form-control-sizing.md`, `token-contract.md`, and `yaml-contract.md` now state the ratified spellings (`no-*` negation prefix, `closable`, `outlined`, `status=completed`) and the amended ADR-0047/0056/0059/0061 rulings inline.
+- **`HARNESS-NOTES.md`** pointer for non-Claude harnesses (gh#2449).
+
+### Fixed
+- **`generate-release-notes.mjs` (gh#2474): two bugs found and hand-fixed live during the v0.8.56 cut, now fixed at the source.** (1) When a CHANGELOG `[X.Y.Z]` section carries two same-named `### Changed`/`### Fixed` blocks (one at cut time, another added by a later hand-fix), the generator now merges them into one heading in first-occurrence order before demoting to `####` — the duplicate `####` heading that tripped CodeRabbit's MD024 (db13eaebb) can't recur. (2) The Slack post's per-package headline now prefers a bullet starting with `- **BREAKING` over document order, falling back to the first bullet only when none is BREAKING (b378b5fd9). Added `mergeDuplicateHeadings()`, unit coverage in `scripts/release/generate-release-notes.test.js`, and `selftest` regression cases for both. `scripts/release/generate-release-notes.mjs`.
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`.codex-plugin/` touched in this release window** (1 file(s), e.g. `.codex-plugin/plugin.json`) — carried by the entries above.
+- **`skills/` touched in this release window** (14 file(s), e.g. `a2ui-maintenance/SKILL.md`) — carried by the entries above.
+
 ## [0.8.55] — 2026-08-28
 
 ### Changed

package/__init__.py

@@ -11,6 +11,11 @@ def register(ctx):
         path=Path(os.path.join(_HERE, "skills", "a2ui-maintenance", "SKILL.md")),
         description="Maintains the A2UI pipeline (packages/gen-ui/a2ui/): the chunk corpus, compose strategies (zettel, chunk-zettel, free-form, monolithic), retrieval, validator, calibration, evals, the a2ui MCP server. Use to author/harvest/fix chunks, tune STRONG_MATCH or zettel thresholds, validate an A2UI document, diagnose an eval gap/regression or lift a semantic fail, change MCP tools (generate_ui, compose_from_chunks, check_anti_patterns, refine_composition), scan anti-patterns, run pipeline ops, or when a contract can't express a shape. NOT for app screens (screen-composition), runtime gen-UI features (gen-ui-wiring), primitive authoring (primitive-authoring), or gallery scoring (gen-ui-review).",
     )
+    ctx.register_skill(
+        name="component-md-authoring",
+        path=Path(os.path.join(_HERE, "skills", "component-md-authoring", "SKILL.md")),
+        description="Author the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — and keep it PR-fresh. Use when a component's states, composed children, aria behavior, or error/empty/ loading handling changes and it already has (or should grow) a `component.md`, or when asked to \"add component.md for X\" / \"write the screen-reader spec for X\" / \"why did check:component-md-fresh fail\". NOT the yaml prop/slot/event/token contract itself (primitive-authoring owns that — this skill only owns the two authored yaml fields, `screenReader`/`behavioral`, plus the optional `intent` field); NOT gen-ui corpus/retrieval wiring (a2ui-maintenance); NOT a component's CSS token audit (component-token-audit).",
+    )
     ctx.register_skill(
         name="cross-harness-authoring-standards",
         path=Path(os.path.join(_HERE, "skills", "cross-harness-authoring-standards", "SKILL.md")),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.55",
+  "version": "0.8.56",
   "description": "Maintain the adia-ui (@adia-ai) framework itself — author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",

package/plugin.yaml

@@ -1,4 +1,4 @@
 name: "adia-ui-kit-forge"
-version: "0.8.55"
+version: "0.8.56"
 description: "Maintain the adia-ui (@adia-ai) framework itself — author primitives and shells, run the A2UI generation pipeline and its corpus, review gen-UI quality, sweep QA, cut releases, deploy. The maintainer counterpart to adia-ui-kit-factory (the consumer/app-author plugin)."
 manifest_version: 1

package/skills/a2ui-maintenance/SKILL.md

@@ -47,7 +47,7 @@ Unmatched work defaults to pipeline-overview and re-classifies from there.
 | Tune the anti-pattern catalogue | [anti-patterns](references/anti-patterns.md) |
 | A contract can't express a content shape — decide how to extend it | [format-extension-decisions](references/format-extension-decisions.md) |
 | Surface regeneration, pending/stale rendering, the `doc`-setter bracket | [surface-lifecycle](references/surface-lifecycle.md) (ADR-0061) |
-| Data-model internals — `Cell`/`Derived`, RFC-6901 pointers, `path-pointer.js` call-site migration, watch semantics | [data-model-reactivity](references/data-model-reactivity.md) (ADR-0078) |
+| Data-model internals — `Cell`/`Derived`, RFC-6901 pointers, watch semantics (shipped) | [data-model-reactivity](references/data-model-reactivity.md) (ADR-0078) |
 
 ## Contracts that gate every change
 

package/skills/a2ui-maintenance/references/data-model-reactivity.md

@@ -1,14 +1,16 @@
 # v1 data-model reactivity — Cell/Derived, RFC-6901 pointers, value-identity cutoff
 
 Source of truth: [ADR-0078](../../../../../../docs/ops/adr/adr-0078-a2ui-runtime-adopts-v1-data-model.md)
-(ratified 2026-08-20, gh#1762; phased plan tracked in gh#1784). Read the ADR
-before touching `packages/gen-ui/a2ui`'s data-model internals, `path-pointer.js`
-call sites, or `surface.js`/`renderer.js` watch semantics — this file is the
-routing pointer + the shape of the adopted contract, not a restatement of the
-ruling, and NOT a claim that any phase has shipped (check gh#1784's own state
-before citing this as already-live behavior).
+(ratified 2026-08-20, gh#1762; phased plan tracked in gh#1784, **closed
+2026-08-28 — all four phases P1-P4 shipped**). Read the ADR before touching
+`packages/gen-ui/a2ui`'s data-model internals or `surface.js`/`renderer.js`
+watch semantics — this file is the routing pointer + the shape of the
+adopted contract, not a restatement of the ruling. `path-pointer.js` (the
+transitional three-walker shim gh#1763 staged) is deleted as of P4; every
+call site now uses the vendored `resolvePointer`/`setPointer`/`deletePointer`/
+`createDataModel` primitives directly.
 
-## What's decided (direction, not yet fully built)
+## What's decided (shipped — ADR-0078 P1-P4 complete, gh#1784 closed)
 
 The in-repo A2UI runtime (`packages/gen-ui/a2ui`, the 0.9 dialect) **adopts**
 the vendored `packages/genui` v1.0 data model internally — `Cell`/`Derived`
@@ -19,8 +21,11 @@ data model. This is an internal implementation swap, not a consumer
 migration or a wire-grammar change: the dialect's eight message kinds, the
 `{path}` binding-prop shape, `updateDataModel`, `HandlerContext.updateModel/
 setModel`, `registerController/Handler/Resolver`, and the `<a2ui-root>`
-element API are all unchanged (ADR-0078 Decision item 2 — falsified if any
-consumer needs a code change, or if `dialect-schema.source.mjs` diffs).
+element API are all unchanged. **[amended 2026-08-28, gh#2268/lld-0005,
+gh#2212]** Decision item 2's falsifier is narrowed to wire-GRAMMAR diffs
+only: it is falsified if any consumer needs a code change, or if
+`dialect-schema.source.mjs`'s wire grammar diffs — a bare `$id`/filename
+identifier rename in `dialect-schema.source.mjs` no longer falsifies it.
 Phased across future cuts, plan/LLD to follow — nothing rides in the cut
 this ADR itself was ratified for (item 6).
 
@@ -49,19 +54,25 @@ this ADR itself was ratified for (item 6).
   same identity-cutoff rule as R-R10). This supersedes `surface.js`'s
   prefix-descend rule and `renderer.js`'s re-apply-all-bindings behavior.
 
-## What's converging, and what it changes
+## What converged (P1-P4, complete)
 
-`path-pointer.js` (gh#1763) currently preserves three divergent legacy
-walkers (`getByPath`/`setByPath`, `getPath`/`setPath`, `getModelValue`) on
-purpose, as a staging step — each call site migrates to the vendored
-semantics above and retires when its last call site migrates. Every
-migration phase must name its own behavior deltas rather than changing
-silently (ADR-0078 item 4 is falsified by an unnamed semantics change) —
-known deltas already called out: `/a//b/` stops resolving forgivingly,
-`/name/length` on a string stops leaking the primitive's own property,
-and a2ui's own read/write asymmetry (today: `getByPath`/`getPath` treat
-absent-path/`""`/`"/"` alike, but `setByPath`/`setPath` no-op on root
-instead of replacing it) converges on the read/write split named above.
+`path-pointer.js` (gh#1763) preserved three divergent legacy walkers
+(`getByPath`/`setByPath`, `getPath`/`setPath`, `getModelValue`) as a
+deliberate staging step; each call site migrated to the vendored semantics
+above in turn (P2: `renderer.js`; P3: `surface.js`/`wiring-registry.js`),
+and P4 deleted the module once its last call site migrated — no divergent
+walker survives (Decision 4). Every migration phase named its own behavior
+deltas rather than changing silently (ADR-0078 item 4's falsifier): `/a//b/`
+stopped resolving forgivingly, `/name/length` on a string stopped leaking
+the primitive's own property, `~0`/`~1` escaping is now honored, and a2ui's
+own read/write asymmetry (previously: `getByPath`/`getPath` treated
+absent-path/`""`/`"/"` alike, but `setByPath`/`setPath` no-op'd on root
+instead of replacing it) converged on the read/write split named above. The
+full Δ1-Δ10 delta table lives in
+[lld-0001-a2ui-data-model-consumption §Data](../../../../../../docs/ops/lld/lld-0001-a2ui-data-model-consumption.md#data);
+the surviving regression proof for the pointer-only deltas is
+`packages/gen-ui/a2ui/data-model-pointer-semantics.test.js` (migrated from
+`path-pointer.test.js` in P4).
 
 ## What stays fixed (don't "fix" these under this ADR)
 
@@ -76,15 +87,24 @@ instead of replacing it) converges on the read/write split named above.
 - `record.js`'s bidirectional-overlap store — app-layer, outside this
   package, rides a separate review track (R2), not this ADR.
 
-## Consumption mechanism — open, LLD decides
+## Consumption mechanism — decided (build-time copy)
 
-`@adia-ai/a2ui` is a zero-runtime-deps package (ADR-0048 posture);
-`packages/genui` is a vendored, never-edited-in-place artifact (ADR-0059).
-Whether the adopted primitives land via a build-time vendor-copy (with a
-provenance stamp) or a workspace-internal import is NOT decided by
-ADR-0078 — whichever the LLD picks must either preserve the zero-deps
-posture or explicitly re-rule it. Check the LLD (once authored, per gh#1784)
-before assuming either mechanism.
+`@adia-ai/a2ui` is a zero-runtime-deps package (ADR-0048 posture).
+**[amended 2026-08-29, ADR-0096, gh#2373 — recorded in ADR-0078's own
+2026-08-29 amendment]**
+`packages/genui` is absorbed first-party in-repo source, not a vendored
+artifact — `packages/genui/VENDOR.json` and the vendor-and-sync mechanism
+are gone (gh#2372 closed; `VENDOR.json` confirmed absent from origin/main).
+[lld-0001](../../../../../../docs/ops/lld/lld-0001-a2ui-data-model-consumption.md)
+decided a build-time byte-identical copy of
+`packages/genui/renderer/dist/data-model.js` (+`.d.ts`) into
+`packages/gen-ui/a2ui/`, with a `data-model.provenance.json` sidecar and a
+freshness gate in `npm run check` — preserving the zero-deps posture (no new
+package dependency, no covert workspace-import). The provenance sidecar now
+points at the in-repo source path instead of a `VENDOR.json` sha: it stamps
+`source.js`/`source.dts` + `syncedAt` + `contentHash` only —
+`packages/genui/renderer/dist/data-model.js` — with no vendor-sha field at
+all.
 
 ## Eval-floor risk
 

package/skills/a2ui-maintenance/references/pipeline-overview.md

@@ -4,34 +4,63 @@
 
 Two protocol layers coexist (ADR-0059, `docs/ops/spec/spec-a2ui-v1-conformance.md`):
 the shipping dialect this pipeline emits (Layer A, `packages/gen-ui/a2ui/`) and
-the vendored A2UI v1.0 Candidate stack (Layer B, `packages/genui/`) reached
-through `packages/genui/wire-bridge/`. Candidate terminology is
+the A2UI v1.0 Candidate stack (Layer B, `packages/genui/`) reached
+through `packages/genui/wire-bridge/`. **[amended 2026-08-29, ADR-0096]**
+`adiahealth/gen-ui-system` is absorbed first-party under `packages/genui/`
+and the standalone repo is archived — Layer B is in-repo source, not a
+vendored dependency; `VENDOR.json` and the sync mechanism are gone (see
+this same note on siblings `data-model-reactivity.md` and
+`surface-lifecycle.md`). Candidate terminology is
 **renderer/agent** — never client/server: `callableFrom` values are
 `rendererOnly`/`agentOnly`/`rendererOrAgent`; the wire function kinds are
 `callRendererFunction`/`callAgentFunction` +
 `rendererFunctionResponse`/`agentFunctionResponse`; the MIME type is
 `application/a2ui+json`; catalog resolution is strict (component `catalogId` →
 surface `catalogId` → error, no registry default). The producer's
-`wireFormat: 'v1'` flag exists and defaults to `'dialect'`
-(`packages/genui/adia-producer/exit-gate.js`). Documents authored here stay
-dialect-shaped; the bridge owns the translation — never hand-write Candidate
-envelopes from this skill's surfaces.
-
-site-a2ui (the build-time HTML→A2UI docs-site transpile) is RULED fit as the
-**dialect side's regression corpus**, not a v1.0 conformance bed (ADR-0068):
-it exercises the dialect renderer, the ADR-0061 lifecycle path, and the
-engine transpiler at real-content scale in production, but never touches the
-producer, the bridge, or the `wireFormat` flag — so it neither blocks the
-v1.0 migration nor gets re-pointed at the v1 wire. **Named expiry:** that
-ruling is load-bearing on `wireFormat` defaulting to `'dialect'`; the flag-flip
-ADR that makes `'v1'` the shipping default MUST re-rule site-a2ui's fitness
-(re-point vs retirement-by-attrition) — the fitness verdict expires with the
-`'dialect'` default. Expanding site-a2ui — new message kinds, new consumers,
-or a promotion PROGRAM toward all routes — also invalidates the ruling's
-basis and needs a new decision; burn-down of existing
-`visual-drift`/`blocked-format-gap` rows (including a route thereby becoming
-parity-promoted) is ordinary maintenance and stays permitted (ADR-0068
-Decision 5).
+`wireFormat` flag (`packages/genui/adia-producer/exit-gate.js`) **[flipped
+2026-08-30, PR #2412]** now defaults to `'v1'`, not `'dialect'` — ADR-0072
+ratified the flip (its precondition, genui-system#51's re-verification,
+re-scoped and satisfied via ADR-0096/PR #2401) and the flip itself has since
+executed. Documents authored here stay dialect-shaped; the bridge owns the
+translation — never hand-write Candidate envelopes from this skill's
+surfaces.
+
+**Catalogs are opt-out scopes, not a taxonomy.** A2UI v1.0 lets a renderer
+mix catalogs within one surface: `createSurface.catalogId` is the default,
+and any component may carry its own `catalogId` to override it
+(a2ui.org/specification/v1.0-a2ui/, "Catalog Reference"). So the useful way
+to split a catalog is by what an app OMITS, never by component kind — Buttons
+and Inputs are never omitted together, whole feature areas are. This is the
+ratified basis of the five-catalog partition (gh#2211, Kim 2026-08-28):
+`adia.core` / `adia.navigation` / `adia.data` / `adia.agent` / `adia.shells`,
+every one a derived view over the yaml `category` axis and package path,
+never a hand list. Two facts that trip a re-derivation: the `category` axis
+had no `data` bucket for tables/charts (they declared `agent`; the partition's
+pre-step re-categorizes five components), and `packages/web-modules/**` is a
+path seam, not a category (its sidecars mostly declare `layout`/`container`).
+The partition lives on the Layer B side only; the dialect catalog stays one
+file per ADR-0059 §1. The 44 L1 harvested widgets are a pattern library, not
+catalog members.
+
+site-a2ui (the build-time HTML→A2UI docs-site transpile) was RULED fit as
+the **dialect side's regression corpus**, not a v1.0 conformance bed
+(ADR-0068): it exercised the dialect renderer, the ADR-0061 lifecycle path,
+and the engine transpiler at real-content scale in production, but never
+touched the producer, the bridge, or the `wireFormat` flag. That fitness
+ruling was load-bearing on `wireFormat` defaulting to `'dialect'`, with a
+**Named expiry**: the flag-flip ADR that makes `'v1'` the shipping default
+had to re-rule site-a2ui's fitness (re-point vs retirement-by-attrition).
+
+**[resolved, ADR-0072]** That trigger has fired and been ruled:
+retirement-by-attrition, not re-point (Decision 2) — promotion program
+closed, site-a2ui moves to breakage-only maintenance, an attrition-exit
+ticket tracks the wind-down (gh#2410), and the mechanism is removed once the
+promoted set reaches zero. The flip itself has since executed (PR #2412,
+merged 2026-08-30: `exit-gate.js` now defaults to `'v1'`) — site-a2ui is in
+its attrition window now, not a still-open future trigger. Burn-down of
+existing `visual-drift`/`blocked-format-gap` rows is no longer "ordinary
+maintenance toward parity promotion" (ADR-0068 Decision 5) — it is wind-down
+toward the mechanism's removal per gh#2410.
 
 All paths repo-relative. Specs worth reading before structural changes:
 `.claude/docs/specs/a2ui-v0.9-catalog-guide.md` (protocol + catalog format),
@@ -151,6 +180,11 @@ for any constant or decision lives in git and PR descriptions
     currently fails, mostly a schema-generation gap around `data-*`/`span`
     attributes, not corpus-content defects — see the ticket before
     assuming a chunk is actually broken).
+13. **Every generated catalog schema carries three synthesized universal
+    props today** (`slot`/`hidden`/`ariaLive`, none declared in any yaml
+    SoT); ADR-0097 rules a fourth, `traits`, but that part is decided-not-
+    yet-shipped (gh#2513) — see `primitive-authoring/references/
+    yaml-contract.md` §Synthesized universal props for the full contract.
 
 ## Test + run commands (all verified in root package.json)
 

package/skills/a2ui-maintenance/references/surface-lifecycle.md

@@ -57,13 +57,20 @@ Staleness is exposed as one attribute plus three events, never styling:
 
 The lifecycle is renderer-runtime work on gen-ui-kit's side of the ADR-0059
 line. The three wire envelope kinds (`beginSurfaceUpdate` /
-`commitSurfaceUpdate` / `abortSurfaceUpdate` as v1.0 server kinds) are a
-genui-system standard PROPOSAL, not dialect schema — `a2ui.schema.json`
-gains nothing, the dialect wire format is byte-identical, and stream-driven
-regeneration waits on the upstream standard (the dialect escape hatch was
-explicitly denied at ratification). Never hand-write lifecycle envelopes
-from this skill's surfaces; the Bridge owns the mapping when the standard
-lands.
+`commitSurfaceUpdate` / `abortSurfaceUpdate` as v1.0 server kinds) are
+defined by the v1.0 Candidate reference implementation — `a2ui.schema.json`
+gains nothing, the dialect wire format is byte-identical. Never hand-write
+lifecycle envelopes from this skill's surfaces; the Bridge owns the mapping
+when the kinds land.
+
+**[amended 2026-08-29, ADR-0096]** `adiahealth/gen-ui-system` is absorbed
+first-party under `packages/genui/` and the standalone repo is archived —
+there is no external, separately-governed "upstream standard" to wait on
+any more. ADR-0096 Decision 5: gen-ui-kit "owns the whole stack now... and
+the v1.0 Candidate reference implementation itself, not only the consumer
+side of a vendor boundary." Stream-driven regeneration now proceeds on
+gen-ui-kit's own schedule against the in-repo `packages/genui/` source,
+not an upstream release.
 
 ## Interlock worth knowing
 

package/skills/component-md-authoring/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: component-md-authoring
+description: >-
+  Author the two judgment sections of a component's `component.md` —
+  Screen-reader spec and Behavioral spec — and keep it PR-fresh. Use when a
+  component's states, composed children, aria behavior, or error/empty/
+  loading handling changes and it already has (or should grow) a
+  `component.md`, or when asked to "add component.md for X" / "write the
+  screen-reader spec for X" / "why did check:component-md-fresh fail". NOT
+  the yaml prop/slot/event/token contract itself (primitive-authoring owns
+  that — this skill only owns the two authored yaml fields,
+  `screenReader`/`behavioral`, plus the optional `intent` field); NOT gen-ui
+  corpus/retrieval wiring (a2ui-maintenance); NOT a component's CSS token
+  audit (component-token-audit).
+disable-model-invocation: false
+user-invocable: true
+---
+
+# component-md-authoring
+
+`component.md` (gh#2615) is a generated shell, per-component, sitting next
+to its `.yaml` SoT (`packages/web-components/components/<name>/component.md`,
+or `packages/web-modules/<cluster>/<name>/component.md` for a composite/
+shell). Every section except two is mechanically transcluded from the yaml
+by `scripts/build/gen-component-md.mjs` — Intent, API (props/events/slots),
+Structural (Light DOM anatomy + states + composes), Tokens, Rules,
+Anti-patterns, Related. This skill's whole charter is the two sections that
+aren't: **Screen-reader spec** and **Behavioral spec**.
+
+## The load-bearing decision: where the authoring happens
+
+You do not hand-edit `component.md`. You edit the yaml's `screenReader:`
+and `behavioral:` fields (and, ideally, `intent:`) — `component.md` is
+regenerated from them. This is deliberate, not incidental:
+
+- **No second source of truth.** plan-2615's evidence pass on gh#2615 found
+  most of component.md's "intent layer" already lives in the yaml
+  (`a2ui.rules`, `anti_patterns`, `related`, examples). The two genuine
+  gaps — screen-reader and behavioral judgment — get the SAME treatment:
+  authored once, in yaml, transcluded everywhere else (component.md today;
+  gen-ui corpus derivation once a2ui-maintenance wires it in).
+- **The freshness gate is PR-blocking, not staleness-only.** Because the
+  authored content lives in a yaml field, `component.md` is 100%
+  mechanically regenerable — `check:component-md-fresh` can do a real byte-
+  diff, the same shape as `check:reference-docs-fresh`, except PR-blocking
+  (operator ruling 2026-08-31) rather than advisory-only. A hand-edit
+  directly in `component.md` will be silently clobbered by the next
+  `npm run docs:component-md` and will fail the gate as "not fresh" — this
+  is the guard rail, not a bug.
+
+## Authoring a component's two sections
+
+1. Confirm the component doesn't already have adequate coverage — read its
+   existing `states:`, `a2ui.rules`, and `.class.js` source. Per
+   primitive-authoring's own first principle, **source wins**: verify every
+   claim you're about to write (focus order, aria attribute names, event
+   names) against the actual `.class.js`/`.js` file, not just the yaml
+   prose.
+2. **Screen-reader spec** — focus order across composed children (order
+   `showModal()`/connect moves focus, what wraps at the tab boundary),
+   live-region announcement sequence (what fires `role="alert"` or an
+   `aria-live` region, and when), and any keyboard map beyond the trait
+   default (`pressable`/`focusable` already cover Enter/Space/click — only
+   document what's ADDITIONAL, e.g. arrow-key grid nav, Escape-dismiss).
+   Do not restate a static `aria-*` attribute the yaml's `props`/`states`
+   already document plainly — that's derived content, not new judgment.
+3. **Behavioral spec** — dismiss/error/empty/loading states and
+   transitions NOT already modeled by `states:`. Distinguish "fetching" vs
+   "confirmed empty" where both exist (see `table.yaml`'s `screenReader`/
+   `behavioral` for a worked example: three distinct states, not one).
+   Name what is explicitly NOT handled (no built-in error state, no
+   built-in loading state) as clearly as what is — an absence is often the
+   more actionable fact for a consumer.
+4. Both fields require `minLength: 20` (schema-enforced) — a placeholder
+   one-liner will fail `check:components-valid`. Write real prose, grounded
+   in source, not a restatement of the component's `description`.
+5. Regenerate and verify:
+
+   ```bash
+   node scripts/build/components.mjs --validate   # schema-valid yaml
+   npm run docs:component-md                      # regenerate component.md
+   npm run check:component-md-fresh                # PR-blocking gate
+   ```
+
+6. If this is the component's FIRST component.md (yaml previously had
+   neither field), run `npm run build:components` too — the corpus/catalog
+   rebuild picks up the new yaml content, and `npm run eval:diff --
+   --engine zettel` should show no regression (preserve-not-regress floor,
+   owned by a2ui-maintenance).
+
+## Scope (gh#2615 pilot)
+
+`scripts/build/gen-component-md.mjs`'s `SCAN_ROOTS` covers
+`packages/web-components/components/` and `packages/web-modules/chat/`
+today — the pilot 5 (`button`, `modal`, `table`, `field`, `chat-shell`).
+Extending to every web-modules cluster, or sweeping the remaining ~145
+primitives, is deliberately out of scope for this pass (file a follow-up
+task rather than silently expanding `SCAN_ROOTS` for one-off need — a
+cluster added there without a plan for authoring every component inside it
+just produces components with a `.yaml` but no eligible `component.md`,
+which the generator already handles gracefully by skipping them, but which
+defeats the point of a rollout plan).
+
+## Cross-references
+
+- `primitive-authoring`'s authoring-cycle: add "new/changed states or aria
+  behavior → component-md-authoring's authored sections may need a pass"
+  to your own SoT-change checklist when editing a yaml that already has a
+  `component.md` sibling.
+- `scripts/schemas/component.yaml.schema.json` — `intent`/`screenReader`/
+  `behavioral` field definitions (all optional; a component with a `.yaml`
+  but neither authored field simply has no `component.md` yet).
+- `scripts/verify/check-component-md-fresh.mjs` — the PR-blocking gate:
+  byte-freshness (component.md matches a fresh render) AND same-PR
+  coverage (a component.md-bearing component's source/yaml change must
+  touch component.md in the same diff).

package/skills/component-md-authoring/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Component Md Authoring"
+  short_description: "Author the two judgment sections of a component's `component.md` — Screen-reader spec and Behavioral spec — and keep it PR-fresh."

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

@@ -31,6 +31,7 @@ Two entry variants, converging at Step 5:
 | 9 | Dispatch publish workflows; wait; verify registry | Publish |
 | 10 | GH releases + site deploy dispatch | Deploy |
 | 11 | Author release notes (default, not optional) | No |
+| 12 | Restore the pnpm dev layout (`npm ci` left it npm-shaped) | node_modules only |
 
 ---
 
@@ -44,8 +45,18 @@ git -C "$REPO" status --short
 git -C "$REPO" log --oneline -8
 git -C "$REPO" fetch && git -C "$REPO" log HEAD..origin/main --oneline   # must be empty
 git -C "$REPO" tag --list 'vX.Y.Z' '*-vX.Y.Z'   # must NOT exist yet
+[ -d "$REPO/node_modules/.pnpm" ] && echo "STOP: pnpm-shaped node_modules — run npm ci first"   # gate 9 precondition, see §3.1 layout note
 ```
 
+**Check the `node_modules` layout here, not at gate 9.** The §3.1 layout note (gh#1359)
+already says gate 9 (`check:js-bundles-fresh`) needs the npm-ci layout, but it sits AFTER
+the gate roster and is easy to read past — the v0.8.55 cut (2026-08-28) ran the full
+33-gate pre-flight under a pnpm-shaped tree, lost ~12 minutes to gates 1-8 and 10-33
+passing, then failed gate 9 with phantom bundle drift (1.24 MB on disk vs 1.52 MB fresh
+on every JS entry — the Phosphor icon glob resolving differently, not a real source
+change). The one-line check above fails in under a second instead. `npm ci` to recover;
+`npm install` alone does NOT reshape an existing pnpm tree.
+
 `branch --show-current` ≠ `main` → stop; cutting on a feature branch pushes a stale `main` ref while the tags point at the feature tip. Recovery: [`recovery-paths.md`](recovery-paths.md) §Scenario 8. If multiple unpushed `release(*):` commits exist → this is a batch push, [`recovery-paths.md`](recovery-paths.md) §Scenario 2.
 
 ## §Step 2 — Classify uncommitted files; stash strays
@@ -244,7 +255,9 @@ 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/gen-ui/a2ui/*/package.json packages/gen-ui/a2ui/*/CHANGELOG.md \
-  packages/genui/adia-catalog/base.json packages/genui/adia-catalog/adia-pack.json \
+  packages/genui/adia-catalog/adia.core.json packages/genui/adia-catalog/adia.navigation.json \
+  packages/genui/adia-catalog/adia.data.json packages/genui/adia-catalog/adia.agent.json \
+  packages/genui/adia-catalog/adia.shells.json \
   docs/ops/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
 ```
@@ -261,6 +274,19 @@ node scripts/build/components.mjs --verify && npm run check:chunks-fresh && npm
 
 Drift here means a regen output was left out of the allowlist — stage it and re-run. <2s now vs ~5min of tag-move recovery after CI catches it. Do not proceed to tag with drift.
 
+## §Step 5.6 — Unstaged-tracked-files guard (`release-pack.mjs`, gh#2473)
+
+`release-pack.mjs`'s Step 5 mechanizes this: right after its own `git add`
+(the allowlist above, as automated), it runs `git status --porcelain` and
+fails the cut if any tracked file is still modified-in-the-worktree —
+proof the allowlist covered everything bump.mjs / cut-hygiene touched this
+cut, not just what §Step 5.5's three named freshness gates happen to check.
+This is the fourth time the allowlist itself went stale (gh#1198, gh#1899,
+gh#1954, gh#2473 — most recently the factory README's generation-MCP pin
+prose), so the guard is generic rather than another named file. A manual
+cut should run the equivalent check by hand: `git status --porcelain`
+after staging must be empty of `M`/`D` lines.
+
 ## §Step 5.7 — Release PR: push the branch, merge, re-baseline
 
 The release commit reaches `main` through the standard PR flow. Mechanized
@@ -415,6 +441,25 @@ 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".
 
+## §Step 12 — Restore the dev layout
+
+The cut runs under `npm ci` (Step 1's layout check, gate 9), and that leaves
+`node_modules` npm-shaped. The dev server refuses to start on that tree:
+`npm run dev`'s `predev` hook (`scripts/dev/check-pnpm-layout.mjs`) hard-stops
+because the Phosphor icon glob matches zero files under the hoisted layout and
+every `<icon-ui>` would render empty (gh#340). Put the tree back before handing
+the checkout to anyone, including yourself:
+
+```bash
+pnpm install                                    # single checkout
+node scripts/dev/bootstrap-worktree.mjs         # inside a linked worktree
+```
+
+Both are idempotent and touch no committed file (`pnpm-lock.yaml` is
+gitignored). Live cost of skipping this: the v0.8.55 cut (2026-08-28) left the
+operator's primary checkout unable to run `npm run dev` until the layout was
+restored by hand.
+
 ## §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

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

@@ -159,6 +159,7 @@ The two `audit:*` probes are soft-fail pre-cut (exit-1 only on criticals); findi
 - **What:** the vitest suite (~1000+ tests).
 - **Stale-test failure:** the test asserts a behavior a peer deliberately changed (CHANGELOG-documented) without updating the assertion. Tell it apart by reading assertion vs CHANGELOG vs source: if the code matches the CHANGELOG's described behavior, the test is stale — update the assertion (see [`recovery-paths.md`](recovery-paths.md) §Scenario 5). Real regression → fix the regression.
 - **Parallel-contention flake:** heavy web-modules composite suites can fail under full parallelism on a loaded machine (`signals: drain loop exceeded 100 iterations`). Load-dependent, not a code defect. Sequential is the source of truth, and **the roster gate now runs it directly** (`npm run test:unit:serial` = `vitest run --no-file-parallelism`, gate 4 since 2026-07-19) — a parallel `test:unit` flake outside the roster still isn't a blocker, and don't raise the drain guard.
+- **Same-host contention timeout (gh#2195):** gate 4 running solo (Phase 1, see the execution-model note above) isolates it from every OTHER pre-flight gate, but not from unrelated concurrent load on the same shared, multi-tenant host — another agent's build, a peer's own `npm run check`. gh#2195's diagnosis found this surfaces as a genuine 45s per-test timeout on a DIFFERENT single file each run, with no repeat culprit (the contention signature, not an order-dependent leak) — and found no separate "release pre-flight runner" with its own core count exists to recalibrate `worker-cap.mjs` against; it's the same operator/agent host either way. `release-pack.mjs`'s `runSoloGateWithRetry()` now retries gate 4 exactly once, scoped to only the file(s) it named as failed, when the failure output has a parseable `FAIL <file>` list — a file that fails once and passes clean on that immediate re-run was contention, not a regression; a file that fails twice is treated as a real one and the pre-flight still aborts. No other gate, and no OTHER invocation of `test:unit:serial` (CI, local dev, `npm run check`), gets this retry.
 - **Exit 143 (SIGTERM):** the vitest process was KILLED (resource pressure / a stray terminator), not a test failure — re-run the gate directly (`npx vitest run --no-file-parallelism`) before diagnosing anything; a clean re-run means transient, proceed (v0.8.34 handoff hit this).
 - **First-time-at-cut failures are REAL (v0.8.34):** this serial suite runs tests PR CI never does — `exit-gate.corpus` (dialect-catalog conformance over real harvested chunks) surfaces yaml-schema drift (e.g. an array prop missing `items.type`, the command/combobox `DynamicStringList` mis-map) only HERE, potentially weeks after the yaml edit merged green. Treat such a failure as a genuine latent defect to root-cause at the yaml SoT, never as release-blocking noise. (Structural fix — promoting the corpus batch into PR CI — tracked as a follow-up.)
 

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

@@ -516,6 +516,75 @@ const EVAL_HEALTH_CHAIN_NUMBERS = [16, 27, 28]; // eval:diff zettel → eval:dif
 // for a dedicated/idle host.
 const PREFLIGHT_CONCURRENCY = Number(process.env.PREFLIGHT_CONCURRENCY) || 4;
 
+// gh#2195 — gate 4 flake-retry, scoped to the solo phase only.
+//
+// gh#2195's own diagnosis found two mechanisms behind "test:unit:serial
+// flakes under host load": a real wall-clock timing race in one test (fixed
+// separately, PR #2290) and genuine 45s timeouts under contention on the
+// same shared, multi-tenant host an operator or agent session runs
+// everything else on. There is no separate "release pre-flight runner" with
+// its own core count to recalibrate worker-cap.mjs against — Phase 1 above
+// already runs gate 4 solo, with no sibling PRE-FLIGHT gate competing, so
+// what is left is contention from OTHER, unrelated concurrent processes on
+// that same host (other agents' builds, other `npm run check` runs) that no
+// single process's static worker-cap formula can see or size against.
+//
+// A file that fails once under that kind of contention and then passes
+// clean on an immediate, unmodified re-run was never proving a code
+// regression — gate 4 exists to prove one, and a transient scheduling stall
+// isn't that. A file that fails twice in a row almost certainly is a real
+// regression (a genuine bug reproduces deterministically; host contention
+// does not), so this retries AT MOST ONCE, and only the files gate 4 itself
+// named as failed — never the whole suite, never a second retry. Scoped to
+// gate 4's solo phase alone: every other gate, and every OTHER invocation of
+// `npm run test:unit:serial` (CI, local dev, `npm run check`), stays
+// single-shot and strict — this never masks a real regression anywhere else.
+const FAILED_TEST_FILE_RE = /^ FAIL\s+(\S+)/gm;
+
+// Pure — extracts the deduped list of failed test file paths from vitest's
+// default-reporter output. Its "Failed Tests" section prints a leading
+// ` FAIL  <file> > ...` line per failing test — the same line is emitted for
+// an assertion failure and for a per-test timeout alike.
+function extractFailedTestFiles(text) {
+  const files = new Set();
+  for (const m of (text || '').matchAll(FAILED_TEST_FILE_RE)) files.add(m[1]);
+  return [...files];
+}
+
+// Runs the solo gate; on failure, extracts which file(s) it named as failed
+// and — only if at least one was parseable — retries gate 4 scoped to
+// exactly those files, once. An unparseable failure (e.g. vitest itself
+// crashed before printing a summary) fails closed: no retry, same behavior
+// as before this change.
+async function runSoloGateWithRetry(soloGate, args) {
+  const first = await runGateCaptured(soloGate, args);
+  printGateResult(first);
+  if (first.ok) return first;
+
+  const failedFiles = extractFailedTestFiles(`${first.stdout || ''}\n${first.stderr || ''}`);
+  if (failedFiles.length === 0) {
+    console.error('\n  Gate 4 failed with no parseable failed-file list — not retrying (fail closed, gh#2195).');
+    return first;
+  }
+
+  console.log(`\n  Gate 4 failed on ${failedFiles.length} file(s) — retrying once, scoped to just those files (host-contention tolerance, gh#2195):`);
+  for (const f of failedFiles) console.log(`    - ${f}`);
+  const retryGate = {
+    n: soloGate.n,
+    cmd: `${soloGate.cmd} -- ${failedFiles.map((f) => `"${f}"`).join(' ')}`,
+    what: `${soloGate.what} — retry of ${failedFiles.length} flaky file(s)`,
+  };
+  const retry = await runGateCaptured(retryGate, args);
+  printGateResult(retry);
+
+  if (retry.ok) {
+    console.log(`\n  ✓ gate 4 passed on retry — treating the first failure as host contention, not a regression (gh#2195).`);
+    return { ...retry, note: `passed on retry after 1 failure (gh#2195 host-contention tolerance); first attempt failed: ${failedFiles.join(', ')}` };
+  }
+  console.error('\n  Gate 4 failed again on retry — a real regression, not a flake. Aborting.');
+  return { ...retry, note: `failed again on retry (gh#2195); first attempt failed: ${failedFiles.join(', ')}` };
+}
+
 // Resolves one gate's actual command string — the same versionArg/
 // targetVersionArg/resume branching step3PreFlight has always applied.
 // Returns null for a versionArg gate deferred by an in-flight resume (Step
@@ -656,8 +725,7 @@ async function step3PreFlight(args) {
   const poolGates = GATE_ROSTER.filter((g) => g.n !== SOLO_GATE_NUMBER && !chainNumbers.has(g.n));
 
   console.log(`\n-- Phase 1/2: gate ${SOLO_GATE_NUMBER} solo (test:unit:serial) --`);
-  const soloResult = await runGateCaptured(soloGate, args);
-  printGateResult(soloResult);
+  const soloResult = await runSoloGateWithRetry(soloGate, args);
   if (!soloResult.ok) {
     console.error('\n  Pre-flight aborted at Phase 1 — fix the gate failure before proceeding.');
     console.error('  See references/gates-catalog.md for failure-mode → recovery.');
@@ -799,10 +867,11 @@ function step4PromoteAndBump(args) {
   sh('npm install --package-lock-only --no-audit --no-fund', args);
   sh('npm run check:lockstep', args);
 
-  // Step 4d.5 — regenerate the derived genui catalog (gh#617): its catalogId
-  // embeds the lockstep version (`adia.base@X.Y.Z`), so the bump above just
-  // invalidated base.json/adia-pack.json. The v0.8.26 cut skipped this and
-  // check:genui-catalog failed in CI one push later. Step 5 stages both files.
+  // Step 4d.5 — regenerate the derived genui catalog (gh#617; gh#2211/ADR-0093
+  // repartitioned): each catalog's catalogId embeds the lockstep version
+  // (`adia.<scope>@X.Y.Z`), so the bump above just invalidated all five.
+  // The v0.8.26 cut skipped this and check:genui-catalog failed in CI one
+  // push later. Step 5 stages all five files.
   console.log('\n  Step 4d.5 — regenerate derived genui catalog (catalogId carries the lockstep version):');
   sh('node scripts/build/derive-genui-catalog.mjs', args);
 
@@ -907,6 +976,39 @@ function step4PromoteAndBump(args) {
   }
 }
 
+// Pure so the selftest can lock the parse without a real git tree (gh#2473,
+// same "pure so selftest can lock the transform" shape as bump.mjs's
+// bumpPinnedRef). Takes `git status --porcelain` output, returns the tracked
+// paths Step 5.6's guard should block on — worktree status (porcelain
+// column Y, index 1) 'M' or 'D'; 'A'/'?' (new/untracked) are out of scope,
+// see the guard's own comment. Handles the two porcelain path shapes a
+// plain `line.slice(3)` mishandles: C-style-quoted paths (git quotes any
+// path containing a space, or a rename's `->` separator surrounded by
+// spaces) and rename/copy entries (`R  old -> new`, `C  old -> new`),
+// where the file that actually needs staging is the NEW path.
+function unstagedTrackedLeftovers(porcelainOutput) {
+  const leftover = [];
+  for (const line of porcelainOutput.split('\n')) {
+    if (line.length <= 3 || !/[MD]/.test(line[1])) continue;
+    let rest = line.slice(3).trim();
+    // Rename/copy: "old -> new" (both sides may independently be quoted) —
+    // the worktree-dirty path to report is the NEW (post-rename) side.
+    const arrow = rest.indexOf(' -> ');
+    if (arrow !== -1) rest = rest.slice(arrow + 4).trim();
+    // git C-quotes a path containing a space, a quote, or a control char as
+    // a double-quoted, backslash-escaped string — strip the wrapper and
+    // undo the escaping rather than reporting the literal quoted form.
+    if (rest.length >= 2 && rest[0] === '"' && rest[rest.length - 1] === '"') {
+      rest = rest
+        .slice(1, -1)
+        .replace(/\\"/g, '"')
+        .replace(/\\\\/g, '\\');
+    }
+    leftover.push(rest);
+  }
+  return leftover;
+}
+
 // ── Step 5 — Commit ──────────────────────────────────────────────
 function step5Commit(args) {
   if (args.mode === 'handoff') {
@@ -956,14 +1058,18 @@ function step5Commit(args) {
     `docs/ops/releases/v${args.version}.md`,
     // gh#617: Step 4d.5 regenerates these post-bump (catalogId embeds the
     // lockstep version); unstaged, check:genui-catalog fails in CI (v0.8.26).
-    // catalog-data.js is the same derivation's third output (the browser-safe
-    // ES-module projection of base.json/adia-pack.json) — check-genui-catalog.mjs
-    // verifies its freshness too, but this list never carried it (found live
-    // during the v0.8.33 cut: base.json/adia-pack.json staged and committed
-    // fine, catalog-data.js sat modified-uncommitted, CI caught the drift a
-    // fresh checkout exposes that a local working tree doesn't).
-    'packages/genui/adia-catalog/base.json',
-    'packages/genui/adia-catalog/adia-pack.json',
+    // gh#2211 (ADR-0093): the old base/pack pair retired in favor of five
+    // opt-out-scoped catalogs. catalog-data.js is the same derivation's sixth
+    // output (the browser-safe ES-module projection of all five) —
+    // check-genui-catalog.mjs verifies its freshness too, but this list never
+    // carried it (found live during the v0.8.33 cut: the JSON catalogs staged
+    // and committed fine, catalog-data.js sat modified-uncommitted, CI caught
+    // the drift a fresh checkout exposes that a local working tree doesn't).
+    'packages/genui/adia-catalog/adia.core.json',
+    'packages/genui/adia-catalog/adia.navigation.json',
+    'packages/genui/adia-catalog/adia.data.json',
+    'packages/genui/adia-catalog/adia.agent.json',
+    'packages/genui/adia-catalog/adia.shells.json',
     'packages/genui/adia-catalog/catalog-data.js',
     // gh#1361: Step 4d.5b regenerates the catalog tier index post-bump (it
     // derives from the catalog derive-genui-catalog.mjs just refreshed) and,
@@ -1015,12 +1121,54 @@ function step5Commit(args) {
         // Codex `agents/openai.yaml` glob above is.
         files.push(`${dir}/plugin.yaml`, `${dir}/__init__.py`, `${dir}/prompts/*.md`);
       }
-      if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`, `${dir}/hermes-mcp.yaml`);
+      // gh#2473: bump.mjs's PINNED_REFS also rewrites the factory README's
+      // OWN prose echo of the generation-MCP pin (`server pinned:
+      // @adia-ai/mcp@X` — see bump.mjs's A2UI_MCP_PIN comment,
+      // check:plugin-count-claims' "factory README generation-MCP pin"
+      // equality check) — same invariant-8 scope as .mcp.json, but this
+      // list only ever staged .mcp.json + hermes-mcp.yaml, so the README
+      // edit rode along unstaged/uncommitted every cut until Step 5.6
+      // (below) started catching it.
+      if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`, `${dir}/hermes-mcp.yaml`, `${dir}/README.md`);
       return files;
     }),
   ];
   sh(`git add ${releaseFiles.join(' ')}`, args);
   sh('git diff --cached --stat | tail -3', args);
+
+  // Step 5.6 — unstaged-tracked-files guard (gh#2473). Numbered 5.6, not
+  // 5.5: cut-procedure.md's own §Step 5.5 already names a DIFFERENT,
+  // pre-existing manual freshness trip-wire (components.mjs --verify +
+  // check:chunks-fresh + check:embeddings-fresh) that this script doesn't
+  // automate — reusing "5.5" here would collide with that doc section for
+  // an operator reading both. This guard slots before §Step 5.7 (the
+  // release PR), the next free number in the doc's own sequence.
+  //
+  // The release commit's file allowlist above has drifted from what
+  // bump.mjs / cut-hygiene actually edit more than once (gh#1198, gh#1899,
+  // gh#1954, gh#2473 itself) — a step upstream starts writing a new file
+  // and nobody remembers to add it here, so it rides through Step 5
+  // uncommitted and either ships a half-bumped release commit or gets
+  // discovered only when a later gate (or a human diff) trips over it.
+  // Fail loud, right here, rather than trusting the allowlist is
+  // exhaustive: after staging everything this list knows about, anything
+  // STILL modified-in-the-worktree on a tracked path means the allowlist
+  // missed a file this cut's bump/hygiene pass touched.
+  if (args.dry) {
+    console.log("  [dry] git status --porcelain (Step 5.6 guard: no unstaged tracked changes remain — Step 5's allowlist covered everything this cut touched)");
+  } else {
+    const leftover = unstagedTrackedLeftovers(shQuiet('git status --porcelain', args));
+    if (leftover.length > 0) {
+      console.error(`\nERROR: ${leftover.length} tracked file(s) modified by this cut are still unstaged after Step 5's allowlist ran:`);
+      for (const f of leftover) console.error(`  ✗ ${f}`);
+      console.error('\n  bump.mjs (or a cut-hygiene step) edited these but Step 5\'s `releaseFiles`');
+      console.error('  allowlist does not know about them — add the missing path(s) and re-run,');
+      console.error('  or `git add` + `git commit --amend` them onto the release commit by hand.');
+      process.exit(1);
+    }
+    console.log("  ✓ no unstaged tracked changes remain — Step 5's allowlist covered everything this cut touched");
+  }
+
   if (!args.commitMessageFile) {
     console.error('ERROR: --commit-message-file required for cut/from-scratch mode');
     process.exit(2);
@@ -1403,9 +1551,120 @@ async function main() {
 // must never proceed to tag/push/publish on its own). A fixture temp dir
 // supplies the operator-authored content files (--commit-message-file /
 // --gh-notes-file) so nothing here depends on real repo state.
-function selftest() {
+async function selftest() {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'release-pack-selftest-'));
   try {
+    // gh#2195 — gate-4 retry: extractFailedTestFiles() must parse vitest's
+    // default-reporter ` FAIL  <file> > ...` lines, and
+    // runSoloGateWithRetry() must retry exactly once, scoped to exactly
+    // those files, accepting a clean retry as a host-contention flake but
+    // never masking a failure that reproduces, and never retrying at all
+    // when the failure has no parseable failed-file list.
+    {
+      const sample = [
+        ' FAIL  packages/a/b.test.js > describe > one',
+        ' FAIL  packages/a/b.test.js > describe > two',
+        ' FAIL  packages/c/d.test.js > describe > three',
+      ].join('\n');
+      const files = extractFailedTestFiles(sample);
+      if (files.length !== 2 || !files.includes('packages/a/b.test.js') || !files.includes('packages/c/d.test.js')) {
+        console.error(`selftest FAIL: extractFailedTestFiles() expected 2 deduped files, got: ${JSON.stringify(files)}`);
+        process.exit(1);
+      }
+
+      const flakyMarker = path.join(tmp, 'flaky-invocation-count');
+      const flakyScript = path.join(tmp, 'flaky-once.mjs');
+      fs.writeFileSync(flakyScript, `
+        import { writeFileSync } from 'node:fs';
+        const isRetry = process.argv.slice(2).includes('--');
+        if (!isRetry) {
+          writeFileSync(${JSON.stringify(flakyMarker)}, '1');
+          console.log(' FAIL  packages/fake/flaky.test.js > describe > flaky test');
+          console.error('Error: Test timed out in 45000ms.');
+          process.exit(1);
+        }
+        console.log(' retry ran clean');
+        process.exit(0);
+      `);
+      const flakyGate = { n: 4, cmd: `node "${flakyScript}"`, what: 'selftest flaky gate' };
+      const flakyResult = await runSoloGateWithRetry(flakyGate, {});
+      if (!flakyResult.ok || !flakyResult.note || !flakyResult.note.includes('packages/fake/flaky.test.js')) {
+        console.error(`selftest FAIL: runSoloGateWithRetry() must accept a clean retry as a flake; got: ${JSON.stringify(flakyResult)}`);
+        process.exit(1);
+      }
+
+      const alwaysFailsScript = path.join(tmp, 'always-fails.mjs');
+      fs.writeFileSync(alwaysFailsScript, `
+        console.log(' FAIL  packages/fake/broken.test.js > describe > broken test');
+        process.exit(1);
+      `);
+      const alwaysFailsGate = { n: 4, cmd: `node "${alwaysFailsScript}"`, what: 'selftest always-fails gate' };
+      const alwaysFailsResult = await runSoloGateWithRetry(alwaysFailsGate, {});
+      if (alwaysFailsResult.ok) {
+        console.error('selftest FAIL: runSoloGateWithRetry() must NOT mask a failure that reproduces on retry');
+        process.exit(1);
+      }
+
+      const sentinel = path.join(tmp, 'unparseable-retried');
+      const unparseableScript = path.join(tmp, 'unparseable-fails.mjs');
+      fs.writeFileSync(unparseableScript, `
+        import { existsSync, writeFileSync } from 'node:fs';
+        const sentinel = ${JSON.stringify(sentinel)};
+        writeFileSync(sentinel, existsSync(sentinel) ? 'RETRIED' : 'FIRST-RUN');
+        console.error('Segmentation fault (core dumped)');
+        process.exit(139);
+      `);
+      const unparseableGate = { n: 4, cmd: `node "${unparseableScript}"`, what: 'selftest unparseable-crash gate' };
+      const unparseableResult = await runSoloGateWithRetry(unparseableGate, {});
+      if (unparseableResult.ok) {
+        console.error('selftest FAIL: an unparseable gate-4 failure must never be treated as passing');
+        process.exit(1);
+      }
+      if (fs.readFileSync(sentinel, 'utf8') !== 'FIRST-RUN') {
+        console.error('selftest FAIL: an unparseable failure (no FAIL lines) must fail closed — no retry');
+        process.exit(1);
+      }
+    }
+
+    // gh#2473 — Step 5.6's guard: unstagedTrackedLeftovers() must find a
+    // plain modified/deleted tracked file, unquote a C-quoted path
+    // (spaces), and report the NEW side of a rename/copy — all from a
+    // fixture porcelain string, independent of `--dry` and independent of
+    // any real git tree (the `--mode cut --dry` subprocess run below can
+    // only ever prove the code path executes and prints a fixed success
+    // string; it can't reach the `else` branch at all, since `sh()`'s dry
+    // short-circuit never runs `git status`). This exercises the exact
+    // logic Step 5.6 runs for real.
+    {
+      const porcelain = [
+        ' M packages/plugins/adia-ui-factory/README.md',
+        ' D packages/plugins/adia-ui-factory/hermes-mcp.yaml',
+        'M  packages/already/staged.json', // staged-only (X=M, Y=space) — NOT a leftover
+        '?? packages/new/untracked.json', // untracked — out of scope, NOT a leftover
+        ' M "packages/has space/quoted file.md"',
+        'RM packages/old-name.md -> packages/new-name.md', // renamed AND further worktree-modified (Y=M) — a leftover
+        'R  packages/clean-rename-old.md -> packages/clean-rename-new.md', // renamed, no further worktree change (Y=space) — NOT a leftover
+      ].join('\n');
+      const leftover = unstagedTrackedLeftovers(porcelain);
+      const want = [
+        'packages/plugins/adia-ui-factory/README.md',
+        'packages/plugins/adia-ui-factory/hermes-mcp.yaml',
+        'packages/has space/quoted file.md',
+        'packages/new-name.md',
+      ];
+      const gotJson = JSON.stringify(leftover);
+      const wantMissing = want.filter((w) => !leftover.includes(w));
+      const wantExtra = leftover.filter((l) => !want.includes(l));
+      if (wantMissing.length > 0 || wantExtra.length > 0 || leftover.length !== want.length) {
+        console.error(`selftest FAIL: unstagedTrackedLeftovers() expected ${JSON.stringify(want)}, got ${gotJson}`);
+        process.exit(1);
+      }
+      if (unstagedTrackedLeftovers('').length !== 0) {
+        console.error('selftest FAIL: unstagedTrackedLeftovers() must return [] on empty porcelain output (the clean-tree case Step 5.6 hits on every normal cut)');
+        process.exit(1);
+      }
+    }
+
     const commitFile = path.join(tmp, 'commit.txt');
     const notesFile = path.join(tmp, 'notes.md');
     fs.writeFileSync(commitFile, 'selftest fixture commit message\n');
@@ -1462,6 +1721,16 @@ function selftest() {
       'packages/plugins/adia-ui-factory/__init__.py',
       'packages/plugins/adia-ui-factory/hermes-mcp.yaml',
       'packages/plugins/adia-ui-factory/prompts/*.md',
+      // gh#2473 — Step 5's staging pathspec must carry the factory README's
+      // own prose echo of the generation-MCP pin (bump.mjs's A2UI_MCP_PIN
+      // README target), or it rides unstaged/uncommitted past the release
+      // commit the same way .mcp.json itself did before gh#1198.
+      'packages/plugins/adia-ui-factory/README.md',
+      // gh#2473 — Step 5.6's unstaged-tracked-files guard must actually run
+      // (as a no-op) on a clean --dry plan. Its real leftover-detection
+      // logic is unit-tested directly above via unstagedTrackedLeftovers();
+      // this marker only proves the --dry code path reaches its console.log.
+      "no unstaged tracked changes remain — Step 5's allowlist covered everything this cut touched",
     ];
     for (const marker of need) {
       if (!out.includes(marker)) {
@@ -1597,7 +1866,10 @@ function fileURLToPathCompat(url) {
 const topArgv = process.argv.slice(2);
 if (topArgv[0] === 'selftest') {
   rl.close();
-  selftest();
+  selftest().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
 } else {
   main().catch((e) => {
     // sh()/shQuiet() failures already printed the failing command + its

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

@@ -23,8 +23,8 @@ closable: { type: Boolean, default: true, reflect: true }
 | --- | --- |
 | `modal-ui[closable]` (default `true`) | `modal-ui[permanent]` (default `false`) |
 | `skeleton-ui[animate]` | `skeleton-ui[static]` |
-| `stream-ui[cursor]` | `stream-ui[hideCursor]` |
-| `chart-ui[average]` | `chart-ui[hideAverage]` |
+| `stream-ui[cursor]` | `stream-ui[noCursor]` |
+| `chart-ui[average]` | `chart-ui[noAverage]` |
 | `toggle-group-ui[multiple]` | `toggle-group-ui[single]` |
 | `swiper-ui[pause-on-hover]` | `swiper-ui[noPauseOnHover]` |
 

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

@@ -66,8 +66,8 @@ AdiaUI conventions require `default: false` on Boolean props in the standard sha
 | --- | --- | --- |
 | Modal can be dismissed | `closable` | `permanent` |
 | Skeleton animates | `animate` | `static` |
-| Stream shows blinking cursor | `cursor` | `hideCursor` |
-| Chart shows average line | `average` | `hideAverage` |
+| Stream shows blinking cursor | `cursor` | `noCursor` |
+| Chart shows average line | `average` | `noAverage` |
 | Toggle group allows multi-select | `multiple` | `single` |
 | Swiper pauses on hover | `pause-on-hover` | `noPauseOnHover` |
 
@@ -253,9 +253,22 @@ Reserve `error` for validation state (`[error]` on form inputs matches ARIA patt
 <toggle-group-ui single>...</toggle-group-ui>
 ```
 
+**[historical, 2026-08-31, ADR-0056 amendment]** `<toggle-group-ui>` /
+`<toggle-option-ui>` were cut outright in `0.8.43` (gh#1617), before the
+migration this ADR's Decision 2 anticipated ever ran — moot, not
+falsified. `segmented-ui`/`segment-ui` absorbed the role
+(`segmented.yaml`'s `multiple` prop description names the absorption
+directly, gh#1369/#1363 C1). The example above stays as written because it
+illustrates the Boolean-false naming rule against a real historical prop
+name, not because `<toggle-group-ui>` still exists — `segmented-ui`
+deliberately does NOT follow this same polarity (`[multiple]` is
+positive-polarity by design, matching `select-ui[multiple]`; there is no
+`segmented-ui[single]` opt-out), so it is not a drop-in replacement
+example for this rule.
+
 ## Selection-item state — a declared, reflected `selected` prop, never a private `data-*` stamp
 
-A **selection-item primitive** (one selectable option inside a selection-group parent — `segment-ui` in `segmented-ui`, `toggle-option-ui` in `toggle-group-ui`) exposes its current state as a declared, reflected `selected: Boolean` prop, documented as parent-managed, and styled via `[selected]`:
+A **selection-item primitive** (one selectable option inside a selection-group parent — `segment-ui` in `segmented-ui`; historically also `toggle-option-ui` in `toggle-group-ui`, cut in `0.8.43`/gh#1617 — see the dated note below) exposes its current state as a declared, reflected `selected: Boolean` prop, documented as parent-managed, and styled via `[selected]`:
 
 ```javascript
 // child — the declared API surface
@@ -286,7 +299,7 @@ Rules:
 - **The parent's `value` is the single source of truth**; the parent writes `selected` on its children (`segmented.class.js:146,149` sets/removes the attribute; `toggle-group.class.js:104-111` assigns `opt.selected`). Authors and generated markup drive the group's `value`, never `[selected]` on a child (`toggle-group.yaml`'s rules block says so in so many words).
 - **No private `data-*` stamp for API-conceptual state.** `data-selected` hides the state from the yaml SoT, the catalog, and generative authoring — a consumer or the A2UI grammar cannot express "this option is selected" against a stamp that no schema declares. `toggle-group-ui` used to stamp `data-selected` + style `:scope[data-selected]`; it converged onto `segment-ui`'s mechanism (`toggle-option.yaml:38-46`, `toggle-group.css:14`, `toggle-group.test.js:64` asserts the stamp is gone).
 - **Parent-stamped ARIA stays as-is — ARIA is wiring, not API.** `segment-ui` derives `aria-checked` from `selected` (`segment.class.js:42`); `toggle-option-ui` derives `aria-pressed` (`toggle-group.class.js:65`). The reflected prop is the API; the ARIA attribute follows it.
-- **Reference implementation:** `segment-ui` (`segment.yaml:32-36`, `segment.css:7`); `toggle-option-ui` is the converged second instance. A new selection-item primitive copies this shape — extending one of the two by analogy is what produced the divergence in the first place (gh#1303).
+- **Reference implementation:** `segment-ui` (`segment.yaml:32-36`, `segment.css:7`) is the current, live reference. **[historical, 2026-08-31, ADR-0056 amendment]** `toggle-option-ui`/`toggle-group-ui` were the converged second instance at ratification time, but both were cut outright in `0.8.43` (gh#1617), before any migration ran — `segmented-ui`/`segment-ui` absorbed the role. A new selection-item primitive copies `segment-ui`'s shape directly; there is no second live instance to extend by analogy anymore (the divergence gh#1303 describes was between `segment-ui` and the now-deleted `toggle-option-ui`).
 
 Migration note: removing `data-selected` was a breaking change for external CSS that targeted it, so it shipped in two halves — the additive `selected` prop in `0.8.39`, the stamp removal on the `0.8.40` breaking wave with a migration-guide entry (`packages/web-components/CHANGELOG.md`; the ADR text names the wave `0.9.0` — it shipped as `0.8.40`).
 

package/skills/primitive-authoring/references/authoring-cycle.md

@@ -31,7 +31,7 @@ These rules are the distilled lessons from a 5-iteration audit. Each one corresp
 
 ### API / Attributes
 
-1. **Boolean defaults are `false`.** If the expected default is "on," rename: `closable` → `permanent`, `animate` → `static`, `cursor` → `hideCursor`, `average` → `hideAverage`, `pause-on-hover` → `noPauseOnHover`.
+1. **Boolean defaults are `false`.** If the expected default is "on," rename: `closable` → `permanent`, `animate` → `static`, `cursor` → `noCursor`, `average` → `noAverage`, `pause-on-hover` → `noPauseOnHover`. `no-*` is the canonical negation prefix (ADR-0063 decision 1) — a new rename lands on `no-*` directly, never `hide-*`.
 
 2. **No magic-value sentinels in numeric props.** Indeterminate = `null`, not `-1`. Consumers branch on `value == null`, which is explicit.
 

package/skills/primitive-authoring/references/code-style.md

@@ -239,7 +239,7 @@ Every Boolean prop on a component must default to `false`. If the expected defau
 | --------------------------------- | ------------------------------ |
 | `<drawer-ui permanent>`           | `<drawer-ui closable>`         |
 | `<chart-ui static>`               | `<chart-ui animate>`           |
-| `<cursor-ui hide-cursor>`         | `<cursor-ui cursor>`           |
+| `<cursor-ui no-cursor>`           | `<cursor-ui cursor>`           |
 | `<carousel-ui no-pause-on-hover>` | `<carousel-ui pause-on-hover>` |
 
 Default behavior is the absent attribute. Attributes exist to opt OUT or carry a value — never to opt INTO the expected default.

package/skills/primitive-authoring/references/form-control-sizing.md

@@ -20,10 +20,24 @@ posture flip.
 
 ## Where legibility floors live
 
-A `--*-min-width: 20ch`-class floor (the gh#781/gh#1633 pattern on
-`input-ui`/`select-ui`/`combobox-ui`) belongs on `:scope[inline]` only, never
-on the plain `:scope`. In the fill state the container owns the width, all
-the way down — no exception, no re-added floor. Two floor classes are
+**[retired 2026-08-28, ADR-0095]** The `--*-min-width: 20ch`-class floor
+described below is no longer permitted anywhere, including on
+`:scope[inline]`. A primitive never floors its own inline-size independent
+of its own geometry — the only permitted floor is
+`min-inline-size: var(--<component>-height)` (a square minimum). ADR-0095
+Decision Class 1 removes the 20ch-class field-width floor for
+`input-ui`/`select-ui`/`combobox-ui` (plus `--input-label-min-width`,
+`--date-range-picker-trigger-min-width`) and replaces it with the square
+floor, generalizing the `button-ui` keep-square pattern already named below
+to the field-width components.
+
+*(Historical, pre-ADR-0095 rule — superseded by the retirement above, kept
+only for context on what the old convention was.)* A
+`--*-min-width: 20ch`-class floor (the gh#781/gh#1633 pattern on
+`input-ui`/`select-ui`/`combobox-ui`) used to belong on `:scope[inline]`
+only, never on the plain `:scope`. In the fill state the container owns the
+width, all the way down — no exception, no re-added floor. Two floor
+classes are
 explicitly NOT sizing-posture floors and stay in both states: inner
 `min-width: 0` flex unclampers (the ellipsis-reset machinery) and
 `min-width: var(--*-height)` squareness floors (`button-ui`'s keep-square
@@ -35,9 +49,10 @@ posture, and also stay in both states.
 
 - Plain `:scope` (no `[inline]`): block-level, `width: auto` in block flow,
   `width: 100%` in flex/grid parents. No `min-width` legibility floor here.
-- `:scope[inline]`: inline-level display, shrink-wrap sizing, and — only if
-  the component is a floor-carrier (input/select/combobox-class) — the
-  `--*-min-width: 20ch`-class floor moves here.
+- `:scope[inline]`: inline-level display, shrink-wrap sizing. Per ADR-0095,
+  no `--*-min-width: 20ch`-class floor moves here any more — a floor-carrier
+  component uses the square minimum (`min-inline-size:
+  var(--<component>-height)`) instead, in both states.
 - A component that wants to own its line but still hug has no attribute for
   that state (ADR-0077 Decision item 6, accepted consequence) — tell the
   consumer to use explicit sizing (`width: fit-content` or an explicit

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

@@ -154,6 +154,11 @@ ADR-0053/0054 don't cover. Any new attribute follows these:
   opt-out. `chart-legend[static]` retires to `[interactive]` (inverted
   default). Applies to single-purpose toggles only — `noodles`'s
   `editable`/`readonly` pair is two orthogonal booleans and stays.
+- **One spelling survives a documented alias; the alias retires
+  everywhere it appeared** — never a deprecation window. `alert[dismissible]`
+  retired (`[closable]` survives, the implemented prop); `card`'s style
+  enum's duplicate `outline` member retired (`outlined` survives, the
+  ADR-0044 style-axis token).
 - **Two sanctioned multi-value encodings, never a hand-rolled delimited
   string:** (a) `multiple` boolean + a structured option model (`select`'s
   `options`/`<option>` shape); (b) a native array-typed JS property,

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

@@ -114,13 +114,93 @@ stricter than the source is a defect, not documentation.
 
 Pipeline: `components.mjs` validates the shape per-yaml, cross-checks every
 referenced name against the full catalog on a full build, and forwards the
-lists onto `x-adiaui` → `catalog-a2ui_0_9.json`.
+lists onto `x-adiaui` → `catalog-a2ui_1_0.json`.
 `scripts/build/derive-genui-catalog.mjs` then translates them into the
-canonical v1.0 key space (yaml `Segmented` → catalog `SegmentedControl`) on
-`base.json`/`adia-pack.json`, where the vendored `@genui/core` validator
-enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier yamls
-(web-modules) carry constraints as dialect-catalog metadata only — modules
-have no v1.0 sidecar.
+canonical v1.0 key space (yaml `Segmented` → catalog `Segmented`, canonical
+per gh#2116) across the five opt-out-scoped catalogs (`adia.core.json`,
+`adia.navigation.json`, `adia.data.json`, `adia.agent.json`,
+`adia.shells.json`, gh#2211/ADR-0093), where the vendored `@genui/core`
+validator enforces them (`UNALLOWED_PARENT`/`UNALLOWED_CHILD`). Module-tier
+yamls (web-modules) now carry a v1.0 sidecar too and land in `adia.shells`.
+
+---
+
+## `examples:` field — a2ui example ids (semantic-id grammar, gh#2492)
+
+Each `examples[].a2ui` block is a JSON array of component nodes (the same
+`updateComponents.components[]` shape `.claude/docs/specs/a2ui-editor.md`
+documents for the editor's live doc store). That spec's line "other
+component ids are free-form (convention: `c-{n}` for generated ids)" governs
+**editor-generated** ids only — ids the editor mints when a human drags a
+component onto the canvas. It was never a license for **authored** ids
+inside a component's own yaml examples, and treating it as one produced a
+corpus-wide drift toward cryptic, positional ids (`q`, `k1`, `k1v`, `hdr`)
+that don't describe what they are once an example has more than one or two
+nodes — reported in gh#2492 against `blockquote.yaml`, `badge.yaml`,
+`aside.yaml`, `alert.yaml`, and `anchor-bar.yaml` (the last four
+corroborating it as a corpus-wide pattern, not a one-off).
+
+**Grammar — authored `a2ui.examples[]` ids only:**
+
+- **Kebab-case, role-descriptive.** The id names what the node IS or DOES in
+  the example, not its position in the array. `quote-body`, not `q` or
+  `node-2`.
+- **Unique per example.** Scoped to one `examples[]` entry, not the whole
+  yaml — reusing `header` across two examples in the same file is fine;
+  reusing an id twice inside one example is not (the renderer's flat
+  `children: string[]` lookup would collide).
+- **Compound ids read parent-then-role** for a node that belongs to a named
+  cluster: `kpi-revenue`, `kpi-revenue-value`, `kpi-revenue-label` — not
+  `k1`, `k1v`, `k1l`. This is what lets a reader studying the copy-paste-able
+  example understand the structure from the ids alone, without cross-
+  referencing the tree.
+- **Exception — the root/wrapper id may stay short when the example has
+  exactly one top-level container and the short id is still a real word**,
+  e.g. `card`, `row`, `panel`, as long as every id it contains follows the
+  grammar. A single generic wrapper doesn't need `card-wrapper-root`; a
+  wrapper's *children* still do.
+- Ids are internal wiring keys (`children: string[]` references, rendered
+  only as `data-a2ui-id`) — never user-visible copy — but they double as the
+  readable structure of the example a consumer studies, which is the whole
+  reason this grammar exists.
+
+**Before / after** (`blockquote.yaml`'s `default` example, gh#2492's
+reported repro):
+
+```jsonc
+// before
+[
+  { "id": "q", "component": "Blockquote", "cite": "…", "children": ["body"] },
+  { "id": "body", "component": "Text", "textContent": "Stay hungry. Stay foolish." }
+]
+
+// after
+[
+  { "id": "quote", "component": "Blockquote", "cite": "…", "children": ["quote-body"] },
+  { "id": "quote-body", "component": "Text", "textContent": "Stay hungry. Stay foolish." }
+]
+```
+
+```jsonc
+// before (badge.yaml chart-dashboard, positional style mixed with semantic
+// ids in the SAME example — k1/k1h/k1v alongside header-row/dash-title)
+{ "id": "k1", "component": "Card", "children": ["k1h", "k1v"] }
+
+// after
+{ "id": "kpi-revenue", "component": "Card", "children": ["kpi-revenue-label", "kpi-revenue-value"] }
+```
+
+**Enforcement**: `scripts/verify/check-example-ids.mjs` walks every yaml's
+`examples[].a2ui` nodes and reports ids that fail the grammar (a bare
+1-2 char id, a `^[a-z]\d+` positional pattern like `k1`/`c2`, non-kebab-case,
+or a within-example duplicate). gh#2492 Phase 2 swept the corpus-wide 526
+violations across 48 files to zero and flipped the gate to `npm run
+check:example-ids:strict` in the `npm run check` chain (non-zero exit on
+any violation) — a new example that violates the grammar now fails the
+build immediately, not just on a future sweep. Known gap: the checker's
+positional-pattern regex catches `letter+digits` (`k1`, `c2`) but not a
+`letter-digit-letter-digit` chain like `g1i1` — out of scope for this
+sweep (nothing flagged it), left for a future refinement.
 
 ---
 
@@ -235,7 +315,7 @@ manifest format. ADR-0066 refines it three ways:
 
 - **`origin: primitive | module` on every L0 entry** — both YAML source
   roots (web-components primitives AND web-modules composites) compile into
-  the same `catalog-a2ui_0_9.json` through one shared contract;
+  the same `catalog-a2ui_1_0.json` through one shared contract;
   `derive-catalog-tiers.mjs` stamps which root an entry came from onto
   `tier-index.json`. A module is legitimately a member of TWO rungs at two
   grains: its component API (props/events/slots) is L0, its assembled shell
@@ -283,6 +363,31 @@ props:
       - ghost
 ```
 
+### Synthesized universal props — `slot` / `hidden` / `ariaLive` / `traits`
+
+`deriveProps()` (`scripts/build/derive-genui-catalog.mjs`) prepends three
+props to every component's generated catalog schema before it ever reads a
+yaml's own `props:` block: `slot: {type: string}`, `hidden: {type:
+boolean}`, `ariaLive: {type: string}` (REQ-013 accessibility pair, gh#1353).
+**No yaml SoT declares any of these** — they're synthesized, not authored,
+and a sidecar that ever DOES declare one of these keys itself simply
+overwrites the synthesized definition.
+
+**Decided but not yet implemented:** ADR-0097
+(`docs/ops/adr/adr-0097-traits-as-a2ui-synthesized-universal-prop.md`,
+ratified via PR #2524) rules that `traits: {type: string}` becomes a fourth
+member of this synthesized set, carrying the same space-separated grammar
+as the existing HTML `[traits="…"]` declarative attribute
+(`.claude/docs/specs/traits.md`, "Method 3" — `"ripple confetti-burst"`,
+not a JSON array) — making `traits` legal on every component's A2UI wire
+schema with no renderer change, and, once wired, checked by
+`catalog-validator.js` against the live trait registry
+(`packages/web-components/traits/_catalog.json`) with a **hard FAIL on an
+unknown trait name** (the same rejection behavior the raw HTML mechanism
+already has). As of this writing `deriveProps()` still synthesizes only the
+three props above and `catalog-validator.js` has no trait-name check —
+gh#2513 tracks the build.
+
 ### `required: true` field
 
 **When to use**: only for props where omitting them makes the component meaningless or inaccessible.
@@ -427,7 +532,7 @@ The build:
 **Downstream of the sidecars — two more derived artifacts (gh#970's release-PR stop):**
 
 ```bash
-node scripts/build/derive-genui-catalog.mjs   # genui base.json + adia-pack.json derive FROM the sidecars
+node scripts/build/derive-genui-catalog.mjs   # genui's five opt-out-scoped catalogs derive FROM the sidecars
 npm run check:genui-catalog                    # the drift gate that fails PR CI if you skip the above
 ```