@adia-ai/adia-ui-forge 0.8.47 → 0.8.50

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-forge",
-  "version": "0.8.47",
+  "version": "0.8.50",
   "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

@@ -0,0 +1,38 @@
+{
+  "name": "adia-ui-kit-forge",
+  "version": "0.8.50",
+  "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",
+    "email": "kim.granlund@adia.ai",
+    "url": "https://github.com/adiahealth/gen-ui-kit"
+  },
+  "homepage": "https://github.com/adiahealth/gen-ui-kit",
+  "repository": "git+https://github.com/adiahealth/gen-ui-kit.git",
+  "license": "MIT",
+  "keywords": [
+    "adia-ui",
+    "a2ui",
+    "gen-ui",
+    "web-components",
+    "framework-authoring",
+    "release-engineering",
+    "maintainer"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Adia UI Forge",
+    "shortDescription": "Maintain the adia-ui (@adia-ai) framework: primitives, A2UI pipeline, releases",
+    "longDescription": "Adia UI Forge is the maintainer toolkit for the adia-ui (@adia-ai) light-DOM web-component framework — author primitives and shells, run and tune the A2UI generative-UI pipeline and its corpus, review gen-UI quality, sweep app-shell QA, cut lockstep releases, and deploy the docs site. The maintainer counterpart to Adia UI Factory (the consumer/app-author toolkit).",
+    "category": "Engineering",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "defaultPrompt": [
+      "Audit adia-ui primitives for token drift",
+      "Run the A2UI generation pipeline and score the gallery output"
+    ],
+    "brandColor": "#1B4D8C"
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog — adia-ui-kit-forge
 
+## [0.8.50] — 2026-08-23
+
+### Maintenance
+- **Lockstep bump riding the v0.8.50 cut** (`scripts/release/check-lockstep.mjs`); the headline v0.8.50 work ships in @adia-ai/web-components (prose/verse sheet removal gh#1885 / PR #1918, input/search fill-default posture gh#1856 — see `packages/web-components/CHANGELOG.md#0850--2026-08-23`). Package-local changes are listed below.
+- **`.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.
+
+### Fixed
+- **`skills/package-release` regenerates Codex plugin manifests in Step 4 (gh#1899, PR #1917)** — `release-pack.mjs` + `cut-procedure.md` gain the post-bump `build:codex-manifests` regen so `check:codex-manifests-fresh` stays green through a cut; `a2ui-maintenance` (`mcp-pipeline-ops.md`) and `primitive-authoring` (`api-contract.md`) references refreshed in the same window.
+
+## [0.8.48] — 2026-08-23
+
+### Added
+- OpenAI Codex plugin manifest (gh#1888) — `.codex-plugin/plugin.json` +
+  a per-skill `skills/<name>/agents/openai.yaml`, derived from
+  `.claude-plugin/plugin.json` via `npm run build:codex-manifests`
+  (`check:codex-manifests-fresh` gates freshness). Additive: the Claude Code
+  plugin surface is unchanged.
+
 ## [0.8.47] — 2026-08-22
 
 ### Maintenance

package/codex.interface.json

@@ -0,0 +1,12 @@
+{
+  "displayName": "Adia UI Forge",
+  "shortDescription": "Maintain the adia-ui (@adia-ai) framework: primitives, A2UI pipeline, releases",
+  "longDescription": "Adia UI Forge is the maintainer toolkit for the adia-ui (@adia-ai) light-DOM web-component framework — author primitives and shells, run and tune the A2UI generative-UI pipeline and its corpus, review gen-UI quality, sweep app-shell QA, cut lockstep releases, and deploy the docs site. The maintainer counterpart to Adia UI Factory (the consumer/app-author toolkit).",
+  "category": "Engineering",
+  "capabilities": ["Read", "Write"],
+  "defaultPrompt": [
+    "Audit adia-ui primitives for token drift",
+    "Run the A2UI generation pipeline and score the gallery output"
+  ],
+  "brandColor": "#1B4D8C"
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adia-ai/adia-ui-forge",
-  "version": "0.8.47",
-  "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.50",
+  "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",
     "a2ui",
@@ -21,6 +21,7 @@
   },
   "files": [
     ".claude-plugin",
+    ".codex-plugin",
     "skills",
     "agents",
     "commands",
@@ -28,7 +29,8 @@
     "scripts",
     "hooks",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "codex.interface.json"
   ],
   "publishConfig": {
     "access": "public",

package/skills/a2ui-maintenance/SKILL.md

@@ -47,6 +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) |
 
 ## Contracts that gate every change
 

package/skills/a2ui-maintenance/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "A2ui Maintenance"
+  short_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."

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

@@ -0,0 +1,96 @@
+# 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).
+
+## What's decided (direction, not yet fully built)
+
+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`
+reactive primitives, RFC-6901 pointer semantics (`resolvePointer`/
+`setPointer`/`deletePointer` with structural sharing), and the
+one-memoized-`Derived`-per-pointer read contract — as its own per-surface
+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).
+Phased across future cuts, plan/LLD to follow — nothing rides in the cut
+this ADR itself was ratified for (item 6).
+
+## The mechanism, once adopted
+
+- **Write path:** every write notifies the root `Cell`; every cached
+  `Derived` recomputes on any write, but a `Derived` notifies its own
+  subscribers only when the recomputed value differs by `Object.is`
+  (`renderer/dist/data-model.d.ts`, R-R10). The perf win is suppressed
+  *notification*, not suppressed *evaluation* — structural-sharing writes
+  keep untouched subtrees identity-stable, which is what makes the
+  `Object.is` cutoff effective.
+- **The falsifiable perf contract (ADR-0078 item 3):** a single-path write
+  causes `#applyProps` (or its successor) to execute ONLY for bindings whose
+  resolved value at their pointer actually changed. Re-application count is
+  the gate, not evaluation count.
+- **Pointer grammar:** RFC-6901 throughout — `~0`/`~1` escaping honored, no
+  empty-segment forgiveness, uniform missing-path → `undefined`. One
+  asymmetry survives by design: `resolvePointer`'s READ path treats only
+  `""` as whole-document (`"/"` resolves the empty-string key, strict RFC
+  6901), while `setPointer`/`deletePointer`'s WRITE/DELETE path treats
+  `undefined`, `""`, and `"/"` all as whole-document.
+- **Watch semantics:** a subscriber at a pointer fires when the resolved
+  value AT that pointer changes — any writer, any write at/above/beneath the
+  pointer that alters it; a sibling write never fires it (host-bridge R-H1,
+  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
+
+`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.
+
+## What stays fixed (don't "fix" these under this ADR)
+
+- The surface-lifecycle contract (ADR-0061 —
+  [surface-lifecycle](surface-lifecycle.md)): the state machine, the
+  `beginSurfaceUpdate → applyTo → commitSurfaceUpdate/abortSurfaceUpdate`
+  host bracket, `data-a2ui-lifecycle` reflection, bubbling surface events —
+  all orthogonal to data-model storage/invalidation and must stay
+  byte-identical across adoption phases.
+- The dialect/wire surface (ADR-0059's frame) and ADR-0072's wire-format
+  flip — both explicitly untouched by this internal swap.
+- `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
+
+`@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.
+
+## Eval-floor risk
+
+No eval floor movement is *expected* (floors measure retrieval/composition,
+not runtime rendering — floor sources are authoritative in
+[eval-diagnostics](eval-diagnostics.md)), but rendered-check verify targets
+and any eval path that renders through the runtime need per-phase
+verification once a phase actually ships. This reference flags the risk;
+each landed phase clears or reports it, not this file.

package/skills/a2ui-maintenance/references/mcp-pipeline-ops.md

@@ -59,9 +59,13 @@ MCP server restart, re-run `compose_from_chunks` for a fresh `state_id`.
 When the engine breaks expectations, fire `report_issue` with the most recent
 `state_id` (reporter: `llm` for agent self-fire, `user` for a human request).
 The record lands in the engine-internal telemetry store — scratch data for
-diagnosis. Anything worth durable tracking (a recurring pattern, a fix
-proposal) belongs in a GitHub issue or the PR description of the fixing
-change.
+diagnosis. **[corrected 2026-08-23, ADR-0008 amendment]** that store is
+`qa/findings/issues/<issue_id>.json`
+(`packages/gen-ui/engine/compose/strategies/zettel/issue-reporter.js:10,26`,
+`DEFAULT_STORAGE_ROOT`) — not the original `.brain/audit-history/issues/`
+path, which was retired. Anything worth durable tracking (a recurring
+pattern, a fix proposal) belongs in a GitHub issue or the PR description of
+the fixing change.
 
 ## Validation checks
 

package/skills/demo-audit/SKILL.md

@@ -13,6 +13,8 @@ user-invocable: true
 
 # demo-audit
 
+> **Claude-only seat.** This skill dispatches a Claude Code subagent (the Agent tool) — under Codex, run the equivalent work inline instead (gh#1888).
+
 Finds the bugs the type-checker misses across the monorepo's rendered surfaces.
 Detection is script-driven; the skill owns mode routing, triage judgment, the
 auto-fix boundary, and verification. Commands run from the monorepo root,

package/skills/demo-audit/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Demo Audit"
+  short_description: "Seven-mode QA sweep of the monorepo's demo/app surfaces: visual probe, app-shell QA, attr-quote typos, native-primitive leak, admin-shell composition, card anatomy, plus an aggregated token/contrast/lifecycle drift battery (`npm run dogfood:status`)."

package/skills/gen-ui-review/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Gen Ui Review"
+  short_description: "Closed-loop Gen UI gallery quality review — per cycle: derive ideal specs, decompose the rendered canvas, score the gap, root-cause, emit fix plans until every prompt clears the exit gate."

package/skills/llm-client-maintenance/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Llm Client Maintenance"
+  short_description: "Maintains @adia-ai/llm (packages/llm/core/): provider adapters (anthropic/openai/ gemini), the shared SSE parser, model registry, chat()/streamChat() facade, createAdapter() bridge."

package/skills/package-release/SKILL.md

@@ -17,6 +17,8 @@ user-invocable: true
 
 # package-release
 
+> **Claude-only seat.** This skill dispatches a Claude Code subagent (the Agent tool) — under Codex, run the equivalent work inline instead (gh#1888).
+
 Release engineering for an @adia-ai-style lockstep monorepo: the
 `@adia-ai/*` packages on the roster (`scripts/package-paths.mjs`, the single source — 10 lockstep as of gh#1282's shim retirement) version and
 publish together (class A). Class B (independent versioning, one member —

package/skills/package-release/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Package Release"
+  short_description: "Release engineering for the @adia-ai lockstep monorepo."

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

@@ -151,6 +151,8 @@ Any red → route via [`gates-catalog.md`](gates-catalog.md); fix at the source,
 
 **4d.5b. Regenerate catalog tiers + re-harvest the chunk corpus if it goes stale** (gh#1361, automated — this was a recurring manual rider before): `npm run build:catalog-tiers`, then `npm run check:chunks-fresh`; if that probe goes stale, `npm run harvest:chunks`. `tier-index.json` derives from the same post-bump catalog 4d.5 just refreshed, and the chunk harvester hashes `tier-index.json` as a harvest SOURCE — regenerating tiers without re-harvesting left `check:chunks-fresh` red on the next run, needing a manual rider commit both cuts it happened live: v0.8.39 (`72417beff`) and v0.8.40/CUT-0840-B (`d9ca8b323`, "Ran `npm run build:catalog-tiers` ... That regen staled `check:chunks-fresh` ... so re-harvested"). The re-harvest is CONDITIONAL on the freshness probe, not unconditional — a tier regen that produces a byte-identical index owes no re-harvest. `tier-index.json`, `packages/gen-ui/engine/corpus/manifest.json`, and `packages/gen-ui/engine/corpus/chunks/` all ride the release commit (Step 5 stages them).
 
+**4d.6. Regenerate the Codex plugin manifests** (gh#1888, gh#1899): `node scripts/build/codex-manifests.mjs`, then `npm run check:codex-manifests-fresh` to confirm. Both plugins' `.codex-plugin/plugin.json` embed `version` from `.claude-plugin/plugin.json`, which the 4b bump just moved — same "derived artifact carries the lockstep version" class as 4d.5's genui catalog. Gate 31 runs pre-bump in Step 3 and only proves freshness against the PREVIOUS version; nothing re-ran the generator post-bump before this line existed — the v0.8.48 release PR (#1897) shipped stale manifests as a result, caught by `check:codex-manifests-fresh` in CI and fixed by hand on the release branch. `packages/plugins/*/.codex-plugin/plugin.json` and `packages/plugins/*/skills/*/agents/openai.yaml` ride the release commit (Step 5 stages them).
+
 **4e. Release docs + team notes** (gated, not optional): review the entry
 files the release touches (root README/CHANGELOG, per-package READMEs —
 content currency is YOUR judgment; the gate only proves presence), then
@@ -212,6 +214,7 @@ node "${CLAUDE_PLUGIN_ROOT}/skills/package-release/scripts/bump.mjs" --from X.Y.
 npm install --package-lock-only --no-audit --no-fund                                          # 4c
 npm run check:lockstep                                                                        # 4d
 node scripts/build/derive-genui-catalog.mjs                                                   # 4d.5 — catalogId carries the bumped version (gh#617)
+node scripts/build/codex-manifests.mjs                                                        # 4d.6 — Codex manifest version carries the bumped version (gh#1899)
 node scripts/release/check-release.mjs --pending-version X.Y.Z --fix                          # 4f — AFTER the stubs exist
 node scripts/release/generate-release-notes.mjs --version X.Y.Z --write                       # 4e
 node scripts/release/check-release-docs.mjs --version X.Y.Z                                   # 4e gate

package/skills/package-release/scripts/gate-roster.mjs

@@ -131,6 +131,12 @@ export const GATE_ROSTER = [
   // inserted: gate numbers are identities in shipped release notes (see
   // gate 29's note).
   { n: 30, cmd: 'npm run check:catalog-tiers', what: 'tier-index.json vs committed catalog (L0–L4, composability law)' },
+  // gh#1888: the Codex-plugin manifest tree (.codex-plugin/plugin.json +
+  // per-skill agents/openai.yaml, both plugins) is derived from
+  // .claude-plugin/plugin.json — a stale copy is a real Codex-install
+  // hazard the same way a stale dist bundle is a real Claude-install
+  // hazard. Appended, not inserted — same numbering discipline as gate 30.
+  { n: 31, cmd: 'npm run check:codex-manifests-fresh', what: 'Codex plugin.json + openai.yaml vs .claude-plugin/plugin.json SoT' },
 ];
 
 // -- CLI ------------------------------------------------------------------

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

@@ -627,6 +627,29 @@ function step4PromoteAndBump(args) {
     console.log('  ✓ chunk corpus still fresh after catalog-tiers regen — no re-harvest needed');
   }
 
+  // Step 4d.6 — regenerate the Codex plugin manifests (gh#1888, gh#1899): both
+  // .codex-plugin/plugin.json's `version` and each per-skill agents/openai.yaml
+  // derive from .claude-plugin/plugin.json, which the bump above just moved —
+  // same "derived artifact embeds the lockstep version" class as 4d.5's genui
+  // catalog. Gate 31 (check:codex-manifests-fresh) runs pre-bump in Step 3, so
+  // it only proves freshness against the PREVIOUS version; nothing re-ran the
+  // generator after the bump until now — the release PR for v0.8.48 (#1897)
+  // shipped stale manifests as a result (Static checks + MCP smoke failed on
+  // check:codex-manifests-fresh, fixed by hand on the release branch). Step 5
+  // stages both plugins' .codex-plugin/plugin.json + skills/*/agents/openai.yaml.
+  console.log('\n  Step 4d.6 — regenerate Codex plugin manifests (version embeds the lockstep bump):');
+  sh('node scripts/build/codex-manifests.mjs', args);
+  if (args.dry) {
+    console.log('  [dry] npm run check:codex-manifests-fresh (post-regen proof)');
+  } else if (!shOk('npm run check:codex-manifests-fresh')) {
+    console.error('\nERROR: Codex plugin manifests still stale after regeneration — codex-manifests.mjs');
+    console.error('       did not produce output matching check:codex-manifests-fresh\'s expectations.');
+    console.error('       Run both by hand to diagnose before re-running the cut.');
+    process.exit(1);
+  } else {
+    console.log('  ✓ Codex plugin manifests fresh after regeneration');
+  }
+
   // Step 4e — generate docs/ops/releases/vX.Y.Z.md (gh#399: neither this step nor
   // its staging into the release commit existed before — check-cut-hygiene's
   // "notes present" claim (Step 4g, below) went unverified until
@@ -747,7 +770,17 @@ function step5Commit(args) {
       // generation MCP (@adia-ai/mcp) in .mcp.json (SKILL invariant 8 —
       // bump.mjs moves the pin too).
       const files = [`${dir}/package.json`, `${dir}/CHANGELOG.md`];
-      if (plugin) files.push(`${dir}/.claude-plugin/plugin.json`);
+      if (plugin) {
+        files.push(`${dir}/.claude-plugin/plugin.json`);
+        // gh#1899: Step 4d.6 regenerates both plugins' Codex manifest tree
+        // post-bump (version embeds the lockstep bump, same class as the
+        // genui catalog outputs above) — stage it here or CI catches the
+        // drift the way v0.8.48's release PR (#1897) did. `skills/*/
+        // agents/openai.yaml` is a glob: `git add` expands it via the shell,
+        // and the per-skill count isn't statically knowable (same shape as
+        // the chunk-corpus directory pathspec above).
+        files.push(`${dir}/.codex-plugin/plugin.json`, `${dir}/skills/*/agents/openai.yaml`);
+      }
       if (name === 'adia-ui-factory') files.push(`${dir}/.mcp.json`);
       return files;
     }),
@@ -1169,6 +1202,17 @@ function selftest() {
       // health record, or it rides untracked past the release commit
       // (v0.8.35/v0.8.36 both did, PR #1196 swept them by hand).
       'evals/health/9.9.9.json',
+      // gh#1899 — Step 4 must regenerate the Codex plugin manifests post-bump
+      // (the v0.8.48 release PR #1897 shipped stale ones without this step).
+      'Step 4d.6 — regenerate Codex plugin manifests',
+      '[dry] node scripts/build/codex-manifests.mjs',
+      // gh#1899 — Step 5's staging pathspec must carry both plugins' Codex
+      // manifest tree, or it rides untracked/uncommitted past the release
+      // commit the same way the genui catalog outputs did before gh#617.
+      'packages/plugins/adia-ui-forge/.codex-plugin/plugin.json',
+      'packages/plugins/adia-ui-forge/skills/*/agents/openai.yaml',
+      'packages/plugins/adia-ui-factory/.codex-plugin/plugin.json',
+      'packages/plugins/adia-ui-factory/skills/*/agents/openai.yaml',
     ];
     for (const marker of need) {
       if (!out.includes(marker)) {

package/skills/primitive-authoring/SKILL.md

@@ -41,6 +41,8 @@ wins any tie with this skill. Monorepo source read while authoring (yaml, CSS,
 | Convention question ("is this idiomatic?") | [code-style.md](references/code-style.md) — cite the rule, don't expand it inline |
 | Trait detail page (`site/pages/traits/<name>/`) | [trait-pages.md](references/trait-pages.md) — the ADR-0019 required-section template (traits are this skill's charter; site-docs-authoring does not own `traits/`) |
 | SVG-rendered primitive (`chart-ui`, `qr-code-ui`, `icon-ui`, or a new one) — viewBox/scaling, stroke-width, text-anchor, card-bleed clipping, hit-testing | [svg-authoring.md](references/svg-authoring.md) — NOT `chart-legend-ui`/`swatch-ui`, which are HTML/CSS despite the chart-family name (file's own §0) |
+| Form-control host sizing (fill vs. hug, a 20ch-class legibility floor, `[inline]`'s sizing axis) | [form-control-sizing.md](references/form-control-sizing.md) — ADR-0077 |
+| A `for=`-bound pair (`table-toolbar-ui`, `chart-legend-ui`, `tooltip-ui[follows=pointer]`, `context-menu-ui`) — id-ref resolution, the bubbling-event interaction contract | [for-attribute-event-contract.md](references/for-attribute-event-contract.md) — ADR-0079 |
 
 Full retrieval map — one line per reference file, grouped by axis:
 [references/INDEX.md](references/INDEX.md). Depth references (api-contract,

package/skills/primitive-authoring/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Primitive Authoring"
+  short_description: "Author or modify AdiaUI framework source inside the monorepo — primitives (packages/web-components), shells/composites (packages/web-modules), yaml SoTs, demos."

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

@@ -19,6 +19,8 @@ file, including the depth references those entries cross-link.
 - [css-patterns.md](css-patterns.md) — how do I structure a component stylesheet: two-block `@scope`, variants vs modes, token layering?
 - [lifecycle-patterns.md](lifecycle-patterns.md) — how do I keep `connected()`/`disconnected()` symmetric for listeners, timers, observers, and popovers?
 - [svg-authoring.md](svg-authoring.md) — viewBox/coordinate scaling, stroke-width, text-anchor/dominant-baseline, card-bleed clipping, currentColor vs `var()` inside SVG markup, hit-testing — for `chart-ui`/`qr-code-ui`/`icon-ui`/any new `<svg>`-emitting primitive.
+- [form-control-sizing.md](form-control-sizing.md) — does a form-control host fill its container or hug its content, and where does the legibility floor live (ADR-0077)?
+- [for-attribute-event-contract.md](for-attribute-event-contract.md) — what does `for=` resolve to, and how does a `for=`-bound pair talk to each other (ADR-0079)?
 
 ## Shells & modules
 

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

@@ -119,6 +119,30 @@ shape — see the ADR-0063 conventions list in
 
 Source: [ADR-0074](../../../../../../docs/ops/adr/adr-0074-chart-ratio-attribute-grammar.md).
 
+**[verified 2026-08-23] Failure mode — DOM-ancestry auto-detection is riskier
+than container-query auto-detection.** ADR-0081 Decision 1 (`chart-ui[labels]`,
+a 3-value enum: `""`/`chip`/`outside`) initially mirrored this same
+auto/explicit-override shape, but auto-detected via DOM ancestry — resolving
+unset `labels=""` to `chip` whenever the element sat inside a `section[bleed]`
+or `card-ui[padding="none"]` ancestor — instead of a container query on the
+element's own box. The 2026-08-21 amendment walked that back entirely after it
+silently flipped 2 of 60 fixtures on the Charts visual-eval floor
+(`comp-chart-in-card-n-*`, pre-existing full-bleed compositions), caught only
+by the floor's pixel-diff gate — neither the unit-test suite nor code review
+renders real CSS/layout. Amended decision: unset `labels=""` resolves to
+`outside` unconditionally; `chip` mode activates only via the explicit
+`labels="chip"` attribute — no ancestry detection at all. ADR-0081's Decision
+2 (a `today` marker attribute) independently rejects clock-derived
+auto-detection for the same reliability reason (cites IDR-0006). Lesson for a
+new auto-snap attribute of this shape: auto-detection is safe when it reads
+the element's *own* rendered geometry (a container query against its own box,
+as `ratio` does); it is risky when it reads *ancestor* DOM state or wall-clock
+time, because neither is guaranteed stable across every composition that
+happens to nest the element — verify any such default against a real
+pixel-diff/visual-eval gate, not unit tests or review alone. Source:
+[ADR-0081](../../../../../../docs/ops/adr/adr-0081-chart-2-0-foundations-attribute-grammar.md)
+Amendment (2026-08-21).
+
 ## Numeric props — `null` over sentinels
 
 Indeterminate, unknown, or "not yet set" numeric state uses `null`, not `-1` or `Infinity`:

package/skills/primitive-authoring/references/for-attribute-event-contract.md

@@ -0,0 +1,62 @@
+# `for=` id-ref + bubbling-event interaction contract
+
+Source of truth: [ADR-0079](../../../../../../docs/ops/adr/adr-0079-for-attribute-id-ref-and-events-only-interaction-contract.md)
+(ratified 2026-08-20, executed by gh#1780). Read the ADR before adding a new
+`for=`-bound pair or touching `table-toolbar-ui`/`chart-legend-ui`/
+`tooltip-ui`/`context-menu-ui` — this file is the routing pointer + the
+fix-now checklist, not a restatement of the ruling.
+
+## The one-line rule
+
+`for=` means id-ref, everywhere in AdiaUI — no component may give it a
+different resolution contract (`context-menu-ui`'s prior CSS-selector
+reading was the violation this ADR ends). The interaction contract over any
+`for=` binding is bubbling `CustomEvent`s in **both** directions — never a
+direct property write or method call across the binding.
+`chart-legend-ui`↔`chart-ui` is the ratified model: the bound element
+dispatches a bubbling event, the target listens on `document` filtered by
+`[for]` matching its own id.
+
+## Fix-now checklist for a `for=`-bound primitive
+
+- `for=` resolves via `getElementById` (id-ref) — never
+  `querySelectorAll`/a CSS-selector reading. A component needing
+  selector-flavored targeting names a DIFFERENT attribute (see
+  `context-menu-ui`'s `target-selector` below) — it never overloads `for`.
+- Every write the bound pair needs to make on each other is a bubbling
+  `CustomEvent`, dispatched at the resolved target (or document-delegated,
+  whichever the existing read direction already established) — never a
+  direct property write (`target.prop = …`) or method call
+  (`target.method()`) across the binding.
+- `chart-legend-ui`, `chart-ui`, and `tooltip-ui[follows=pointer]` are
+  already verified compliant — don't touch them to "align" with a new
+  pattern; the ADR names them explicitly out of scope for its own sweep.
+- `table-toolbar-ui`→`table-ui`'s inbound command surface is
+  `toolbar-search` / `toolbar-filter-set` / `toolbar-filter-clear` /
+  `toolbar-columns-set` / `toolbar-paginate` — dispatched by the toolbar at
+  its resolved `#target`, applied by `table-ui` via the same public-API call
+  the direct write used to make. This is additive to `table-ui`'s contract:
+  any consumer may dispatch these events, not only `table-toolbar-ui`. The
+  existing toolbar→consumer notification events (`search`, `filter-change`,
+  `sort-change`, `columns-change`, `page-size-change`) are unchanged and
+  never reused as the inbound command channel (naming collision, rejected
+  alternative in the ADR).
+- A component whose `for=` was CSS-selector-flavored (`context-menu-ui`'s
+  prior shape) renames the selector-flavored attribute to `target-selector`;
+  `for` survives only as a **deprecated back-compat alias** — still resolved
+  as a selector (never dual-purposed into id-ref sniffing — rejected in the
+  ADR as ambiguous), honored only when `target-selector` is unset, with a
+  one-shot `console.warn` pointing at the replacement. Document the alias as
+  deprecated in the yaml SoT, the class doc comment, and the examples.
+
+## What NOT to do
+
+- Don't invent a document-level delegated-listener shape for a pair that
+  already resolves a concrete target reference for its read direction — a
+  targeted dispatch at the resolved element is simpler and still satisfies
+  "events, not direct writes" (rejected alternative in the ADR, re:
+  `table-toolbar-ui`).
+- Don't dual-purpose one attribute name for two resolution contracts
+  (id-ref sometimes, selector sometimes) — this is the exact same-name/
+  different-contract collision ADR-0053's no-shadowing doctrine forbids for
+  global attributes, and the defect this ADR exists to end.

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

@@ -0,0 +1,59 @@
+# Form-control sizing posture — fill by default, `[inline]` hugs
+
+Source of truth: [ADR-0077](../../../../../../docs/ops/adr/adr-0077-form-control-sizing-posture.md)
+(ratified 2026-08-19; amends [ADR-0037](../../../../../../docs/ops/adr/adr-0037-inline-display-mode-convention.md)
+partial — `[inline]` semantics widen to own the sizing axis, the display-default
+convention itself is unchanged). Companion SPEC:
+`docs/ops/spec/spec-form-control-sizing-posture.md`. Read the ADR before
+touching a form-control host's width/min-width rules — this file is the
+routing pointer + the fix-now checklist, not a restatement of the ruling.
+
+## The one-line rule
+
+A form-control host, absent `[inline]`, is block-level (ADR-0037, unchanged)
+**and fills its container's available inline space** — in block flow via
+`width: auto` (already true), in flex/grid parents via `width: 100%` on the
+host (the mechanism `field-ui`/`otp-input-ui` already shipped). `[inline]`
+flips BOTH axes at once: inline-level display **and** shrink-wrap/hug sizing.
+No separate `hug` attribute exists or should be minted — one token, one
+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
+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
+rule). Inner *segment* floors (`time-picker-ui`'s 2ch/2.5ch segments,
+`tags-input-ui`'s 8em `[data-inline-input]`) are inner mechanics, not host
+posture, and also stay in both states.
+
+## Fix-now checklist for a form-control primitive
+
+- 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.
+- 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
+  width), don't invent a third posture token.
+- `field-ui`/`fields-ui`'s `[inline]` carve-out (single-row layout meaning,
+  ADR-0037 §5) is retained and stays behaviorally convergent with this
+  decision — don't "fix" it to match the family's token meaning.
+- The trip-wire gate is `scripts/release/check-display-default-convention.mjs`
+  — it fails a 20ch-class host floor on the plain `:scope` and fails a
+  missing fill mechanism in the default state, for roster components. One
+  gate, no second check to satisfy.
+
+## Roster and rollout
+
+The exact component roster and the breaking-wave/golden-regeneration rollout
+(one coordinated wave, MIGRATION GUIDE entry same cycle, deliberately
+regenerated `evals/visual/` goldens — never additive-first, never shimmed)
+are the companion PLAN's job (`docs/ops/plan/plan-form-control-sizing.md`),
+not this reference — cite the ADR/PLAN rather than re-deriving scope here.

