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

package/scripts/site-postwrite-derivation-gate

@@ -1,88 +1,40 @@
 #!/usr/bin/env python3
 """site-postwrite-derivation-gate — PostToolUse check: site source edits name their stale derivatives.
 
-The docs site renders converted routes from GENERATED artifacts: site/site.js
-probes site-a2ui/pages/<slug>.a2ui.json per route and renders it via
-<a2ui-root>.doc — the HTML fragment under site/pages/** is only the 404
-fallback. An editor who changes the fragment and stops there has changed
-NOTHING users see (shipped exactly that way 2026-07, caught only by manual
-review). site/sitemap.json likewise feeds site/llms.txt and the patterns
-index. This hook feeds the regeneration obligation back at write-time; the
-hard gate is the repo-wide site-a2ui verify wired in CI.
-
-Quiet on: fragments with no sitemap route, routes the ledger has not
-converted (the fragment IS what renders), anything under site-a2ui/ and the
-generated pages sidecar-prewrite-guard owns, and any internal error
-(fail-open — this hook must never block editing with a crash).
+site/sitemap.json feeds GENERATED surfaces (site/llms.txt, the patterns/
+templates index) that go stale the moment a route or content path changes
+without a regen. This hook feeds that regeneration obligation back at
+write-time.
+
+(Before ADR-0072 Decision 2 / gh#2410, this hook also flagged
+site/pages/**/*.html fragment edits whose route the site-a2ui ledger
+marked "converted" — the docs site rendered such routes from a GENERATED
+site-a2ui/pages/<slug>.a2ui.json artifact, so a fragment-only edit changed
+nothing users saw. That render path retired; every route now renders
+straight from its fragment, so a fragment edit is never stale on its own
+and needs no nudge.)
 
 Usage:
   site-postwrite-derivation-gate --hook       # PostToolUse mode: event JSON on stdin
-  site-postwrite-derivation-gate selftest     # prove matcher + resolution on fixtures
+  site-postwrite-derivation-gate selftest     # prove matcher on fixtures
 """
 import json
 import sys
 
 SITEMAP_MARKER = "site/sitemap.json"
-FRAGMENT_MARKER = "site/pages/"
-
-# Generated files under site/pages/ are sidecar-prewrite-guard territory.
-GENERATED_EXCLUDE = ("site/pages/patterns/index.html",)
 
 
 def classify(path):
-    """→ ("sitemap"|"fragment", repo-root prefix, "/"-rooted repo path) or (None, None, None)."""
-    if not path or "site-a2ui/" in path:
-        return None, None, None
-    if path.endswith(SITEMAP_MARKER):
-        return "sitemap", path[: -len(SITEMAP_MARKER)], "/" + SITEMAP_MARKER
-    idx = path.find(FRAGMENT_MARKER)
-    if idx == -1 or not path.endswith(".html") or path[idx:] in GENERATED_EXCLUDE:
-        return None, None, None
-    return "fragment", path[:idx], "/" + path[idx:]
-
-
-def find_route(sitemap, rel):
-    """Walk sections/items for the entry whose `content` equals rel; → route path or None."""
-    stack = [sitemap.get("sections") or []]
-    while stack:
-        node = stack.pop()
-        if isinstance(node, list):
-            stack.extend(node)
-        elif isinstance(node, dict):
-            if node.get("content") == rel and node.get("path"):
-                return node["path"]
-            stack.extend(v for k, v in node.items() if k in ("sections", "items", "children"))
+    """→ "sitemap" if `path` is site/sitemap.json, else None."""
+    if path and path.endswith(SITEMAP_MARKER):
+        return "sitemap"
     return None
 
 
-def resolve_fragment(root, rel):
-    """→ feedback reason for a stale-artifact edit, or None to stay quiet.
-
-    Raises on I/O / parse trouble — the caller fail-opens.
-    """
-    with open(root + "site/sitemap.json", encoding="utf-8") as f:
-        route = find_route(json.load(f), rel)
-    if not route:
-        return None  # not a routed page
-    with open(root + "site-a2ui/ledger.json", encoding="utf-8") as f:
-        rows = json.load(f).get("pages") or []
-    row = next((r for r in rows if r.get("route") == route), None)
-    if not row or row.get("status") != "converted":
-        return None  # legacy-rendered: the fragment IS what users see
-    slug = row.get("slug") or route.lstrip("/").replace("/", "__")
-    return (
-        f"site-postwrite-derivation-gate · {rel} is the SOURCE for {route}, which renders "
-        f"from GENERATED site-a2ui/pages/{slug}.a2ui.json — the artifact is now stale and "
-        f"users still see the OLD content. Regenerate: `node scripts/build/site-a2ui.mjs "
-        f"--page {route}` (repo-wide check: `npm run verify:site-a2ui`)."
-    )
-
-
 SITEMAP_REASON = (
     "site-postwrite-derivation-gate · site/sitemap.json feeds GENERATED surfaces that are "
     "now stale: site/llms.txt (`npm run build:llms`) and the patterns/templates index "
-    "(`npm run build:patterns-index`). If you changed routes or content paths, also verify "
-    "site-a2ui route coverage: `node scripts/build/site-a2ui.mjs --verify`."
+    "(`npm run build:patterns-index`)."
 )
 
 
@@ -92,80 +44,24 @@ def hook_mode():
     except Exception:
         return 0
     tool_input = event.get("tool_input") or {}
-    kind, root, rel = classify(tool_input.get("file_path") or "")
-    if not kind:
-        return 0
-    if kind == "sitemap":
+    if classify(tool_input.get("file_path") or "") == "sitemap":
         print(json.dumps({"decision": "block", "reason": SITEMAP_REASON}))
