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

package/skills/package-release/references/authorization-model.md

@@ -0,0 +1,34 @@
+# Authorization model — history and mechanics
+
+SKILL.md's own "Authorization" section states the rule; this is the history
+and the mechanism behind it.
+
+## Why single-authorization replaced the checkpoint ceremony
+
+This replaced the 4-checkpoint sign-off ceremony after the v0.8.5 cut
+(2026-07-17): ~40 minutes of approval relays that produced zero safety —
+every real protection had already fired deterministically (the
+`release-pretag-docs-gate` hook, the pre-push F-N1 trip-wire, the
+one-tag-per-push rule, the registry verify). Those deterministic gates are
+untouched and remain non-skippable: **an F-N1 error hard-stops
+unconditionally — no flag, no instruction wording, bypasses it.**
+
+## Why releases run inline, not dispatched
+
+**Releases run INLINE in the operator's session by default.** Do not
+dispatch a subagent to run an interactive release — a dispatched seat cannot
+receive the operator's words directly, which the v0.8.5 cut proved
+structurally deadlocks on any consent question (the relay-refusal loop). The
+`package-release-agent` agent exists for UNATTENDED contexts only
+(scheduled/batch/CI cuts), where the dispatch itself carries the operator's
+authorization.
+
+## Mechanics
+
+`release-pack.mjs --go` auto-confirms all checkpoints (it equals
+`--yes --push --publish`); the evidence blocks still print as a log — the
+audit trail survives, nothing waits on input. The granular flags remain for
+cautious manual runs; interactive prompts fire for whatever flag is absent.
+A cosmetic F-N1 warn still refuses auto-confirmation at the push boundary —
+with Step 4f (mechanized pre-tag coverage) warns should be extinct, so one
+appearing means something novel: treat it as a gate failure, not ceremony.

package/skills/package-release/references/invariants-detail.md

@@ -0,0 +1,61 @@
+# Invariants — detail and history
+
+SKILL.md's own "Invariants" section states each rule; this expands the
+history and mechanics behind the denser ones.
+
+## 1. Lockstep coherence
+
+Every roster package bumps together (`check:lockstep`). **The roster is
+`scripts/package-paths.mjs`'s `PACKAGE_ROSTER` — read it, never a copy.**
+This line used to enumerate the names inline and went stale the first time
+the roster moved (ADR-0048 P4 added a package while the list still read the
+pre-split six); a name list has no gate behind it, so it can only decay.
+Each plugin's `.claude-plugin/plugin.json` version moves with its
+package.json — `bump.mjs` handles both; `verify:plugins` gates the sync.
+
+## 2. PATCH-cut asymmetry
+
+Internal `@adia-ai/*` ranges hold at `^X.Y.0` during PATCH cuts; only MINOR
+bumps the floor. `^0.0.x` is forbidden (pre-1.0 caret locks exact — shipped
+a real stale-sibling bug).
+
+## 3. Release commits land via PR, never a direct push to `main`
+
+(Repo policy, operator ruling 2026-07-12.) Commit on `release/vX.Y.Z` → PR →
+CI → merge — THEN tag at `main`'s post-merge HEAD, not at the bump commit;
+post-bump fixes merge before tagging and belong in the tarball. Exception:
+batch push tags each version at its own release-merge SHA.
+
+## 4. One umbrella + one per-package tag per cut
+
+One per lockstep-roster package (`scripts/package-paths.mjs`); publish
+workflows key off the per-package tags. Push tags **one per `git push`** — a
+batched multi-tag push drops the trigger event.
+
+## 5. F-N1 per-package clean
+
+`check:release --all-pending` — the umbrella-tag mismatch error is expected
+noise. Coverage is mechanized at cut time: Step 4f
+(`check-release.mjs --pending-version X.Y.Z --fix`) runs the SAME matcher
+pre-PR and auto-appends verified Maintenance bullets, so a post-tag warn
+means something novel — stop and investigate, don't loop enrichment PRs.
+
+## 6. `npm dist-tag latest` is set by publish order
+
+Batch pushes publish oldest first and WAIT for settle.
+
+## 7. A breaking (MINOR) cut MUST ship its MIGRATION GUIDE section in the same cycle
+
+MINOR is reserved for removed/renamed API symbols; everything else,
+including visible behavior changes, stays PATCH.
+
+## 8. The adia-factory plugin's `.mcp.json` pins the generation MCP exactly
+
+Bump the pin in `packages/plugins/adia-ui-factory/.mcp.json` in the same cut
+(the consumer never floats; with the plugins in-lockstep this lands in the
+release commit itself, not a follow-up). The pinned NAME is `@adia-ai/mcp`
+with the `gen-ui` subcommand (`npx -y @adia-ai/mcp@<exact> gen-ui`) — the
+single live name since the ADR-0048 P7 cut (v0.8.37) per the gh#1240
+one-package amendment; `@adia-ai/a2ui-mcp` is retired and the P2-planned
+`@adia-ai/gen-ui-mcp` never published. `check:lockstep`'s mcp-pin guard and
+`bump.mjs` both enforce this pin.

