@adia-ai/adia-ui-forge 0.8.41 → 0.8.43

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.41",
-  "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-factory (the consumer/app-author plugin).",
+  "version": "0.8.43",
+  "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",
     "email": "kim.granlund@adia.ai"

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.43] — 2026-08-18
+
+### Changed
+- Knowledge packs harvested for ADR-0061..0074: surface-lifecycle reference (a2ui-maintenance), site-package-registry playbook, attribute-grammar/role-class/tier-model sections, disabled-state token convention (gh#1564, #1609, #1625).
+- primitive-authoring/gen-ui-review references migrated off cut attributes (`hide-*` → `no-*`) so agent-authored demos stop reintroducing them (gh#1617, #1626).
+- token-selection references regenerated for the `--a-ui-bg-disabled` container-low retarget (gh#1596, #1599).
+
+### Maintenance
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`skills/` touched in this release window** (5 file(s), e.g. `references/corpus-html-patterns.md`) — carried by the entries above.
+
+## [0.8.42] — 2026-08-17
+
+### Maintenance
+- Knowledge packs harvest the ADR-0061..0070 ratifications (PR #1564: gen-ui-wiring + wave-coordination corpora); rename-wave W2 doc migration (PR #1567).
+- **`.claude-plugin/plugin.json` version bump** — moves in lockstep with package.json (the `/plugin update` cache key).
+- **`skills/` touched in this release window** (7 file(s), e.g. `a2ui-maintenance/SKILL.md`) — carried by the entries above.
+
 ## [0.8.41] — 2026-08-17
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.41",
+  "version": "0.8.43",
   "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-factory (the consumer/app-author plugin).",
   "keywords": [
     "adia-ui",

package/skills/a2ui-maintenance/SKILL.md

@@ -41,6 +41,22 @@ surface `catalogId` → error, no registry default). The producer's
 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).
+
 ## Route by task shape
 
 | Task shape | Load |
@@ -55,6 +71,7 @@ envelopes from this skill's surfaces.
 | Add or change an MCP tool | [mcp-tool-reference](references/mcp-tool-reference.md) |
 | Tune the anti-pattern catalogue | [anti-patterns](references/anti-patterns.md) |
 | A component's 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 replace bracket | [surface-lifecycle](references/surface-lifecycle.md) (ADR-0061) |
 
 Unmatched work defaults to pipeline-overview and re-classifies from there.
 

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

@@ -0,0 +1,73 @@
+# Surface lifecycle — the runtime pending/stale contract (ADR-0061)
+
+The renderer runtime (`packages/gen-ui/a2ui/`) owns a per-surface lifecycle
+state machine, ratified by ADR-0061
+(`docs/ops/adr/adr-0061-surface-lifecycle-pending-stale.md`; requirements and
+build order in `docs/ops/spec/spec-a2ui-surface-lifecycle.md`). Load this file
+when a change touches surface regeneration, `<a2ui-root>`'s `doc` setter,
+pending/stale rendering, or a host's update bracketing.
+
+## The state machine
+
+```text
+empty → pending-first → live → pending-stale → live
+              └→ error-empty         └→ error-stale
+                  (both error-* heal on the next successful commit)
+```
+
+- **Pending is per-surface, never global.** Each renderer surface record
+  carries its own machine; one surface regenerating never dims another.
+- **Latest-generation-wins arbitration.** When two update brackets race on
+  one surface, the newest generation's commit wins; a superseded bracket's
+  messages are discarded, not interleaved.
+- **Stale content stays visible.** In `pending-stale` and `error-stale` the
+  previous answer keeps rendering — the blank-flash reset+replay shape is
+  what this contract retired. Error state heals: the next successful commit
+  clears `error-*`.
+
+## The host API
+
+Four public runtime methods drive the machine — `beginSurfaceUpdate` /
+`applyTo` / `commitSurfaceUpdate` / `abortSurfaceUpdate`. Messages arriving
+inside a bracket buffer and apply atomically at commit. A `replace`-mode
+commit sweeps components the new answer no longer declares — the ONLY place
+removal semantics exist; outside a bracket, `updateComponents` upserts
+exactly as before, so unbracketed streams and hosts are behavior-identical
+to the pre-lifecycle runtime (strictly additive, ADR-0061 Decision 4).
+`<a2ui-root>`'s `doc` setter routes through this replace bracket
+(`replaceDoc`) rather than reset+replay — a deliberate, ratified behavior
+change for doc-setting hosts (ADR-0061 OD-2).
+
+## The DOM contract
+
+Staleness is exposed as one attribute plus three events, never styling:
+
+- **`data-a2ui-lifecycle`** — a single enum attribute on the surface root
+  reflecting the current state. This is the `data-a2ui-*` prefix's FIRST
+  ratification (the pre-existing `data-a2ui-surface` stamp was accidental,
+  now ratified alongside it) — the runtime-owned `data-*` tier, sibling to
+  ADR-0060's trait tier.
+- **Three bubbling CustomEvents** mark the transitions.
+- Hosts and primitives style off the attribute with semantic tokens: stale
+  content dims; skeletons (the existing `skeleton` primitive) appear only in
+  `pending-first`. `@adia-ai/a2ui` ships state, never styling, and stays
+  zero-dependency.
+
+## Layer boundary (ADR-0059)
+
+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.
+
+## Interlock worth knowing
+
+The v1.0 conformance program's duplicate-`surfaceId` error (REQ-002)
+sequences AFTER this API — the silent `createSurface` no-op it removes was
+previously the only wire-visible re-target path, and the lifecycle bracket
+is its sanctioned replacement.

package/skills/demo-audit/references/admin-shell-anatomy.md

@@ -21,7 +21,7 @@ the live admin-dashboard example.
    a bare `<nav-ui>` direct child overflows long lists
 5. Sidebar `<admin-statusbar slot="footer">` with `<select-ui avatar="…">`
    (user menu) — ★ commonly missing
-6. Sidebar `<div data-resize></div>` — REQUIRED when `resizable` is on
+6. Sidebar `<div data-sidebar-resize></div>` — REQUIRED when `resizable` is on
 7. `<admin-content>` inner `<admin-topbar>` containing
    `<button-ui data-sidebar-toggle="leading" icon="sidebar">` +
    `<breadcrumb-ui>` + `<span data-spacer>` + `<div data-actions>` —

package/skills/gen-ui-review/references/corpus-html-patterns.md

@@ -139,12 +139,12 @@ col-ui midpoint, landing it beside the description instead of the title.
 **WORKS** — the renderer JSON-parses string JS_PROPS before assignment:
 
 ```html
-<chart-ui type="bar" x="month" y="revenue" hide-values
+<chart-ui type="bar" x="month" y="revenue" no-values
   data='[{"month":"Jan","revenue":3200},{"month":"Feb","revenue":4100}]'>
 </chart-ui>
 ```
 
-Include 4–6 data points; `hide-values` when the canvas is too narrow for labels.
+Include 4–6 data points; `no-values` when the canvas is too narrow for labels.
 
 ### image-ui: data URIs, never external URLs
 
@@ -153,7 +153,7 @@ rectangle. Use either a sparkline placeholder (renders immediately, no network):
 
 ```html
 <section bleed>
-  <chart-ui type="sparkline" x="t" y="v" color="accent" hide-values
+  <chart-ui type="sparkline" x="t" y="v" color="accent" no-values
     data='[{"t":1,"v":60},{"t":2,"v":80},{"t":3,"v":45}]'
     style="height:160px"></chart-ui>
 </section>

package/skills/gen-ui-review/scripts/gen-review-decompose.mjs

@@ -148,7 +148,7 @@ const TAG_TO_COMPONENT = {
   'chat-input-ui':   'ChatInput',
   'chat-thread-ui':  'ChatThread',
   'color-input-ui':  'ColorInput',
-  'color-picker-ui': 'ColorPicker',
+  'color-area-ui':   'ColorArea',
   'command-ui':      'Command',
   'context-menu-ui': 'ContextMenu',
   'date-range-picker-ui': 'DateRangePicker',

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

@@ -66,7 +66,7 @@ Treat this as the default lookup table. **If your affordance maps to a row here,
 | Modal / drawer / toast | `modal-ui` / `drawer-ui` / `toast-ui` |
 | Switch / checkbox / radio / segmented / toggle group | `switch-ui` / `check-ui` / `radio-ui` / `segmented-ui` / `toggle-group-ui` |
 | Avatar / avatar group | `avatar-ui` / `avatar-group-ui` |
-| Color / calendar / OTP picker | `color-picker-ui` / `calendar-picker-ui` / `otp-input-ui` |
+| Color / calendar / OTP picker | `color-area-ui` / `calendar-picker-ui` / `otp-input-ui` |
 | Stepper / timeline / progress / progress-row | `stepper-ui` / `timeline-ui` / `progress-ui` / `progress-row-ui` |
 | Card with header / section / footer | `card-ui` (+ slot children) — don't roll a "panel" |
 | Description-list (key/value) | `description-list-ui` |

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

@@ -90,9 +90,9 @@ chart's Y-axis labels clipped under a bled card's corner.
 ```css
 /* Guide/value/legend safety inset (gh#1095) — [bleed]'s zero-inset is
    only collision-free for the bare-marks case: a sparkline, or any other
-   chart-ui type with BOTH [hide-grid] and [hide-values] set. */
-& > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([hide-grid])),
-& > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([hide-values])),
+   chart-ui type with BOTH [no-grid] and [no-values] set. */
+& > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([no-grid])),
+& > section[bleed]:has(> chart-ui:not([type="sparkline"]):not([no-values])),
 & > section[bleed]:has(> chart-legend-ui) {
   margin: var(--card-inset);
   padding: 0;
@@ -105,7 +105,7 @@ relying on every author to remember. `#renderSparkline()` is the ONLY
 renderer that never emits axis ticks, gridlines, value text, or a legend
 (`chart.class.js`'s sparkline branch) — it's the sole type where genuine
 edge-to-edge bleed is collision-free with no attribute needed. Every other
-type needs BOTH `[hide-grid]` and `[hide-values]` set to opt into true
+type needs BOTH `[no-grid]` and `[no-values]` set to opt into true
 bleed; short of that, the safety inset applies and the chart renders inset
 like a normal card section — expected, not a bug.
 
@@ -234,29 +234,34 @@ correctness rather than just aesthetics), set `shape-rendering: crispEdges`
 explicitly** — the browser default (`auto`, effectively anti-aliased) is
 correct for everything else and should stay the default.
 
-## 8. Attribute-shadowing on SVG-adjacent primitives (ADR-0053/0054)
+## 8. Attribute-shadowing on SVG-adjacent primitives (ADR-0053/0054/0070)
 
-Two of the pre-existing global-attribute-grammar collisions gh#1335 surfaced
-are specifically SVG-rendered primitives, and both cite the SVG-specific
-reasoning for their proposed resolution rather than the generic
-rename/converge path:
+Two of the global-attribute-grammar collisions gh#1335 surfaced are
+specifically SVG-rendered primitives; both exemptions are **GRANTED**
+(ADR-0070, ratified 2026-08-17), closing the last 2 of gh#1335's 17 and
+emptying `check-attribute-shadowing.mjs`'s `KNOWN_FINDINGS` — the gate now
+enforces via `attribute-api-system.md`'s ratified §11 table alone:
 
 - **`qr-code-ui[color]`** — a free-form CSS color string (drives the raw
   `fill` baked into the generated matrix SVG, §5 above), structurally
-  identical to the already-ratified `swatch-ui`/`noodles-ui[color]` §11
-  exemptions ("the component's entire subject is a color") — proposed for
-  the same exemption rather than a rename.
-- **`icon-ui[weight]`** — Phosphor's icon-rendering weight vocabulary
+  identical to the ratified `swatch-ui`/`noodles-ui[color]` §11 exemptions
+  ("the component's entire subject is a color"). The exemption covers the
+  free-form value space AND the hardcoded `#000000` scanability fallback
+  (deliberately never theme-derived — light-on-dark won't scan), plus its
+  contract pairing with `[background]`.
+- **`icon-ui[weight]`** — Phosphor's own glyph-variant vocabulary
   (`thin/light/regular/bold/fill/duotone`, selecting which pre-rendered SVG
-  asset variant `getIcon()` loads) is a DIFFERENT CONCEPT from CSS
-  `font-weight` (`thin/light/normal/medium/semibold/bold`) despite the
-  shared attribute name — gh#1335 names it "the strongest candidate for a
-  ratified §11 exemption rather than a rename," the same reasoning as
-  `swatch-ui[color]`.
-
-Neither is resolved yet (both remain in `check-attribute-shadowing.mjs`'s
-`KNOWN_FINDINGS` list per gh#1335) — cite this section, not a fresh
-investigation, if either surfaces again in a yaml audit.
+  set `getIcon()` loads) is a DIFFERENT CONCEPT from CSS `font-weight`
+  despite the shared name; the global utility's `font-weight` is inert on
+  the inline SVG, so the collision has no cascade effect.
+
+Known residual (documented in the §11 justification, accepted not fixed):
+global-only `weight` values (`normal|medium|semibold`) select no Phosphor
+set and fall back to `regular`; a semantic-enum value on `qr-code-ui[color]`
+(`color="danger"`) passes to the SVG fill verbatim, unresolved through
+tokens. Cite this section — ADR-0070 — not a fresh investigation, if either
+attribute surfaces again in a yaml audit; the next colliding
+`color`/`weight` on any OTHER component still needs its own ADR.
 
 ## When to load this file
 

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

@@ -138,7 +138,52 @@ mechanics; never work from this summary alone):
   the global name always means the global thing. Before minting any attribute
   in a component yaml, check it against the spec's attribute inventory; the
   only sanctioned collisions live in the spec's §11 Global-Attribute Exemption
-  List (first entries: `swatch-ui[color]` / `noodles-ui[color]`, ADR-0054).
+  List (first entries: `swatch-ui[color]` / `noodles-ui[color]`, ADR-0054;
+  granted since: `qr-code-ui[color]` / `icon-ui[weight]`, ADR-0070).
+
+Beyond the global grammar, ADR-0063
+(`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies six
+CROSS-SIBLING conventions for component-local attribute naming — the axis
+ADR-0053/0054 don't cover. Any new attribute follows these:
+
+- **`no-*` is the canonical negation prefix** — `hide-*` retires
+  (`chart[hideAverage|hideGrid|hideValues]` → `no*`, `stream[hide-cursor]`
+  → `[no-cursor]`).
+- **Interactivity is opt-in by a positively-named boolean, default `false`**
+  (the `stepper-item[interactive]` / `swatch[selectable]` shape) — never
+  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.
+- **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,
+  JSON-serialized for attribute/form participation (`tags-input`'s
+  `.value`). One explicit, operator-ratified EXCEPTION for existing
+  components (recorded on gh#1563, 2026-08-17): `segmented-ui[multiple]`'s
+  comma-separated value IS accepted as the sanctioned multiple+options
+  encoding, and toggle-group's comma-string resolves under that same ruling
+  rather than being re-ticketed. This is a ruling on those two existing
+  components, not a loophole — a NEW component's multi-value attribute still
+  uses form (a) or (b) above, never a delimited string, unless a separate
+  ruling says otherwise.
+- **Cross-sibling naming convergence:** `pane[side]` → `pane[edge]`
+  (drawer keeps physical `side`); `menu-item[subtitle]` →
+  `menu-item[description]` (the ~20-component majority word); `placement`
+  ratified as-is for anchored popovers. Documented exception:
+  `input[maxlength]` — a primitive wrapping a genuine native `<input>`
+  keeps the native attribute's exact casing (ADR-0025/0055 conformance);
+  new non-native length constraints use the framework's
+  camelCase-property/kebab-attribute pair.
+- **`completed` is the stage-terminal word** for a `status` lifecycle enum
+  (`agent-reasoning[status]`'s `done` converges).
+- **`-picker` is reserved for the outer trigger+popover form-associated
+  composite** — never the inline substrate it composes. `color-picker-ui`
+  (the inline substrate) renames to `color-area-ui`.
+
+The renames above have LANDED: dual-read compat shims shipped via gh#1563,
+and the breaking cut removed the old names in 0.8.43 (gh#1617). The new
+spellings are the sole ones — a yaml or demo still showing an old name is
+stale and should be fixed.
 
 ## When to update this reference
 

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

@@ -177,6 +177,79 @@ have no v1.0 sidecar.
 
 ---
 
+## Semantic color-family axis — two role-classes, two names (ADR-0044, ADR-0064)
+
+Every component carries at most one STYLE axis and one FAMILY axis (the
+semantic color family: `default | info | success | warning | danger`,
+`+primary` where the role-class already carries brand emphasis), and every
+enum value belongs to exactly one axis. The family axis's ATTRIBUTE NAME is
+decided by role-class — never one universal name (a same-name meaning-flip
+is a silent-failure migration and poisons the trained corpus, per ADR-0044
+LLD §3):
+
+- **Role-class A — `variant` is unclaimed:** the family axis is named
+  `variant`. Badge/tag's ratified shape (ADR-0044), plus `rating-ui` and the
+  `variant`-only siblings (inline-message, feed-item, empty-state, menu-item,
+  progress-row).
+- **Role-class B — an existing identity/style axis already claims the
+  selector slot:** the family axis is named `color`. Button's shape
+  (`variant`=style, `color`=family), extended by ADR-0064 to `text-ui`
+  (`variant`=typography role), `chart-ui`/`heatmap-ui` (`type`=kind),
+  `icon-ui` (`weight`=glyph style), `spinner-ui` (`variant`=animation), and
+  `toggle-scheme-ui`. Renames owed by this ruling (follow-on build, gh#1376
+  — not yet landed): `icon-ui[tone]` → `[color]`, `heatmap-ui[colorScheme]`
+  → `[color]`, `spinner-ui[tone]` → `[color]`.
+
+`accent` is RETIRED from the family enum everywhere — ADR-0044 removed it
+from badge/tag/button; ADR-0064 removes it from the seven stragglers
+(text, chart, icon, heatmap, rating, spinner, toggle-scheme) with no
+replacement value. Never mint `accent` in a new enum.
+
+Two ratified non-family exceptions — the name without the semantics:
+
+- `swatch-ui[color]` / `noodles-ui[color]` — an arbitrary CSS color string,
+  not a semantic enum (ADR-0054 §11 exemption, unchanged).
+- `spinner-ui[color]` (post-rename) — a closed contrast-mode enum
+  (`current | subtle | inverse`), NOT the family vocabulary; never assume it
+  accepts `info`/`success`/`warning`/`danger` by analogy.
+
+---
+
+## Catalog tiers — L0–L4, `origin`, and the promotion rule (ADR-0050, ADR-0066)
+
+ADR-0050's L0–L4 ladder is the ONLY tier grammar — never mint a second
+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;
+  `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
+  composition is L3 — ruled correct, not a modeling defect.
+- **The promotion rule, stated once:** patterns/zettel compositions are the
+  SOLE promotion source, and they enter the ladder at exactly one point —
+  pattern → L1 widget, through `curate-l1-widgets.mjs`'s gates (which writes
+  only `l1-widgets.json`). The higher rungs (L1 → L2 → L3 → L4) are AUTHORED
+  edges — hand-written `tiers/l*-*.json` manifests whose `composes` reference
+  the rung below, reserved/unblocked per ADR-0050's own phasing; a module's
+  L3 membership comes from an authored L3 manifest, never from its yaml
+  (which contributes only the L0 entry + `origin`). There is no
+  patterns↔module edge, primitives and modules never "promote" into each
+  other, and nothing promotes automatically or in reverse — curation is the
+  one-way valve (ADR-0050: "corpus derives from catalogs, never the
+  reverse").
+- **The two pattern-facing outputs stay separate by design:**
+  `site/patterns-index.json` / `pattern-index.md` are a generated,
+  developer-facing index over the FULL pattern/template census, intentionally
+  independent of the L0–L4 machine-validated schema — a different audience,
+  never a convergence gap to "fix".
+
+(`status:` above is orthogonal to the tier ladder — tier = what an entry is
+composed of; status = how much to trust its contract today.)
+
+---
+
 ## `props:` field — prop schemas
 
 Each prop is a top-level key inside `props:`. The full prop schema:
@@ -266,7 +339,7 @@ string-list schema is the exact silent-mismatch shape.
 | --- | --- | --- |
 | `[data-col]` | `display: flex; flex-direction: column; gap: var(--page-grid-gap)` | column layout helper |
 | `[data-row]` | `display: flex; align-items: center; gap: var(--page-grid-gap)` | row layout helper |
-| `[data-grid]` | `display: grid; grid-template-columns: 1fr 1fr` (or `1fr 1fr 1fr` for `data-grid="3"`) | 2- or 3-col grid helper |
+| `[data-layout-grid]` | `display: grid; grid-template-columns: 1fr 1fr` (or `1fr 1fr 1fr` for `data-layout-grid="3"`) | 2- or 3-col grid helper |
 | `[data-actions]` | `display: flex; align-items: center; gap: var(--page-actions-gap)` | action button cluster |
 | `[data-spacer]` | `flex: 1` | flex spacer for pushing content to edges |
 

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

@@ -139,10 +139,18 @@ itself is unavailable.
    - **`build:site` copies packages but does NOT rebuild their dist bundles** — after
      component `.css`/`.js` source changes, rebuild first (`npm run build -w
      @adia-ai/llm`, then `npm run build:bundles`) or the deployed bundles are stale.
-   - **`scripts/build/site.mjs` is per-package (`copyX()` functions), not glob-based** —
-     every new or renamed package needs its own copy fn or `dist/` silently omits it
-     (local Vite works, prod 404s; caused the v0.3.0 `@adia-ai/llm` + `a2ui-runtime`
-     deploy gaps). After any package add/rename, check `site.mjs` before deploying.
+   - **Package registration is one manifest, `scripts/build/site-package-registry.mjs`
+     (ADR-0062)** — every `@adia-ai/*` package the site ships is one registry entry, from
+     which the dist copy, BOTH importmaps (one shared `renderImportMapBlock()` — the
+     `site/index.html` copy is a generated artifact, `npm run build:site-importmap`),
+     the `dist/node_modules` symlinks, and the CI build order all derive. The old
+     failure class (per-package `copyX()` hand-edits; local Vite works, prod 404s —
+     v0.3.0 llm/a2ui-runtime, v0.8.27 persona+agent) is gated mechanically:
+     `check:site-packages-registered` scans every shipped source root for an
+     unregistered bare `@adia-ai/*` import and fails naming file:line, alongside
+     `check:site-importmap-fresh` and `check:deploy-workflow-build-order` — all three
+     in `npm run check` and early in `deploy-site.yml`. After any package add/rename,
+     add the registry entry; the gates say the rest.
 2. **Dry-run first, and adjudicate every delete — BEFORE the real rsync, never after:**
    ```sh
    rsync -azni --delete --exclude='packages/gen-ui/a2ui/corpus/feedback/' \