@adia-ai/adia-ui-forge 0.8.42 → 0.8.44

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

@@ -22,6 +22,26 @@ static properties = {
 - `reflect` — when `true`, JS property changes write back to the HTML attribute so CSS can match it. Required for every state-bearing Boolean. Usually safe to omit for large value props (long strings, big objects).
 - `attribute` — explicit kebab-case mapping when the JS name doesn't auto-convert cleanly. `camelCase` → `camel-case` automatic; override via `attribute: 'max-length'` when you want non-default behavior.
 
+[verified 2026-08-19] **Literal-string `"false"` parity (ADR-0075).** For a
+`Boolean`-typed prop, `parseAttr` (`core/element.js:93-94`) special-cases the
+literal attribute string `"false"` to parse as JS `false` — a deliberate
+deviation from strict HTML boolean-attribute semantics (where any presence,
+including `attr="false"`, means `true`). This matches the A2UI transpiler's
+own prior `// (defensive)` special-case
+(`compose/transpiler/transpiler-maps.js:206-207`), so identical markup now
+parses the same in the live DOM and in transpiled/generated output. Quoting
+the Decision: "for `t === Boolean`, the literal string `\"false\"` parses to
+JS `false`; any other present value (including empty string) parses to
+`true`; absence stays `false`." A component author or generation pipeline
+that writes `interactive="false"` on a `default: true` Boolean prop gets the
+intuitive result — do not assume strict HTML semantics here. (`default:
+true` itself remains the rare, ratified exception this ADR's blast radius
+runs against — ADR-0063's stamped-attribute mechanism, gh#961 — never the
+default shape "Boolean prop naming — the flip rule" above documents.) Named
+blast radius already shipped and relying on this: `password-strength-ui
+show-label="false"`, `nav-group-ui collapsible="false"`
+(`.examples.html` demos for both).
+
 ## The `attr:` silent-typo trap
 
 A real bug caught in iteration 4:
@@ -61,6 +81,44 @@ AdiaUI conventions require `default: false` on all Booleans. The naming follows:
 - `enabled` (invert to `disabled`), `visible` (invert to `hidden`) — these clash with standard HTML attribute vocabulary.
 - Double-negatives like `unhide` or `dontSkip`.
 
+## Enum attribute + container-query auto-snap default — no interpolation
+
+[verified 2026-08-19] ADR-0074 establishes the cross-component pattern for a
+value-enum attribute whose sensible default is "pick automatically from live
+layout, but let a consumer pin it explicitly": `chart-ui` /
+`chart-legend-ui` / `chart-in-card`'s `ratio` attribute, three allowed
+values (`3:2`, `1:1`, `2:3`), unset by default. Quoting the Decision:
+"Unset (the default, empty string) means auto-snap: a CSS container query on
+the element's own box compares its live aspect ratio against two midpoint
+boundaries … and renders the nearest named ratio's studied layout — never a
+scaled/interpolated blend. Setting `ratio` explicitly pins that ratio's
+rendering regardless of the container's actual aspect, overriding the
+container query."
+
+Shape to follow for a new attribute of this kind:
+
+- A plain value-enum attribute, not a boolean — ADR-0063's `no-*`
+  negation-prefix grammar does not apply.
+- Unset/default means container-query-driven auto-snap against studied
+  breakpoints — discrete snapping between named values, never continuous
+  interpolation (an in-between state was never individually studied, so it
+  can't carry a "deliberately designed" claim).
+- An explicit attribute value always pins and overrides the auto-snap,
+  never blends with it.
+- The resolved value reflects back for CSS/consumer introspection —
+  `data-ratio-resolved` on `chart-ui` names which of the enum's snapped or
+  pinned values is currently in effect, distinct from the (possibly unset)
+  `ratio` attribute itself.
+- Don't fold the new axis into an existing enum attribute that covers a
+  different concern (`size` stayed `sm|md|lg`-only; `ratio` didn't grow a
+  compound value like `lg-2:3`) — orthogonal axes get their own attribute.
+
+`table-toolbar-ui[stage]` (ADR-0076) is the second precedent for this same
+shape — see the ADR-0063 conventions list in
+[token-contract.md](token-contract.md).
+
+Source: [ADR-0074](../../../../../../docs/ops/adr/adr-0074-chart-ratio-attribute-grammar.md).
+
 ## Numeric props — `null` over sentinels
 
 Indeterminate, unknown, or "not yet set" numeric state uses `null`, not `-1` or `Infinity`:

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

@@ -1,5 +1,30 @@
 # AdiaUI code style — best practices
 
+## First principles (SKILL.md's own summary, expanded)
+
+1. **Invariants are enforced by the next author, not the linter.** A component
+   that violates the contract silently teaches the next agent the violation is
+   acceptable. Write as if your component is the reference the next one is
+   patterned after — because it will be.
+2. **Default behavior is the absent attribute.** `<component-ui>` with no
+   attributes does the expected default thing; every Boolean prop defaults to
+   `false`. If the expected default is "on," the prop name is wrong — flip it
+   (`closable` → `permanent`, `animate` → `static`).
+3. **Variants change tokens; modes change layout.** A variant body contains
+   only `--component-*: var(...)` lines — no `padding`, `display`, `position`,
+   `width`, `height`, `gap`, `flex`, `grid`, `overflow`, `border-radius`.
+   Layout-changing attributes are modes and require a Sanctioned Mode
+   Attributes entry in the contract doc.
+4. **Symmetric lifecycle or it's a leak.** Every listener added in
+   `connected()` is removed in `disconnected()`; every timer cleared, observer
+   disconnected, cached ref nulled. Handlers are stable `#field` arrows so
+   `removeEventListener` can match — inline arrows bit three components in one
+   audit cycle.
+5. **Component tokens consume L3, not L2.** Alias from the role×state matrix
+   (`--a-primary-bg-hover`), never the family base (`--a-primary`) — bypassing
+   L3 strands the component outside theme / dark-mode / contrast cascades
+   silently.
+
 Modern AdiaUI is small, declarative, and token-driven. Most of the "bugs" agents write are bugs _against the conventions_ — bare `<div>`s where `col-ui` belongs, raw `<input>` where `input-ui` belongs, hex colors where tokens belong. The conventions are not stylistic preferences; each one corresponds to a working feature (theme switching, density modes, form association, focus rings) that breaks silently when the convention is violated.
 
 When in doubt: look up the catalog (the `lookup_component` MCP tool, or the adia-factory plugin's composition skill), pick the existing primitive, wire through tokens.
@@ -221,6 +246,19 @@ Default behavior is the absent attribute. Attributes exist to opt OUT or carry a
 
 State-bearing Booleans must `reflect: true` so CSS can match `:scope[disabled]`, `:scope[selected]`, etc. Without reflection, hover / active / selected styles break silently.
 
+[verified 2026-08-19] **The literal string `"false"` is not "presence = true"
+here.** ADR-0075 special-cases `parseAttr` for `Boolean`-typed props so the
+literal attribute string `"false"` parses to JS `false`, not `true` —
+deviating from strict HTML semantics on purpose, to match this repo's own
+A2UI transpiler (which already special-cased it defensively) and the
+authoring intuition both human and generated markup default to. Writing
+`show-label="false"` on a `default: true` Boolean prop does what it looks
+like it does. (`default: true` is itself the rare, ratified exception to
+this section's "every Boolean defaults to `false`" rule — ADR-0063's
+stamped-attribute mechanism, gh#961 — not a license to skip the flip rule
+above for a new prop.) See [api-contract.md](api-contract.md)'s field-rules
+section for the full rule and shipped blast radius (`core/element.js:93-94`).
+
 Native DOM accessors (`textContent`, `innerHTML`) get clobbered if declared in `static properties` — `installProps` overrides the native setter and `el.textContent = ''` becomes a signal write, not a child-wipe. Don't declare those names in `static properties`.
 
 ## Symmetric lifecycle

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.
 

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

@@ -142,7 +142,7 @@ mechanics; never work from this summary alone):
   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
+(`docs/ops/adr/adr-0063-attribute-grammar-addendum.md`) ratifies seven
 CROSS-SIBLING conventions for component-local attribute naming — the axis
 ADR-0053/0054 don't cover. Any new attribute follows these:
 
@@ -179,11 +179,71 @@ ADR-0053/0054 don't cover. Any new attribute follows these:
 - **`-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 are follow-on BUILD work tracked as gh#1563, not yet
-landed in code (compat shims in 0.8.42; breaking cut rides 0.9.0) — when a
-yaml still shows an old name, the ADR is ratified and the code is behind,
-not the other way around.
+- **[verified 2026-08-19] Preset-boolean-vs-alias-retirement boundary**
+  (ADR-0076): a boolean attribute that is additive sugar over several
+  existing granular `no-*` opt-outs — `table-toolbar-ui[chrome-only]`
+  equivalent to setting all four of `no-filter`, `no-sort`, `no-columns`,
+  `no-search` — is NOT an ADR-0063-style alias-retirement case (the
+  granular attributes aren't duplicate spellings of one concept the way
+  `alert[dismissible]`/`[closable]` were; a consumer may legitimately want
+  a subset off, a combination the preset alone can't express), so the
+  granular attributes stay shipped, independently-addressable API with no
+  deprecation. The preset's precedence is **pure, absolute OR — never a
+  tri-state**: while set, all covered controls are off, full stop, with no
+  partial re-enable via clearing an individual `no-*` while the preset
+  remains set (ADR-0076: "`no-*` attributes are presence-based booleans …
+  meaning 'presence forces off' is expressible but 'absence means defer to
+  [the preset]'s own OR' is not without a tri-state amendment"). A second
+  auto-snap-enum precedent alongside ADR-0074's chart `ratio` lands here
+  too: `table-toolbar-ui[stage]` (`full | search-tight | icon-only |
+  overflow`) — unset auto-snaps via `@container` queries against studied
+  breakpoints, an explicit value pins and overrides the query, no
+  interpolation between stages.
+
+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.
+
+## Disabled-state tokens
+
+[verified 2026-08-19] ADR-0073 ratifies the standing convention for any
+control supporting the `disabled` boolean attribute/state:
+
+- **Shared bg role, container-low tier.** `--a-ui-bg-disabled`
+  (`styles/colors/semantics/features.css`) resolves to
+  `var(--md-sys-color-neutral-container-low)` — the same 10%-tint role
+  `--a-bg-hover` / `--a-bg-muted` ride for REST-state de-emphasis. A
+  component's own `--<component>-bg-disabled` indirection aliases this
+  shared role — never a raw color, never a per-family `*-container-low`
+  variant (none exists in the disabled path).
+- **`[state][disabled]` specificity override for checked/selected fills.**
+  A `[checked]`/`[selected]` selector outranks a plain `[disabled]` rule on
+  CSS specificity (2 attribute selectors beat 1), so a checked+disabled
+  control silently keeps its active-state fill unless the component adds an
+  explicit higher-specificity override — `[checked][disabled]` /
+  `[selected][disabled]` — routed through its own
+  `--<component>-...-checked-disabled` (or `-selected-disabled`) custom
+  prop, itself aliasing `--a-ui-bg-disabled`.
+- **Reduced-contrast disabled border — the `--input-border-disabled`
+  pattern.** Any control that renders a border when disabled adds
+  `--<component>-border-disabled: var(--a-ui-border-disabled)`, applied as
+  `border-color` under `:scope[disabled]`.
+
+Quoting ADR-0073's Decision 5: "a control supporting `disabled` uses the
+shared, single neutral `--md-sys-color-neutral-container-low` role for
+background … always through a `--<component>-bg-disabled` … indirection
+aliasing `--a-ui-bg-disabled` … uses the reduced-contrast
+`--input-border-disabled` pattern … for any border it renders when disabled
+… overrides any checked/selected state fill at `[state][disabled]`
+specificity rather than relying on `[disabled]` alone."
+
+The re-runnable check is `scripts/audit/audit-disabled-fill-tokens.mjs`
+(`check:disabled-fill-audit`, advisory) — it fails any `[disabled]`-scoped
+`background`/`background-color` that doesn't resolve through a
+disabled-aware indirection.
+
+Source: [ADR-0073](../../../../../../docs/ops/adr/adr-0073-disabled-state-container-low-token-convention.md).
 
 ## When to update this reference
 

package/skills/site-deployment/SKILL.md

@@ -28,13 +28,11 @@ directives are findings.
 
 ## Platform contract (the non-obvious bits)
 
-- The app binds **`:8000` plain HTTP**; the exe.dev edge terminates TLS on
-  `<host>.exe.xyz` and forwards to VM `:8000`. Nothing listening ⇒ exe.dev
-  serves its "**Port 8000 unbound.**" error page (its nginx hint is just an
-  example — anything binding :8000 works). Don't bind :443 on the VM.
-- Default user **`exedev`** (uid 1000, in `sudo` + `docker`); service
-  processes run as it. Preinstalled: `git`, `rsync`, `docker`. NOT
-  preinstalled: `caddy`, `node`, `nginx` (apt + NodeSource).
+- The app binds **`:8000` plain HTTP**; the exe.dev edge terminates TLS and
+  forwards to VM `:8000`. Nothing listening ⇒ "**Port 8000 unbound.**"
+  Don't bind :443 on the VM.
+- Default user **`exedev`** (uid 1000, `sudo` + `docker`); service runs as
+  it. Preinstalled: `git`, `rsync`, `docker`. NOT: `caddy`, `node`, `nginx`.
 - **`127.0.0.1:9999` runs `shelley`** — exe.dev's internal agent,
   localhost-only. Leave it running; don't bind 9999.
 - Disk: 25 GB on `/`. New VMs ship RSA-2048-only host keys — verify the
@@ -47,18 +45,15 @@ Standard layout: `/srv/<app>/dist/` webroot (exedev-owned) ·
 
 ## Deploy-freshness cadence — a lockstep cut is not a site deploy
 
-`package-release` cutting and publishing the lockstep version (the roster in
-`scripts/package-paths.mjs` is the live count) does
-**not** itself update `ui-kit.exe.xyz` — that only happens on a `site-v*` tag
-push (see below). Any lockstep cut that changes a package the site actually
-serves — `web-components`, `web-modules`, `llm`, or `a2ui/*` — **owes a site
-deploy in the same release cycle**, or an explicit operator decision to skip
-it, recorded in the release notes (who decided, why). "The release finished"
-is not evidence the site is current: the v0.8.x window is the proof case — a
-lockstep cut touching served packages landed with no matching `site-v*` tag,
-and the deployed site sat a week behind npm before anyone noticed. When
-handing off from a release, check whether the cut touched a served package
-and close the loop before calling the cycle done.
+`package-release` cutting and publishing does **not** itself update
+`ui-kit.exe.xyz` — only a `site-v*` tag push does. Any lockstep cut that
+changes a package the site actually serves (`web-components`,
+`web-modules`, `llm`, `a2ui/*`) **owes a site deploy in the same release
+cycle**, or an explicit, recorded operator decision to skip it. "The
+release finished" is not evidence the site is current (the v0.8.x window:
+a served-package cut landed with no matching tag, site sat a week stale).
+When handing off from a release, check whether the cut touched a served
+package before calling the cycle done.
 
 ## Current deployments
 
@@ -72,60 +67,22 @@ VM artifacts (Caddyfile, unit, env example) live in repo `deploy/`.
 
 **Never run `npm run deploy:site` from a local shell.** Push a tag matching
 `site-v*` (or run the workflow via `workflow_dispatch`) — `deploy-site.yml`
-builds, dry-runs, and (once the `production-site` GitHub Environment has
-required reviewers configured — a one-time repo-settings step, Settings →
-Environments) waits for a human to read the dry-run's delete summary in the
-job before the destructive `deploy` job runs. The hardened sequence below
-is what the workflow automates; it's kept here as the reference for what
-the workflow does and as a manual fallback if CI itself is unavailable.
-
-`npm run deploy:site` still exists locally (`build:site` + `rsync -az
---delete dist/ → /srv/adia-ui/dist/`) for that fallback case only. It is
-destructive (a 2026-06-08 manual run deleted 3,572 files) — every step
-below is incident-earned; the reference carries the full commands and the
-delete-adjudication classes.
-
-1. Build from clean, fully-merged `main`. In a fresh worktree,
-   `npm run build -w @adia-ai/llm` runs **before** `build:site` — llm compiles
-   at publish time and its outputs are gitignored, so without it
-   `/packages/llm/core/index.js` 404s and component registration breaks site-wide
-   (found live 2026-06-09).
-2. Dry-run `rsync -azni --delete --exclude='packages/gen-ui/a2ui/corpus/feedback/'`
-   and bucket **every** `*deleting` line into a known-safe class; any
-   unexplained served-content delete aborts the deploy. The exclude protects
-   prod-only runtime-written files (feedback logs wiped 2026-06-10).
-3. Snapshot prod: `cp -al /srv/<app>/dist /srv/<app>/dist.bak-<date>`
-   (hardlink farm — instant, and the only rollback).
-4. Real rsync — the dry-run minus `-n`, SAME excludes, and the SAME BYTES:
-   both jobs rsync the artifact-round-tripped tree, and the deploy job aborts
-   if its tree's sha256 fingerprint differs from the one whose delete summary
-   was approved (gh#425 — the dry-run used to read the build job's own
-   `dist/`, so the v0.8.14 summary listed 3,128 deletions the real send never
-   performed; an over-reporting summary trains reviewers to approve past scary
-   numbers, and the same gap can under-report).
-5. Verify a fixture **file** that only exists in the new build, then
-   render-check a `/site/components/*` page headlessly (SPA returns 200 shell
-   for any route; file presence alone misses the llm-404 class).
-6. On verify failure: `rm -rf dist && mv dist.bak-<date> dist`. Keep the
-   snapshot until the deploy is confirmed good.
+builds, dry-runs, and waits for a human to read the delete summary before
+the destructive `deploy` job runs. `npm run deploy:site` still exists
+locally for CI-unavailable fallback only, and is destructive (a 2026-06-08
+manual run deleted 3,572 files). The full step-by-step hardened sequence
+(llm-build-first gotcha, delete-adjudication classes, snapshot, verified
+rsync, fixture+render verify, rollback) is in
+[deploy-playbooks.md](references/deploy-playbooks.md)'s "Hardened
+`--delete` deploy sequence" — every step there is incident-earned; read it
+before running the fallback by hand.
 
 If `server.js` changed: rsync it, then `sudo systemctl restart <app>`.
 
-### One-time CI setup for `ui-kit.exe.xyz`
-
-- **Repo secret `SITE_DEPLOY_SSH_KEY`** — done. An ed25519 keypair generated
-  *by a human*, never by the agent (Hard gate 1). Public half goes in the
-  VM's `~exedev/.ssh/authorized_keys`; private half goes in
-  Settings → Secrets and variables → Actions, pasted directly — it should
-  never appear in an agent's Bash context or a commit.
-- **Environment `production-site` reviewer gate — CONFIGURED** (verified
-  live 2026-08-11, `gh api repos/<org>/<repo>/environments`:
-  `protection_rules` carries `required_reviewers`). The `deploy` job in
-  `deploy-site.yml` therefore blocks on a human approval after its dry-run
-  job — the delete-adjudication gate this skill's hardened-deploy design
-  assumes. Changing the reviewer set is operator-only (repo Settings →
-  Environments → `production-site`) — no agent can configure it. Re-check
-  the API output before trusting this line; it drifts with repo settings.
+One-time CI setup for `ui-kit.exe.xyz` (the deploy SSH key, the
+`production-site` reviewer gate) is in
+[deploy-playbooks.md](references/deploy-playbooks.md)'s own section by
+that name.
 
 ## Other playbooks (reference §-anchors)
 
@@ -161,24 +118,9 @@ rollback state:    not-needed | rolled-back — <if rolled back, what triggered
 verdict:           shipped | held — <one line>
 ```
 
-Filled example (a real cut, `gh run view 29586391343`):
-
-```text
-Deploy Record
-tag / run id:      site-v4 (workflow run 29586391343, 2026-07-17T14:03:15Z)
-dry-run deletes:   see the run's dry-run job log for the class breakdown
-fixture verified:  pass — CI's post-deploy verify step, run marked success
-render verified:   pass — CI's post-deploy verify step, run marked success
-snapshot:          CI pre-deploy hardlink step (deploy-site.yml)
-rollback state:    not-needed
-verdict:           shipped
-```
-
-This example cites the run URL rather than restating its log inline — the
-record's job is to point at the evidence, not transcribe it; re-derive the
-dry-run/fixture/render lines from `gh run view <id> --log` if the detail is
-ever needed, don't assume this filled example's prose stays current with a
-run that already happened.
+A filled worked example (a real cut) is in
+[deploy-playbooks.md](references/deploy-playbooks.md)'s own "Deploy Record"
+section.
 
 ## Hard gates
 

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

@@ -97,6 +97,22 @@ sudo vim /etc/<app>.env
 sudo systemctl restart <app>
 ```
 
+## One-time CI setup for `ui-kit.exe.xyz`
+
+- **Repo secret `SITE_DEPLOY_SSH_KEY`** — done. An ed25519 keypair generated
+  *by a human*, never by the agent (Hard gate 1). Public half goes in the
+  VM's `~exedev/.ssh/authorized_keys`; private half goes in
+  Settings → Secrets and variables → Actions, pasted directly — it should
+  never appear in an agent's Bash context or a commit.
+- **Environment `production-site` reviewer gate — CONFIGURED** (verified
+  live 2026-08-11, `gh api repos/<org>/<repo>/environments`:
+  `protection_rules` carries `required_reviewers`). The `deploy` job in
+  `deploy-site.yml` therefore blocks on a human approval after its dry-run
+  job — the delete-adjudication gate this skill's hardened-deploy design
+  assumes. Changing the reviewer set is operator-only (repo Settings →
+  Environments → `production-site`) — no agent can configure it. Re-check
+  the API output before trusting this line; it drifts with repo settings.
+
 ## Playbook: deploy an update
 
 **Push a tag matching `site-v*`** (or trigger `.github/workflows/deploy-site.yml`
@@ -282,3 +298,25 @@ Add new hosts here as they come online.
 
 Release engineering (`package-release`) builds and publishes artifacts; this
 playbook owns the deploy step that pushes them to the VM.
+
+## Deploy Record — a filled example
+
+The schema lives in SKILL.md's own "The Deploy Record" section; this is a
+worked example (a real cut, `gh run view 29586391343`):
+
+```text
+Deploy Record
+tag / run id:      site-v4 (workflow run 29586391343, 2026-07-17T14:03:15Z)
+dry-run deletes:   see the run's dry-run job log for the class breakdown
+fixture verified:  pass — CI's post-deploy verify step, run marked success
+render verified:   pass — CI's post-deploy verify step, run marked success
+snapshot:          CI pre-deploy hardlink step (deploy-site.yml)
+rollback state:    not-needed
+verdict:           shipped
+```
+
+This example cites the run URL rather than restating its log inline — the
+record's job is to point at the evidence, not transcribe it; re-derive the
+dry-run/fixture/render lines from `gh run view <id> --log` if the detail is
+ever needed, don't assume this filled example's prose stays current with a
+run that already happened.

package/skills/ssr-compatibility/SKILL.md

@@ -2,17 +2,16 @@
 name: ssr-compatibility
 description: >-
   Answers why an AdiaUI component crashes, drops content, or renders wrong
-  under SSR (linkedom/Astro consumers) — the four known failure shapes,
-  what's fixed vs open, how to prove a fix under the linkedom shim gate. Use when
-  asked "does this work under SSR", why a component crashes on
-  attachInternals/ResizeObserver/adoptedStyleSheets/matchMedia/`instanceof Node`
-  under a DOM shim, why
-  table-ui/chart-ui/select-ui or a container CE renders empty or loses its
-  nested children when server-rendered, whether it's safe to call
-  getBoundingClientRect() synchronously in connectedCallback, or whether a
-  browser-API shim/workaround can finally be deleted after a fix ships.
-  ANSWERS only. NOT for implementing a fix (primitive-authoring) or consumer
-  host/hydration wiring (host-wiring, adia-ui-factory plugin).
+  under SSR (linkedom/Astro) — the four known failure shapes, what's fixed
+  vs open, how to prove a fix under the linkedom shim gate. Use for "does
+  this work under SSR", why a component crashes on
+  attachInternals/ResizeObserver/adoptedStyleSheets/matchMedia/`instanceof
+  Node` under a DOM shim, why table-ui/chart-ui/select-ui or a container CE
+  renders empty or drops nested children server-rendered, whether
+  getBoundingClientRect() is safe in connectedCallback, or whether a shim
+  can be deleted after a fix ships. ANSWERS only. NOT for a fix
+  (primitive-authoring) or host/hydration wiring (host-wiring,
+  adia-ui-factory).
 disable-model-invocation: false
 user-invocable: false
 ---
@@ -29,36 +28,14 @@ this" and "what's the state of each shape's fix" — it never carries the fix it
 
 ## The four shapes, in one line each
 
-1. **A browser-only API is called unconditionally → crash.** `attachInternals`,
-   the four Observer constructors, `document.adoptedStyleSheets`. **Fixed** (gh#285).
-2. **`connectedCallback` destructively re-stamps existing DOM → silent content loss.**
-   The ORIGINAL diagnosis, narrowed to a static audit 2026-07-17 (gh#284) — zero
-   shipped components currently pair a non-null template with real light-DOM
-   content, so this specific mechanism isn't exposed today; a forward audit catches
-   a future regression. **Do not stop here** — see shape 2b, the actual live bug
-   found investigating the same report.
-2b. **Custom-element upgrade doesn't replay `attributeChangedCallback` for
-   pre-existing attributes → reflected properties stuck at their class default.**
-   The REAL mechanism behind gh#284's reported symptom. happy-dom and (by strong
-   inference) linkedom both skip the custom-elements spec's upgrade-time
-   attribute replay (§4.13.5 step 6); any `reflect: true` property seeded only
-   from pre-parsed/SSR HTML never initializes. **Fixed 2026-07-18** (gh#284,
-   PR #309) — `connectedCallback` now re-syncs every declared property from its
-   live attribute before `connected()` runs.
-3. **A connect-time layout measurement is treated as confirmed, not unknown.** A zero
-   rect (shim, or real pre-layout connect) drives a wrong persistent decision.
-   **Fixed for one component** (gh#286); the general pattern is unswept.
+1. **A browser-only API is called unconditionally → crash** (`attachInternals`, Observers, `adoptedStyleSheets`). **Fixed** (gh#285).
+2. **`connectedCallback` destructively re-stamps existing DOM → silent content loss.** ORIGINAL diagnosis, narrowed to a static audit 2026-07-17 (gh#284) — doesn't currently expose against any shipped component.
+2b. **Custom-element upgrade doesn't replay `attributeChangedCallback` for pre-existing attributes → reflected properties stuck at class default.** The REAL mechanism behind gh#284's symptom. **Fixed 2026-07-18** (PR #309).
+3. **A connect-time layout measurement is treated as confirmed, not unknown.** **Fixed for one component** (gh#286); the general pattern is unswept.
+4. **Property-only components can't seed initial state from SSR HTML** (gh#288) — a feature gap, **CLOSED 2026-07-18** (table-ui's `data="[…]"` attribute).
 
-A fifth item, **property-only components can't seed initial state from SSR HTML**
-(gh#288), was a feature gap — **CLOSED 2026-07-18**. It was never actually blocked
-on shape 2/2b (table-ui/chart-ui/select-ui all use `static template = () => null`
-too), and the real scope was narrower than filed: `select-ui` already declares
-options via native `<option>` children, `chart-ui` already hydrates `.data` from a
-JSON `data="[…]"` attribute — only `table-ui`'s `.data` had no declarative form,
-now fixed the same way.
-
-Full symptom → root-cause → status detail, cited to the actual shipped/open code:
-[`references/failure-shapes.md`](references/failure-shapes.md).
+Full symptom → root-cause → status detail, cited to the actual shipped/open
+code: [failure-shapes.md](references/failure-shapes.md).
 
 ## Consult table
 
@@ -74,17 +51,12 @@ Full symptom → root-cause → status detail, cited to the actual shipped/open
 
 ## Deviation doctrine
 
-Every fix pattern this pack cites ([`guard-patterns.md`](references/guard-patterns.md))
-carries the reasoning for why it looks the way it does — the no-op `ElementInternals`
-shim exists because leaving the field `undefined` would relocate a crash, not remove
-it; the linkedom shim gate (`scripts/dev/ssr-linkedom-smoke.mjs`, gh#1430) exists
-because happy-dom implements every API in the documented shape-1 cases that linkedom
-lacks (matchMedia, rAF, the Observers, `Node`/`Element` globals, rect APIs), so the
-unit suite is blind to that class by construction — deletion-based testing is the unit-level complement, not
-the proof.
-If a new case doesn't fit an existing pattern's reasoning, that's a signal to design a
-new pattern. Route it through `primitive-authoring` — don't force-fit the nearest existing
-shape.
+Every fix pattern this pack cites ([guard-patterns.md](references/guard-patterns.md))
+carries the reasoning for why it looks the way it does (e.g. the no-op
+`ElementInternals` shim exists because `undefined` would relocate the crash,
+not remove it). If a new case doesn't fit an existing pattern's reasoning,
+that's a signal to design a new pattern — route through `primitive-authoring`,
+don't force-fit the nearest existing shape.
 
 ## Boundaries
 
@@ -104,25 +76,11 @@ shape.
 
 ## Worked example — the answer contract
 
-**Ask:** "`<text-ui>Adia Admin</text-ui>` renders as an empty tag in our SSR output —
-is this a known issue?"
-
-**Answer:** It matches shape 2's SYMPTOM (`connectedCallback` destructively
-re-stamping existing DOM), but shape 2 was narrowed on 2026-07-17 — verify against
-the CURRENT code before reusing the old answer, because this is exactly the case it
-no longer covers. `text-ui`'s `static template` (`packages/web-components/components/text/text.class.js`)
-is `() => null` — `connectedCallback`'s `if (result) stamp(result, this)` never
-enters the branch, so `stamp()` never touches `<text-ui>`'s children at all. This
-component isn't exposed to shape 2; something else is dropping the text — check
-whether `text-ui` is even registered server-side (a different, structural gap: is
-the tag defined before the SSR pass runs?), or whether another mutation (a parent
-re-render, `innerHTML` elsewhere) is clearing it. **The general lesson, not just
-this one component:** before answering "yes, known issue, shape 2" for ANY new
-report, grep the component's own `static template` — if it's the literal
-`() => null`, shape 2 cannot be the cause, no matter how closely the symptom
-matches the old description. [`failure-shapes.md`](references/failure-shapes.md)
-§2 has the full survey (150 components at the 2026-07 survey — the census has since grown) and cites exactly why every
-current children-accepting component is unaffected.
+A "content vanished" report can match shape 2's symptom while shape 2
+itself no longer applies (it was narrowed 2026-07-17) — the general lesson
+(grep the component's `static template` before answering "known issue,
+shape 2") plus a full worked ask/answer are in
+[failure-shapes.md](references/failure-shapes.md) §2's own Worked example.
 
 ## Corpus of record
 

package/skills/ssr-compatibility/references/failure-shapes.md

@@ -131,6 +131,29 @@ the attribute-upgrade-replay gap was real-and-live (now fixed in #309). A
 future "content vanished under SSR" report should check the attribute-replay
 mechanism FIRST — it's the one that was actually firing.
 
+### Worked example — answering a new "content vanished" report
+
+**Ask:** "`<text-ui>Adia Admin</text-ui>` renders as an empty tag in our SSR
+output — is this a known issue?"
+
+**Answer:** It matches shape 2's SYMPTOM (`connectedCallback` destructively
+re-stamping existing DOM), but shape 2 was narrowed on 2026-07-17 — verify
+against the CURRENT code before reusing the old answer, because this is
+exactly the case it no longer covers. `text-ui`'s `static template`
+(`packages/web-components/components/text/text.class.js`) is `() => null` —
+`connectedCallback`'s `if (result) stamp(result, this)` never enters the
+branch, so `stamp()` never touches `<text-ui>`'s children at all. This
+component isn't exposed to shape 2; something else is dropping the text —
+check whether `text-ui` is even registered server-side (a different,
+structural gap: is the tag defined before the SSR pass runs?), or whether
+another mutation (a parent re-render, `innerHTML` elsewhere) is clearing
+it. **The general lesson, not just this one component:** before answering
+"yes, known issue, shape 2" for ANY new report, grep the component's own
+`static template` — if it's the literal `() => null`, shape 2 cannot be the
+cause, no matter how closely the symptom matches the old description. This
+survey (150 components at the 2026-07 survey — the census has since grown)
+cites exactly why every current children-accepting component is unaffected.
+
 ## 3 · A connect-time layout MEASUREMENT is meaningless before real layout exists
 
 **Symptom:** a component makes a decision (a boolean state, a mode, a snapped value)