package/skills/package-release/references/mechanization.md

@@ -0,0 +1,54 @@
+# Mechanization — bundled `scripts/`, stdlib Node, all support `--dry`
+
+`release-pack.mjs` walks the cycle in two phases per invariant 3 — `--mode
+cut` / `--mode from-scratch` promote `[Unreleased]` (BOTH modes now — a
+peer's hand-authored section must be promoted whichever mode cut it, and a
+loud guard blocks the bump if any roster package still carries non-empty
+`[Unreleased]` content after promotion), run Step 4f (pre-tag coverage
+`--fix` with the authoritative F-N1 matcher), and stop at the release commit
+(PR → merge); `--mode handoff` tags/publishes/deploys from post-merge main.
+**`--go` is the standard invocation for an operator-initiated release** — the
+single authorization covers the cycle; evidence blocks print as a log;
+granular `--yes`/`--push`/`--publish` remain for cautious manual runs
+(`--push` still refuses to auto-fire past any F-N1 finding). `--mode batch`
+is not implemented — it hard-rejects with a pointer to
+[recovery-paths.md](recovery-paths.md) §Scenario 2 rather than silently
+misbehaving; a real batch tags each version at its own release-merge SHA,
+which this single-version orchestrator has no model for. Pre-flight (Step 3)
+runs the full 30-gate roster from the single shared list in
+`scripts/gate-roster.mjs` — the same list [cut-procedure.md](cut-procedure.md)
+§3.1 transcribes, so a subset run requires editing that one file, not two.
+
+The pieces are callable alone: `bump.mjs` (version fields + the factory
+`.mcp.json` `@adia-ai/mcp` pin, invariant 8), `promote-unreleased.mjs` /
+`insert-stub.mjs` (CHANGELOG blocks), `tag-lockstep.mjs` (umbrella + one tag
+per lockstep roster package — the set is derived from `PACKAGE_ROSTER`,
+never a number written here: it went stale at 14 while the roster said 17,
+17 went stale in turn when gh#1240 folded two planned MCP rows into one
+(now 16), and 16 goes stale again the day the ADR-0048 shims retire; run
+`--dry` to see the live list, `--delete` to move), `dispatch-publish.mjs`
+(publish workflows; `--verify-triggered` re-dispatches missing AND dead —
+cancelled/failed/timed-out — runs, each gated behind an npm-registry check
+so an already-published version is never re-dispatched (gh#763); `--after`
+enforces batch ordering — dispatch output states what WAS done, never a
+to-do phrased as if it hadn't fired), and `pr-bridge.mjs` (the two-phase
+bridge: pushes the release branch, opens the PR, waits out CI, and merges
+ONLY on all-non-fail-soft-checks-green + zero unresolved threads + no
+changes-requested; any other state stops with evidence — §5.7 mechanized,
+`--dry` to preview the decision). All fail fast outside a monorepo root
+(`assert-monorepo-root.mjs`); fork-configurable via `--host` / `--scope`.
+All 6 CLI scripts (plus `scripts/release/check-release.mjs`) have a
+`selftest` mode wired into CI's Plugin bin selftests step; the 3 helper
+modules (`assert-monorepo-root`, `gate-roster`, `package-paths`) are
+exercised through the CLIs' selftests, not their own.
+
+## Site deploy
+
+Site deploy (Step 10 of the handoff) dispatches `deploy-site.yml` (its own
+pre-flight verify → snapshot → hardened rsync → post-deploy verify →
+auto-rollback), never a raw local `rsync` — H1 (forge-campaign gh#268
+audit): the script had drifted into bypassing that pipeline even though this
+doc already taught the workflow-dispatch path. The dispatch rides the
+cycle's single authorization (`--go`, or `--publish` on a manual run); the
+workflow's own GitHub environment gate is the human stop for the deploy
+itself.

package/skills/package-release/references/recovery-paths.md

@@ -9,6 +9,16 @@
 
 ---
 
+## §Scenario 0 — Recon: classifying an unclear starting state
+
+`git branch --show-current` (must be `main`) · `git status --short` ·
+`git log origin/main..HEAD --oneline` · `git tag --list 'vX.Y.*'` ·
+CHANGELOG heads for `## [Unreleased]`. One unpushed `release(*):` commit →
+deploy handoff · several → batch push (Scenario 2) · `[Unreleased]`, no
+bump → author from scratch · removed/renamed API symbol → breaking cut,
+guide owed · target under `packages/plugins/*` → independent release.
+Ambiguous → surface it, don't guess.
+
 ## §Scenario 1 — Version-skip correction
 
 **Shape:** a peer's release commit mislabels the version — package.json bumped 0.6.X → 0.6.X+2, skipping X+1; the CHANGELOG body may narrate the work as two releases. No tags yet, npm latest still 0.6.X, commit unpushed. (Real case: a "v0.6.13" cut that was actually v0.6.12's work.)