-        return 0
-    try:
-        reason = resolve_fragment(root, rel)
-    except Exception:
-        return 0  # fail-open: never block editing on our own error
-    if reason:
-        print(json.dumps({"decision": "block", "reason": reason}))
     return 0
 
 
 def selftest():
-    import os
-    import tempfile
-
     scope_cases = [
-        ("/repo/site/pages/architecture/ontology.html", "fragment"),
-        ("site/pages/guides/testing.html", "fragment"),
         ("/repo/site/sitemap.json", "sitemap"),
-        ("/repo/site/pages/patterns/index.html", None),  # generated: prewrite guard owns it
-        ("/repo/site-a2ui/pages/site__x__y.a2ui.json", None),
-        ("/repo/site-a2ui/ledger.json", None),
+        ("/repo/site/pages/architecture/ontology.html", None),
+        ("site/pages/guides/testing.html", None),
+        ("/repo/site/pages/patterns/index.html", None),
         ("/repo/site/site.js", None),
         ("/repo/site/pages/architecture/notes.txt", None),
         ("/repo/apps/tasks/app/index.html", None),
     ]
     for path, expected in scope_cases:
-        if classify(path)[0] != expected:
-            print(f"selftest: FAIL scope {path} → {classify(path)[0]} expected {expected}")
-            return 1
-    with tempfile.TemporaryDirectory() as tmp:
-        root = tmp + os.sep
-        os.makedirs(root + "site")
-        os.makedirs(root + "site-a2ui")
-        with open(root + "site/sitemap.json", "w", encoding="utf-8") as f:
-            json.dump(
-                {
-                    "sections": [
-                        {
-                            "items": [
-                                {"path": "/site/a/one", "content": "/site/pages/a/one.html"},
-                                {"path": "/site/a/two", "content": "/site/pages/a/two.html"},
-                            ]
-                        }
-                    ]
-                },
-                f,
-            )
-        with open(root + "site-a2ui/ledger.json", "w", encoding="utf-8") as f:
-            json.dump(
-                {
-                    "pages": [
-                        {"route": "/site/a/one", "slug": "site__a__one", "status": "converted"},
-                        {"route": "/site/a/two", "slug": "site__a__two", "status": "failed"},
-                    ]
-                },
-                f,
-            )
-        resolve_cases = [
-            ("/site/pages/a/one.html", True),  # converted → nudge
-            ("/site/pages/a/two.html", False),  # ledger row not converted → quiet
-            ("/site/pages/a/three.html", False),  # no sitemap entry → quiet
-        ]
-        for rel, should_fire in resolve_cases:
-            fired = resolve_fragment(root, rel) is not None
-            if fired != should_fire:
-                print(f"selftest: FAIL resolve {rel} fired={fired} expected={should_fire}")
-                return 1
-        if "site__a__one.a2ui.json" not in resolve_fragment(root, "/site/pages/a/one.html"):
-            print("selftest: FAIL reason does not name the stale artifact")
+        if classify(path) != expected:
+            print(f"selftest: FAIL scope {path} → {classify(path)} expected {expected}")
             return 1
     print("selftest: PASS")
     return 0

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,65 @@
 
 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 — retired 2026-08-31]** That trigger fired and was
+ruled: retirement, not re-point (Decision 2). Passive attrition never
+netted the promoted set down (355 pages and growing at last measurement —
+regen work kept adding rows faster than breakage retired them), so the
+operator converted it to an active drain (gh#2410): the mechanism —
+builder, ledger, artifact tree, gates, hook — is gone. The docs site now
+renders every route through the legacy template path only; site-a2ui is
+no longer part of this pipeline. The dialect side's regression-corpus
+coverage site-a2ui once provided (real-content-scale exercise of the
+dialect renderer, the ADR-0061 lifecycle path, and the engine transpiler)
+has no standing replacement — see ADR-0072 Decision 2 / gh#2410 for the
+closure record.
 
 All paths repo-relative. Specs worth reading before structural changes:
 `.claude/docs/specs/a2ui-v0.9-catalog-guide.md` (protocol + catalog format),
@@ -151,6 +182,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/demo-audit/references/visual-probe-triage.md

@@ -1,12 +1,15 @@
 # Mode 1 — Component visual probe: probe classes + triage
 
+`<plugin-root>` below is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory
+in Codex.
+
 Detection layers, deepest last:
 
 1. `npm run dogfood:visual-probe` — baseline per-page bar: no 4xx/5xx, no
    console JS errors, non-zero body rect, ≥1 upgraded custom-element host.
    Artifacts land in `qa/findings/visual-probe-<DATE>/`.
 2. Bundled deep analyzer —
-   `node "${CLAUDE_PLUGIN_ROOT}/skills/demo-audit/scripts/analyze.mjs"`.
+   `node "<plugin-root>/skills/demo-audit/scripts/analyze.mjs"`.
    Resolves the target checkout from `$ADIA_REPO_ROOT`, else cwd — always run
    from (or point it at) the monorepo checkout, never the plugin install dir.
    Flags: `--filter <slug>` · `--port N` (default 5173) · `--out PATH`

package/skills/gen-ui-review/SKILL.md

@@ -77,7 +77,10 @@ only that file, never the raw DOM/canvas/gallery-latest.json.** The
 structural prompt-injection defense. Data model:
 [loop-protocol](references/loop-protocol.md).
 
-## Scripts (`node ${CLAUDE_PLUGIN_ROOT}/skills/gen-ui-review/scripts/…`, from monorepo root)
+## Scripts (`node <plugin-root>/skills/gen-ui-review/scripts/…`, from monorepo root)
+
+`<plugin-root>` is `$CLAUDE_PLUGIN_ROOT` in Claude Code; the plugin's installed directory in
+Codex.
 
 | Command | Purpose |
 | --- | --- |