package/skills/site-deployment/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Site Deployment"
+  short_description: "Deploys and operates the AdiaUI site + services on exe.dev VMs — pushing a `site-v*` tag through the hardened rsync --delete deploy to ui-kit.exe.xyz (dry-run delete summary reviewed before the real deploy job runs), diagnosis (\"Port 8000 unbound\", a 502, a stale/404ing build behind npm after the last lockstep cut), rolling back a broken deploy, VM provisioning, secret rotation."

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

@@ -16,6 +16,8 @@ user-invocable: true
 
 # site-docs-authoring
 
+> **Claude-only seat.** This skill dispatches a Claude Code subagent (the Agent tool) — under Codex, run the equivalent work inline instead (gh#1888).
+
 Every page under `site/pages/{architecture,getting-started,guides,patterns,
 reference}/` shares one skeleton: `<header><h1>` + a deck `<p>`, then numbered
 `<section data-section data-property="...">` blocks, each opening

package/skills/site-docs-authoring/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Site Docs Authoring"
+  short_description: "Review or author pages under site/pages/{architecture,getting-started, guides,patterns,reference}/ — the docs site (count the pages on disk; it grows)."

package/skills/ssr-compatibility/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Ssr Compatibility"
+  short_description: "Answers why an AdiaUI component crashes, drops content, renders wrong, or mutates a byte-identical subtree under SSR (linkedom/Astro) — the known failure shapes, what's fixed vs open, how to prove a fix under the linkedom shim gate."