package/skills/primitive-authoring/SKILL.md

@@ -3,16 +3,14 @@ name: primitive-authoring
 description: >-
   Author or modify AdiaUI framework source inside the monorepo — primitives
   (packages/web-components), shells/composites (packages/web-modules), yaml
-  SoTs, demos. Use when asked to add a new primitive component, add or fix a prop/slot/
-  attribute/CSS variant, update a component's yaml, build or fix a shell
-  (chat-shell, admin-shell, editor-shell — sidebar/pane/bespoke-tier
-  composition), promote or extract repeated inline content into a shared
-  module, audit a component's four-axis contract/token usage/lifecycle
-  (connected/disconnected symmetry) for drift, or author/write a demo or
-  examples.html for a component or composite. NOT for composing app screens
-  from primitives (screen-composition), A2UI pipeline internals (a2ui-maintenance),
-  @adia-ai/llm adapter/streaming/bridge internals (llm-client-maintenance), or
-  site/pages docs pages (site-docs-authoring).
+  SoTs, demos. Use to add a new primitive, fix a prop/slot/attribute/CSS
+  variant, update a yaml, build or fix a shell (chat-shell, admin-shell,
+  editor-shell — sidebar/pane/bespoke-tier composition), promote repeated
+  inline content into a shared module, audit a component's four-axis
+  contract/token usage/lifecycle for drift, or author a demo or
+  examples.html. NOT for app screens (screen-composition), A2UI internals
+  (a2ui-maintenance), @adia-ai/llm internals (llm-client-maintenance), or
+  site/pages docs (site-docs-authoring).
 disable-model-invocation: false
 user-invocable: true
 ---
@@ -58,28 +56,11 @@ citation mechanically on every web-modules demo write; the
 
 ## First principles
 
-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.
+Invariants are enforced by the next author, not the linter; default behavior
+is the absent attribute; variants change tokens while modes change layout;
+symmetric lifecycle or it's a leak; component tokens consume L3, not L2.
+Each expanded, with examples, in
+[code-style.md](references/code-style.md)'s First principles section.
 
 ## Verify targets (named before executing)
 

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

@@ -18,10 +18,30 @@ static properties = {
 **Field rules:**
 
 - `type` — one of `String`, `Number`, `Boolean`, `Object`, `Array`. The runtime uses this to coerce attribute strings into typed values.
-- `default` — the value the prop takes when no attribute is present AND no JS value has been assigned. For `Boolean` props, default is ALWAYS `false` (see rule 1). For numeric props, default is `0`, a real value, or `null` for indeterminate — NEVER a sentinel like `-1`.
+- `default` — the value the prop takes when no attribute is present AND no JS value has been assigned. For `Boolean` props, default is `false` in the standard shape (see rule 1); `default: true` is a rare, ratified exception carried by connect-time attribute stamping (ADR-0075, gh#961) — never the default shape to reach for. For numeric props, default is `0`, a real value, or `null` for indeterminate — NEVER a sentinel like `-1`.
 - `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:
@@ -40,7 +60,7 @@ Use `attribute:` verbatim. If you think you're writing `attr:`, stop and correct
 
 ## Boolean prop naming — the flip rule
 
-AdiaUI conventions require `default: false` on all Booleans. The naming follows:
+AdiaUI conventions require `default: false` on Boolean props in the standard shape, unless a ratified exception applies (ADR-0075's connect-time attribute stamping, gh#961 — a rare exception, not a route open to new work). The naming follows:
 
 | Intended default behavior | Wrong name (default:true) | Right name (default:false) |
 | --- | --- | --- |
@@ -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/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,12 +179,72 @@ 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`.
+- **[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
 
 If you add a new token category (like `--a-chrome-*` was added), update both this file and `.claude/docs/specs/component-token-contract.md`. The spec doc is the live source of truth; this file is the practitioner's checklist.

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