@adia-ai/adia-ui-factory 0.8.52 → 0.8.54

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.52",
+  "version": "0.8.54",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework \u2014 orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "adia-ui-kit-factory",
-  "version": "0.8.52",
+  "version": "0.8.54",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "author": {
     "name": "Kim",

package/.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "adia-gen-ui": {
       "command": "npx",
-      "args": ["-y", "@adia-ai/mcp@0.8.52", "gen-ui"]
+      "args": ["-y", "@adia-ai/mcp@0.8.54", "gen-ui"]
     }
   }
 }

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog — adia-ui-kit-factory
 
+## [0.8.54] — 2026-08-27
+
+### Added
+- **`references/overlays.md`** — new decision reference grounding the modal-ui/drawer-ui/popover-ui/tooltip-ui/menu-ui/context-menu-ui choice in the primitives' own yaml sidecars, closing a coverage gap in `references/` (tables had table-composition, charts had chart-selection, overlays only had scattered mentions). Carries the mobile-nav-drawer always-in-DOM scoping gotcha (gh#2031) and is wired into `skills/screen-composition/SKILL.md`'s load-when routing table. Closes gh#2031.
+- **`scripts/verify/check-adia-ui-factory-references.mjs`** (repo-root, wired as `check:adia-ui-factory-references`, 93 → 94 gates) — mechanizes the checkable subset of a `references/` drift audit going forward: every `required-for:` skill name resolves to a real `skills/` directory, and every backtick-quoted repo path citation resolves under the repo root or the plugin root.
+
+### Fixed
+- **`references/annotations.yaml`** — flagged the `responsive-shell-sidebar` pattern's own documented state-loss defect (components with local DOM state lose it when the viewport crosses the breakpoint, since the inline copy unmounts while the drawer copy mounts) and points shell leading-nav collapse work at the drawer-relocation approach instead (ADR-0090 supersedes this recipe in practice; the dual-mount recipe stays lawful only for non-shell/non-nav cases). Derived `skills/pattern-catalog/references/pattern-index.md` regenerated to match.
+- **`references/component-model.md`** — still cited the pre-v0.2.0 `AdiaToast`/`AdiaFeed` class names, renamed to `UIToast`/`UIFeed` at v0.2.0 (~80 releases stale).
+- **`references/genui-a2ui.md`** — pointed maintainer-territory edits at `packages/gen-ui/a2ui/compose`; the real path is `packages/gen-ui/engine/compose`. Also fixed a stale `registerResolver` import citing the ancient pre-consolidation `@adia-ai/a2ui-runtime` package name — now `@adia-ai/a2ui`.
+- **`references/mcp-substrate.md`** — package naming two renames behind (gh#1240): the generation MCP is `@adia-ai/mcp`'s `gen-ui` subcommand, not the retired `@adia-ai/gen-ui-mcp`.
+- **`references/llm.md`** — version snapshot stale (v0.7.26 → lockstep current); API surface itself re-verified accurate.
+- **`references/shell-simple.md`** — stylesheet line-count citation wrong (33 → 40).
+- **`references/spa-architecture.md`** — cross-referenced "five" data-flow patterns in `data-and-hydration.md`; it documents six (`createStore()` added later).
+- **`references/agentic-ux-patterns.md`** — `confirm-dialog` → `confirm-dialog-ui` (tag-suffix convention).
+
+### Docs
+- **`references/shell-admin.md`, `shell-chat.md`, `shell-editor.md`** — none mentioned the mobile-nav-drawer persistent-DOM contract (gh#2031); `shell-admin.md` also gained a Subnav-rail pages section (the gh#2143 fix).
+- **`references/ssr-integration.md`** — re-verified all `[D]` claims against live source, refreshed the staleness self-check date stamp; applied the same re-verification date-stamp convention to the other 18 reference files in this tree (`agentic-ux-patterns.md`, `authoring-components.md`, `composed-surface-rubric.md`, `contracts/a2ui-mcp-surface.md`, `contracts/migration-guide-format.md`, `data-and-hydration.md`, `genui-a2ui.md`, `llm.md`, `mcp-substrate.md`, `migration.md`, `overlays.md`, `project-shapes.md`, `shell-embed.md`, `spa-architecture.md`, plus the three shell-* files and `shell-simple.md` above) — following the operator ruling on the coverage-gap review: "if it was identified as a gap, it needs to be addressed" (PR #2157's manual audit had covered all 19 files once already; nothing mechanized re-verification afterward until this cut's new gate).
+- **`references/authoring-components.md`, `data-and-hydration.md`, `project-shapes.md`, `migration.md`, `contracts/*.md`, `composed-surface-rubric.md`** — checked against current `main`, already accurate, date-stamp applied, no content changes.
+
+### Maintenance
+- **`.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.
+
+## [0.8.53] — 2026-08-26
+
+### Changed
+- **`skills/pattern-catalog/references/pattern-index.md` regenerated** (`npm run build:patterns-index`) — mechanical reindex, no skill/agent behavior change this cut.
+
+### Maintenance
+- **Lockstep version bump only.** No other source changes in this package; bumped to maintain the lockstep version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.8.53 work shipped in Framework-wide docs+catalog audit (177 primitives/modules), nav collapsible click-handler bug fix, corpus-wide Related-link sweep (181 fixes), SegmentedControl catalog-rename cascade fix, mobile-nav-drawer consumer contract docs (gh#2032, gh#2031, gh#2068, gh#2076, gh#2116, gh#2133). See `packages/web-components/CHANGELOG.md#0853--2026-08-26` for details.
+- **`.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 `pattern-index.md` regen above; no separate content change.
+
 ## [0.8.52] — 2026-08-25
 
 ### Added

package/README.md

@@ -101,7 +101,7 @@ surface-qa-agent) · `component-model.md` · the `references/contracts/` twins.
 
 ## MCP
 
-`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.52` (tool SoT:
+`adia-gen-ui` server pinned: `@adia-ai/mcp@0.8.54` (tool SoT:
 `packages/gen-ui/mcp/TOOLS.md` — the `gen-ui` section; stability rule in
 `references/contracts/`; pin lives in `.mcp.json` — `check:plugin-count-claims`
 guards this README copy against it). The server is `adia-mcp gen-ui`,

package/hermes-mcp.yaml

@@ -6,5 +6,5 @@ mcp_servers:
     command: "npx"
     args:
       - "-y"
-      - "@adia-ai/mcp@0.8.52"
+      - "@adia-ai/mcp@0.8.54"
       - "gen-ui"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/adia-ui-factory",
-  "version": "0.8.52",
+  "version": "0.8.54",
   "description": "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation.",
   "keywords": [
     "adia-ui",

package/plugin.yaml

@@ -1,4 +1,4 @@
 name: "adia-ui-kit-factory"
-version: "0.8.52"
+version: "0.8.54"
 description: "Author and verify apps built ON the adia-ui (@adia-ai) light-DOM web-component framework — orient, scaffold, compose, wire, verify, and migrate across SPA and SSR rendering modes. Wires the a2ui MCP for catalog retrieval, UI generation, and validation."
 manifest_version: 1

package/references/agentic-ux-patterns.md

@@ -11,6 +11,8 @@ and the user must be able to **understand, control, trust, and recover from** th
 A gen-UI experience that renders validated A2UI but never shows the user what the agent is
 about to do, or how to undo it, is technically working and experientially broken.
 
+(Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
+
 ## The mental model comes first
 
 Before any of the six patterns below, name the frame the user carries into the interaction —
@@ -34,7 +36,7 @@ reason** rather than silently omitting it — a silent omission reads as "not co
 
 | Pattern | Phase | What it requires | AdiaUI realization |
 |---|---|---|---|
-| **Intent preview** | Pre-action | Show the plan *before* execution — the user sees what the agent will do and gets Proceed / Edit / Cancel. Identify where these moments occur and what the preview surface is. | `confirm-dialog` or a `modal-ui` with the planned action steps as a `list-ui`; the three choices as `button-ui` (primary Proceed, ghost Edit, ghost Cancel). For a streamed gen-UI plan, a `card-ui` preview region that the user commits before the runtime serializes. |
+| **Intent preview** | Pre-action | Show the plan *before* execution — the user sees what the agent will do and gets Proceed / Edit / Cancel. Identify where these moments occur and what the preview surface is. | `confirm-dialog-ui` (a `modal-ui` variant) with the planned action steps as a `list-ui`; the three choices as `button-ui` (primary Proceed, ghost Edit, ghost Cancel). For a streamed gen-UI plan, a `card-ui` preview region that the user commits before the runtime serializes. |
 | **Autonomy dial** | Pre-action | Let users calibrate independence **per task type, not globally** — map each task type to its spectrum (suggest-only → act-and-notify). | A per-task-type control surface: `segmented-ui` (suggest / confirm / auto) per row in a settings `list-ui`, or `select-ui` per task. Never one global toggle — that collapses the dimension the pattern exists to expose. |
 | **Explainable rationale** | In-action | The agent grounds its action in user-set context: "Because you selected auto-pay, I charged your card on file." Specify when and where rationale shows. | Inline `text-ui variant="caption"` beneath the acted-on element, or an `alert-ui variant="info"` on the action result. The rationale cites the user's own prior choice, not model internals. |
 | **Confidence signals** | In-action | Disclose uncertainty — specify how (score, copy, visual) and the threshold at which it's surfaced. | A `badge-ui` or `tag-ui` tone tied to a confidence band (never `--a-data-*` series colors — use semantic tones: `success` high, `warning` low); or a `progress-ui` meter for a continuous score. Below the disclosure threshold, escalate (last pattern) rather than proceed silently. |

package/references/authoring-components.md

@@ -1,6 +1,6 @@
 # Authoring a project component
 
-When no catalog primitive composes to the need, author a light-DOM custom element. The discipline below is what separates a component that themes, scales, and survives HMR from one that fights the system. It mirrors the framework's own audit gates — the `adia-lint` hook and the MCP's `check_anti_patterns` mechanize the catchable parts.
+When no catalog primitive composes to the need, author a light-DOM custom element. The discipline below is what separates a component that themes, scales, and survives HMR from one that fights the system. It mirrors the framework's own audit gates — the `adia-lint` hook and the MCP's `check_anti_patterns` mechanize the catchable parts. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## The skeleton
 

package/references/component-model.md

@@ -1,6 +1,6 @@
 # The adia-ui component model
 
-How to _think_ about the catalog. The **live** catalog is the a2ui MCP (`get_component_map`, `lookup_component`, `get_traits`) — query it for exact names, props, and counts; don't memorize them here (they drift per release). This file teaches the vocabulary so the MCP's answers make sense.
+How to _think_ about the catalog. The **live** catalog is the a2ui MCP (`get_component_map`, `lookup_component`, `get_traits`) — query it for exact names, props, and counts; don't memorize them here (they drift per release). This file teaches the vocabulary so the MCP's answers make sense. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## Three tiers
 
@@ -76,7 +76,7 @@ Selection mistakes that keep recurring (verify props with `lookup_component` whe
 - **Card/drawer body content wraps in `<section>`** (canonical order: void media → `<header>` → `<section>`+ → `<footer>`) — direct flow children bypass the body slot and lose the `--card-inset` margin; `<section bleed>` zeros the inset but keeps inline padding.
 - **Clickable grid cards:** wrap the card in `<a href style="display:contents">` — link semantics + keyboard focus without a layout box, so the grid still sees the card as the cell; hover rides `a:hover card-ui`.
 - **No `stretch` on a `<button-ui>` inside a `<col-ui>` action stack** (col-ui already stretches children); `size="lg"` on an action stack applies only when it contains a `variant="primary"` button.
-- **`<toast-ui>` is a facade over `<feed-ui>`** — `AdiaToast.show()` routes to `AdiaFeed.post()`; the top-layer/queue/focus logic lives in the feed component.
+- **`<toast-ui>` is a facade over `<feed-ui>`** — `UIToast.show()` routes to `UIFeed.post()`; the top-layer/queue/focus logic lives in the feed component. (The `Adia<X>` class-name convention this facade predates was swept to `UI<X>` at v0.2.0 — `packages/web-components/CHANGELOG-pre-0.2.0.md`.)
 
 ## Attribute honesty — silent-failure class
 

package/references/composed-surface-rubric.md

@@ -17,6 +17,8 @@ checkable — a named audit/grep/artifact is the evidence) or **[review]** (judg
 the resolved plan + the rendered surface). The a2ui MCP / component yaml is the source of truth
 for primitives and slots — this rubric never restates it.
 
+(Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
+
 ## COMPOSE axis (D1–D4) — assembled correctly, to the resolved intent
 
 | # | Dimension | Type | What it checks | 1 → 3 → 5 |

package/references/contracts/a2ui-mcp-surface.md

@@ -13,6 +13,8 @@ consumer skills drive it. Source of truth for the full tool surface:
 `packages/gen-ui/mcp/TOOLS.md` (the `gen-ui` section — 31 tools, generated from
 `server.js` — update both together).
 
+(Claims re-verified against the kit's live source 2026-08-26 — 31 tools and the consumer-load-bearing subset below confirmed current against `packages/gen-ui/mcp/TOOLS.md`; re-verify on a MINOR cut.)
+
 ## Stability rule (the load-bearing clause)
 
 - **Changing an existing tool's input/output contract is a breaking change for

package/references/contracts/migration-guide-format.md

@@ -8,6 +8,8 @@
 (via `package-release`, on every breaking cut) and the factory CONSUMES (via
 `app-migration`, to drive consumer sweeps). This is the shared shape.
 
+(Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
+
 ## Producer obligations (package-release, per breaking cut)
 
 1. **Version-scope bullet** in the top index: `**\`X.Y.Z\`** — <MINOR/PATCH>

package/references/data-and-hydration.md

@@ -7,7 +7,7 @@ required-for: [data-wiring — all modes]
 
 # Data, state & hydration — patterns
 
-Code shapes for the six data-flow patterns, the three hydration paths, and section wiring. The ownership rules (single-owner · projections-only · attribution) are the `data-wiring` rubric gates.
+Code shapes for the six data-flow patterns, the three hydration paths, and section wiring. The ownership rules (single-owner · projections-only · attribution) are the `data-wiring` rubric gates. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## The six patterns
 

package/references/genui-a2ui.md

@@ -7,7 +7,7 @@ required-for: [gen-ui-wiring — all modes]
 
 # a2ui runtime & corpus — consumer surface
 
-The consumer-facing a2ui runtime (mount + feed + resolve) and corpus (core vs custom). Pipeline internals (compose strategies, zettel scoring, catalog) are maintainer territory — not here. Exact names below; treat as a snapshot (re-bake with the pinned MCP).
+The consumer-facing a2ui runtime (mount + feed + resolve) and corpus (core vs custom). Pipeline internals (compose strategies, zettel scoring, catalog) are maintainer territory — not here. Exact names below; treat as a snapshot (re-bake with the pinned MCP). (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## Render roots
 
@@ -22,7 +22,7 @@ The consumer-facing a2ui runtime (mount + feed + resolve) and corpus (core vs cu
 ```html
 <a2ui-root id="canvas"></a2ui-root>
 <script type="module">
-  import { registerResolver } from '@adia-ai/a2ui-runtime';
+  import { registerResolver } from '@adia-ai/a2ui';
   registerResolver('resource', async (uri) => fetchResource(uri));  // register BEFORE feeding
   document.getElementById('canvas').doc = validatedMessages;        // A2UIMessage[]
 </script>
@@ -45,7 +45,7 @@ A discriminated union the runtime reconciles (set `.doc` to an array of these):
 ## registerResolver
 
 ```js
-import { registerResolver } from '@adia-ai/a2ui-runtime';
+import { registerResolver } from '@adia-ai/a2ui';
 registerResolver('resource', async (uri, params) => { … });   // resolves resource:// → your data
 ```
 
@@ -65,4 +65,4 @@ Built-in schemes: `resource:` (→ a `/api/...` REST convention), `api:` (direct
 
 ## Consumer vs maintainer
 
-Consumer (here): mount roots, register resolvers, call the MCP to generate/validate/refine, use or author a corpus. Maintainer (elsewhere): compose strategies, zettel scoring, the component catalog, embedding-model choice, evals. If you're editing `packages/gen-ui/a2ui/compose/**` or tuning retrieval scoring, you've crossed into maintainer territory.
+Consumer (here): mount roots, register resolvers, call the MCP to generate/validate/refine, use or author a corpus. Maintainer (elsewhere): compose strategies, zettel scoring, the component catalog, embedding-model choice, evals. If you're editing `packages/gen-ui/engine/compose/**` or tuning retrieval scoring, you've crossed into maintainer territory.

package/references/llm.md

@@ -7,7 +7,7 @@ required-for: [llm-wiring]
 
 # `@adia-ai/llm` — the app-side LLM client
 
-Chat / streaming / AI features for a consumer app. Snapshot verified against **@adia-ai/llm v0.7.26**. LLM client surfaces drift — confirm precise field names against the installed version and lean on the **smart-proxy contract** (stable) rather than memorized fields.
+Chat / streaming / AI features for a consumer app. Snapshot verified against **@adia-ai/llm 0.8.53 (lockstep — see `packages/llm/core/package.json`)**. LLM client surfaces drift — confirm precise field names against the installed version and lean on the **smart-proxy contract** (stable) rather than memorized fields. (Version pin re-verified against `packages/llm/core/package.json` 2026-08-26 — still 0.8.53; re-verify on a MINOR cut.)
 
 ## Import & core API
 
@@ -59,4 +59,4 @@ When authoring: default to the smart-proxy pattern; use passthrough only behind
 
 ## Not in the package (don't assume)
 
-Tool/function-calling chunks, structured-output/JSON-schema modes, built-in retry/backoff, and client-side token estimation are **not** surfaced by `@adia-ai/llm` v0.7.26 — handle them in your own server layer. `createAdapter` from `@adia-ai/llm/bridge` is the A2UI generation pipeline's internal LLM adapter; an app rarely calls it directly.
+Tool/function-calling chunks, structured-output/JSON-schema modes, built-in retry/backoff, and client-side token estimation are **not** surfaced by `@adia-ai/llm` — handle them in your own server layer. `createAdapter` from `@adia-ai/llm/bridge` is the A2UI generation pipeline's internal LLM adapter; an app rarely calls it directly.

package/references/mcp-substrate.md

@@ -4,13 +4,18 @@ Background on the generation MCP server that `app-planning` and other consumer-s
 route generative-UI work through. Load when the pinned version, tool roster, or TOOLS.md
 acquisition path is in question.
 
+(Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
+
 ## Authoritative source
 
-The generation MCP (`@adia-ai/gen-ui-mcp`, ADR-0048 P2 — published under the retired name
-`@adia-ai/a2ui-mcp` until the P7 cut) is the authoritative catalog/generator/validator — its
-pinned version is the injected `adia-info` probe's `a2uiMcp.pin` field (never a literal in a
-skill file: a version written into a skill loses a race with every lockstep cut — it happened
-twice).
+The generation MCP now ships as `@adia-ai/mcp`'s `gen-ui` subcommand (`adia-mcp gen-ui`) — one npm
+package, three MCP servers (`gen-ui` / `protocol` / `factory`) under one bin, per gh#1240
+(operator ruling 2026-08-14), which folded the two prior separately-published packages,
+`@adia-ai/gen-ui-mcp` (itself ADR-0048 P2's rename of the retired `@adia-ai/a2ui-mcp`) and
+`@adia-ai/a2ui-protocol-mcp`, into this one distribution before either predecessor name ever
+published a P7 cut. Its pinned version is the injected `adia-info` probe's `a2uiMcp.pin` field
+(never a literal in a skill file: a version written into a skill loses a race with every
+lockstep cut — it happened twice).
 
 ## Tool roster
 

package/references/migration.md

@@ -6,6 +6,8 @@ intentional) is the per-version source of truth; its required shape is
 [`contracts/migration-guide-format.md`](contracts/migration-guide-format.md). Loaded by
 `app-migration` (all migration types). Versions and examples below are a snapshot, not a registry.
 
+(Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
+
 ## Types
 
 - **version-upgrade** — bump `@adia-ai/*` X→Y (lockstep; all packages move together).

package/references/overlays.md

@@ -0,0 +1,103 @@
+---
+name: overlays
+load-when: picking or debugging an overlay surface — modal-ui vs drawer-ui vs popover-ui vs inline disclosure
+load-size: ~1.5k tokens
+required-for: [screen-composition — overlay picks]
+---
+
+# Overlay surfaces — modal-ui vs drawer-ui vs popover-ui vs inline
+
+Four overlay-shaped choices, in order of interruption. This is the decision layer, not a prop
+dump — verify exact props/events with `lookup_component` and compose full surfaces from the
+pattern-catalog entries named below.
+
+(Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
+
+## The decision rule
+
+| Need | Use | Why |
+| --- | --- | --- |
+| Blocking, focus-trapped, short (≤2 fields or one decision), interrupts the task | `modal-ui` | Native `<dialog>` (`showModal()`), centered, `[size]` presets (sm=24rem/md=32rem/lg=48rem), suppresses everything behind it unless `[permanent]` |
+| Edge-anchored, keeps page context, multi-field create/edit or list-detail inspection | `drawer-ui` | Same native-`<dialog>` focus trap as modal-ui but anchored to a `[side]` (left/right/top/bottom) — the list/page stays scrollable behind it conceptually even though the dialog still traps focus while open |
+| Reversible micro-decision anchored to a trigger, non-modal, page stays interactive | `popover-ui` | Popover API (`showPopover()`/`hidePopover()`) + CSS Anchor Positioning — no focus trap, no backdrop blocking the rest of the page |
+| Read-only hover/focus hint, no interaction | `tooltip-ui` | `follows="trigger"` (hover/focus label) or `follows="pointer"` (chart-hover tracking); never for anything the user must act on |
+| Action list from a trigger click | `menu-ui` | The specialized popover: `role=menu` + roving tabindex over `menu-item-ui` children, Popover API under the hood |
+| Action list from a right-click / long-press | `context-menu-ui` | Same item shape as menu-ui (`menu-item-ui` children) but trigger-surface is right-click/long-press, not a button |
+
+Both `modal-ui` and `drawer-ui` are built on the same native-`<dialog>` primitives (portal,
+`::backdrop`, focus-trap, Escape-dismiss) — the only real difference is anchoring (centered vs
+edge) and, correspondingly, the weight of interruption implied. `modal-ui`'s own yaml states
+this directly: "same portal / backdrop / focus-trap / Escape-dismiss primitives as `<drawer-ui>`,
+but anchored to the viewport center with size presets" (`modal.yaml`).
+
+**modal-ui is not the Cmd+K palette.** `<admin-command>` is a bespoke shell-tier component under
+`<admin-shell>`, not a modal-ui composition, even though the visual reads overlay-like
+(`modal.yaml` a2ui rule).
+
+**Nest nothing dialog-shaped inside a popover.** `popover-ui`'s own contract rules this out
+explicitly: "Do NOT nest `<modal-ui>` or `<drawer-ui>` inside `slot="content"`; popovers are
+non-modal anchored surfaces, not dialog hosts. Stacking dialog surfaces inside a popover breaks
+focus management" (`popover.yaml`).
+
+**Popover placement convention (ADR-0034, from `popover.yaml`):** default `bottom` centers under
+the trigger — right for wide pickers (calendar, color, filter forms). `bottom-start` for
+trigger-width menus (action lists, listboxes). `bottom-end` only when the trigger sits at a
+container's right edge by construction. `top-*` when the trigger sits low in the viewport.
+`[offset]` (default 4px) sets the anchor gap.
+
+**`[trigger="hover"]` is for non-essential disclosure only** — never for a popover carrying
+inputs, destructive actions, or anything requiring keyboard interaction (`popover.yaml`). Default
+`[trigger="click"]` for anything interactive.
+
+## Gotchas (verified from source)
+
+- **The mobile-nav-drawer is ALWAYS in the DOM (gh#2031, ADR-0090).** `admin-shell`,
+  `chat-shell`, and `editor-shell` each stamp a persistent `<drawer-ui data-mobile-nav-drawer>` —
+  it is not conditionally created; only its visibility is container-query-driven below the
+  shell's mobile breakpoint (768px for admin-shell/chat-shell, 1024px for editor-shell's leading
+  sidebar). A consumer selector or test that assumes exactly one `drawer-ui`/`dialog` on the page
+  will match this one too — scope past it explicitly, e.g. `:not([data-mobile-nav-drawer])`.
+  This shipped silently in 0.8.52 and broke a real downstream consumer before the docs caught up
+  (`packages/web-modules/CHANGELOG.md`).
+- **Never set `.innerHTML` on a modal-ui/drawer-ui host.** Both wipe the stamped `<dialog>` part
+  and the authored header/section/footer skeleton; mutate a stable inner element inside a
+  persistent `<section>` instead — same rule, same wording, in both yamls.
+- **drawer-ui direct children are structurally enforced.** Must be `<header>`, one-or-more
+  `<section>`, `<footer>`, or an explicit `[slot="header|body|footer"]` element — bare
+  `<col-ui>`/`<row-ui>`/`<div>` at the top level must be wrapped in a `<section>`.
+  `scripts/audit/audit-drawer-structure.mjs` enforces this; bypassing it loses `--drawer-inset`
+  and teaches the gen-UI corpus the wrong pattern.
+- **drawer-ui's `close` event carries a typed reason** (`detail.reason` ∈ `escape` | `backdrop` |
+  `close-button` | `programmatic`) — modal-ui's `close` event does not distinguish dismiss paths.
+  If the surface needs to know *why* it closed (e.g. skip a confirm-discard on Escape but not on
+  backdrop), that's drawer-ui-only today.
+- **popover-ui uses `popover="manual"`, not the browser's `popover="auto"` light-dismiss.** The
+  component wires its own outside-click + Escape handling (deferred one frame past the opening
+  click so the trigger click doesn't self-dismiss). Known Safari quirks at the supported floor
+  (light-dismiss broken 17.0–18.2; virtual-keyboard-on-input persists past 18.3) are tracked in
+  `.claude/docs/BROWSER-COMPAT.md` §3a — don't assume vanilla Popover-API dismiss semantics.
+  `[matchWidth]` sizes the panel to the trigger's width instead of content-width (opt-in).
+- **tooltip-ui is two unrelated modes behind one tag.** `follows="trigger"` (default) is a plain
+  hover/focus label; `follows="pointer"` subscribes to `chart-hover`/`chart-leave` events from a
+  `[for]`-referenced `chart-ui`/`heatmap-ui` and renders a data-viz annotation that tracks the
+  cursor — `[for]` is required in pointer mode or the tooltip renders nothing.
+- **menu-ui vs context-menu-ui have the same item shape, different trigger.** Both consume
+  `menu-item-ui` children and fire an equivalent select event, but menu-ui requires an explicit
+  `slot="trigger"` focusable child while context-menu-ui activates on right-click or a
+  touch long-press (`[duration]`, default 500ms) — don't reach for context-menu-ui just because
+  a design shows a kebab-button dropdown; that's menu-ui.
+- **Sidebar/persistent nav is never menu-ui or context-menu-ui** — `<nav-ui>` + `<nav-item-ui>`
+  own persistent navigation; menu-ui/context-menu-ui are for Popover-API dropdowns only
+  (`component-model.md`, `shell-admin.md`).
+
+## Deeper material
+
+- Full compositions: pattern-catalog's **Alert Dialog** (blocking destructive confirm over
+  modal-ui, WAI alertdialog), **Inline Dialog** (anchored non-modal popover mini-form),
+  **Record Detail Drawer** (side drawer + tabs over a list), and **Form Drawer** (under
+  forms-input — side drawer + sticky footer for create/edit) — search `pattern-catalog`'s
+  pattern index by name before hand-composing any of these shapes.
+- Exact props/events/slots: `mcp__a2ui__lookup_component` — this file states the decision, not
+  the current prop list.
+- Shell-scoped mobile-nav mechanics beyond the gotcha above: `shell-admin.md` / `shell-chat.md` /
+  `shell-editor.md`.

package/references/project-shapes.md

@@ -1,6 +1,6 @@
 # Project shapes & structure
 
-How real adia-ui apps are laid out (synthesized from the chat-ui apps). Three shapes over one four-axis layout, with a page-trio/DUO rule. The **structure rubric** at the bottom is the gate; `scripts/adia-scaffold` mechanizes the layout. Loaded by `app-planning` (shape classifier) and `project-scaffolding` (layout / scaffold / inventory).
+How real adia-ui apps are laid out (synthesized from the chat-ui apps). Three shapes over one four-axis layout, with a page-trio/DUO rule. The **structure rubric** at the bottom is the gate; `scripts/adia-scaffold` mechanizes the layout. Loaded by `app-planning` (shape classifier) and `project-scaffolding` (layout / scaffold / inventory). (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## The four-axis layout (all shapes)
 

package/references/shell-admin.md

@@ -7,7 +7,7 @@ required-for: [shell-selection — admin path]
 
 # admin-shell — the app frame
 
-Full SaaS/admin chrome from `@adia-ai/web-modules`. Register the **cluster barrel**: `import '@adia-ai/web-modules/shell'`.
+Full SaaS/admin chrome from `@adia-ai/web-modules`. Register the **cluster barrel**: `import '@adia-ai/web-modules/shell'`. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## Cluster roster
 
@@ -47,6 +47,16 @@ Full SaaS/admin chrome from `@adia-ai/web-modules`. Register the **cluster barre
 - `<admin-command>` — `open` `shortcut` (`both`|`cmd+k`|`ctrl+k`) `no-shortcut`; `.show()/.hide()`. A `[data-command-trigger]` opens it.
 - Read cross-cutting state off the child: `shell.querySelector('admin-sidebar[slot="leading"]').hasAttribute('collapsed')`; style with `admin-shell:has(admin-sidebar[collapsed]) …`.
 
+## Subnav-rail pages
+
+For a page that needs its own left-rail nav (e.g. a Settings page with Preferences/Account
+sections), stamp `<aside data-subnav>` as the first child of `<admin-scroll>`, followed by
+`<admin-page>`: `admin-scroll` grid-layouts automatically once it detects an unhidden
+`[data-subnav]` sibling — the rail scrolls independently in its own column (`overflow-y: auto`)
+while the content column scrolls separately; neither drags the other out of view. Size the rail
+with `--subnav-width` (default `14rem`). Toggle the rail with the `hidden` attribute, not by
+removing it — the grid layout keys off `[data-subnav]:not([hidden])`.
+
 ## Chrome-tier vs content-tier — the allocation model
 
 The most common admin-shell layout regression is putting **page-tier content in shell-tier
@@ -88,5 +98,6 @@ SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only th
 - **Sidebar nav is `<nav-ui>` + `<nav-item-ui>`**, never `<menu-ui>`/`<menu-item-ui>` — menu-ui is for Popover-API dropdowns, not persistent navigation.
 - **Full-height mount:** an intermediate wrapper (`<main id="app">`) between `body { height: 100dvh; display: flex }` and the shell needs `flex: 1; display: flex; min-height: 0` — without it the flex chain breaks and the shell collapses to content height.
 - **`header-ui` has no CSS of its own** — its icon/heading/description/action grid comes from the parent's `@scope` (`admin-page-header` provides it); bespoke chrome reusing the header-ui vocabulary must supply the grid + text ellipsis locally.
+- **A persistent `<drawer-ui data-mobile-nav-drawer>` is always in the DOM** (relocated mobile-nav mechanism, gh#1984/ADR-0090), not conditionally created — only its visibility responds to a container query at the shell's mobile-nav breakpoint. A selector assuming exactly one `drawer-ui`/`dialog` on the page (e.g. an E2E test) must scope past it: `drawer-ui:not([data-mobile-nav-drawer])`.
 
 Real usage: `apps/saas/app/admin-dashboard/`.

package/references/shell-chat.md

@@ -7,7 +7,7 @@ required-for: [shell-selection — chat path]
 
 # chat-shell — the conversation surface
 
-LLM chat chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-modules/chat'`. The **LLM client/proxy/security** lives in `llm-wiring` — this is the _surface_; that is the _wiring_.
+LLM chat chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-modules/chat'`. The **LLM client/proxy/security** lives in `llm-wiring` — this is the _surface_; that is the _wiring_. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## Cluster roster
 
@@ -45,5 +45,6 @@ Set `proxy-url` (or, dev-only, `apiKey`) and the shell **auto-sends on submit**
 - Legacy shapes (`[data-chat-messages]`, `[data-chat-input]`, `[data-chat-empty]`, `[data-chat-name]`) were retired v0.4.0 — use the bespoke tags (`adia-lint` `LEGACY-SHELL`).
 - SSR: register `<chat-shell>` client-side like any component; keep the key server-side.
 - **Reasoning/trace panels must surface their own reliability** — a bare status label (`Domain: data`) reads identically at 3% and 95% confidence; a label that hides the data needed to judge it is pragmatically deceptive. Show the confidence with the claim.
+- **A persistent `<drawer-ui data-mobile-nav-drawer>` is always in the DOM** (relocated mobile-nav mechanism, gh#1984/ADR-0090), not conditionally created — only its visibility responds to a container query at the shell's mobile-nav breakpoint. A selector assuming exactly one `drawer-ui`/`dialog` on the page (e.g. an E2E test) must scope past it: `drawer-ui:not([data-mobile-nav-drawer])`.
 
 Real usage: `apps/genui/app/factory-chat/`.

package/references/shell-editor.md

@@ -7,7 +7,7 @@ required-for: [shell-selection — editor path]
 
 # editor-shell — the canvas + panes
 
-Design-tool / code-editor chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-modules/editor'`.
+Design-tool / code-editor chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-modules/editor'`. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## Cluster roster
 
@@ -62,5 +62,6 @@ The shell binds **no keyboard shortcuts** — the host owns the chords (focus-mo
 - `<editor-canvas-empty>` is the empty-state slot, not a conditional wrapper — canvas content goes *beside* it, never inside it.
 - Legacy shapes (`[data-editor-body]`, `[data-canvas]`, `data-pane-side/grow`) retired v0.4.0 — use the bespoke tags (`adia-lint` `LEGACY-SHELL`).
 - SSR: swap the canvas content via the framework outlet, not `<router-ui>`.
+- **A persistent `<drawer-ui data-mobile-nav-drawer>` is always in the DOM** (relocated mobile-nav mechanism, gh#1984/ADR-0090), not conditionally created — only its visibility responds to a container query at the shell's mobile-nav breakpoint. A selector assuming exactly one `drawer-ui`/`dialog` on the page (e.g. an E2E test) must scope past it: `drawer-ui:not([data-mobile-nav-drawer])`.
 
 Real usage: `apps/genui/app/a2ui-editor/`.

package/references/shell-embed.md

@@ -7,7 +7,7 @@ required-for: [shell-selection — embed path]
 
 # embed-shell — embedded multi-surface frame
 
-Embedded chrome from `@adia-ai/web-modules` (shell cluster). Register: `import '@adia-ai/web-modules/shell'`. Peer of admin/editor/chat shells; light-DOM, content-agnostic — it orchestrates layout of whatever `[app]` + `[panel]` children it's given, never the content or data.
+Embedded chrome from `@adia-ai/web-modules` (shell cluster). Register: `import '@adia-ai/web-modules/shell'`. Peer of admin/editor/chat shells; light-DOM, content-agnostic — it orchestrates layout of whatever `[app]` + `[panel]` children it's given, never the content or data. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## Cluster roster
 

package/references/shell-simple.md

@@ -7,7 +7,7 @@ required-for: [shell-selection — simple path]
 
 # simple-shell — minimal centered chrome
 
-The lightest shell from `@adia-ai/web-modules` — for marketing, landing, error (404/500/maintenance), thank-you, and auth pages. Register: `import '@adia-ai/web-modules/simple'` (simple is its own cluster barrel — the `/shell` barrel does not register it). Behavior-only host + two CSS-only children.
+The lightest shell from `@adia-ai/web-modules` — for marketing, landing, error (404/500/maintenance), thank-you, and auth pages. Register: `import '@adia-ai/web-modules/simple'` (simple is its own cluster barrel — the `/shell` barrel does not register it). Behavior-only host + two CSS-only children. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## Cluster roster
 
@@ -36,6 +36,6 @@ The lightest shell from `@adia-ai/web-modules` — for marketing, landing, error
 - For an error page, a page-DUO (no `.contents.js`) is usually right — see `project-shapes.md`.
 - **Where the message goes on a status page:** an `<alert-ui>` carries the full message when the user is a *passive* recipient (session expired, account locked); the header `text-ui` carries it when the user is *actively* confirming something they initiated — the alert then only supplements.
 - **Prose/marketing header:** the centered pattern is a `<col-ui>` inside `<header>` with kicker + display heading + deck — not ad-hoc heading stacks.
-- Reach for this canonical shell before hand-rolling centered chrome: a new auth/status/maintenance surface (centered card, brand mark, heading, content) composes `simple-shell` + `<card-ui raw>` — authoring a parallel bespoke shell is how a 117-line stylesheet earns a 33-line replacement.
+- Reach for this canonical shell before hand-rolling centered chrome: a new auth/status/maintenance surface (centered card, brand mark, heading, content) composes `simple-shell` + `<card-ui raw>` — authoring a parallel bespoke shell is how a 100+-line stylesheet earns a 40-line replacement (`simple-shell.css`).
 
 Real usage: `apps/errors/`, `apps/user-flow/` (auth).

package/references/spa-architecture.md

@@ -1,6 +1,6 @@
 # SPA architecture
 
-The client-rendered path: a static host, Vite or vanilla. The framework is SPA-native — components register at load, the page is one document, routing and state live in the browser. Inside Next/Nuxt/SvelteKit/Astro instead? That's the **SSR** path — [ssr-integration.md](ssr-integration.md); the two diverge sharply on registration, routing, and state.
+The client-rendered path: a static host, Vite or vanilla. The framework is SPA-native — components register at load, the page is one document, routing and state live in the browser. Inside Next/Nuxt/SvelteKit/Astro instead? That's the **SSR** path — [ssr-integration.md](ssr-integration.md); the two diverge sharply on registration, routing, and state. (Claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## The host document
 
@@ -85,7 +85,7 @@ A **content-mode** route (one carrying `content`) makes the router fetch and `in
 
 ## Data & state
 
-Owned by `data-wiring` — see [data-and-hydration.md](data-and-hydration.md) for the five data-flow patterns, the DataClient → projection pipeline, the attribution gate (`mutate` throws without an `action_source`), and single-owner state (the route owns the active view; a control mutates the route, an observer/CSS reflects it back — never a second source of truth).
+Owned by `data-wiring` — see [data-and-hydration.md](data-and-hydration.md) for the six data-flow patterns, the DataClient → projection pipeline, the attribution gate (`mutate` throws without an `action_source`), and single-owner state (the route owns the active view; a control mutates the route, an observer/CSS reflects it back — never a second source of truth).
 
 ## Exit gate
 

package/references/ssr-integration.md

@@ -2,7 +2,7 @@
 
 Consuming adia-ui components **inside an SSR framework** (Next.js, Nuxt, SvelteKit, Astro, …). Same components, same UI, **wildly different architecture** from the SPA path — the framework owns routing, registration must be deferred to the client, and state can't live in component-lifetime signals.
 
-> **Honesty about sources.** The kit's own documentation explicitly covers Next/Nuxt/SvelteKit/Astro — those patterns are marked **[D]** (documented) below. Frameworks it names in its routing table but doesn't give wiring for (Remix, Rails/Turbo, Django/HTMX, Phoenix) are marked **[G]** — the _rule_ (one route owner; client-only registration) holds, but the wiring is your framework's standard pattern, not something the kit ships. Don't present **[G]** patterns as kit-guaranteed. ([D] claims verified against the kit's docs 2026-07-16; re-verify on a MINOR cut.)
+> **Honesty about sources.** The kit's own documentation explicitly covers Next/Nuxt/SvelteKit/Astro — those patterns are marked **[D]** (documented) below. Frameworks it names in its routing table but doesn't give wiring for (Remix, Rails/Turbo, Django/HTMX, Phoenix) are marked **[G]** — the _rule_ (one route owner; client-only registration) holds, but the wiring is your framework's standard pattern, not something the kit ships. Don't present **[G]** patterns as kit-guaranteed. ([D] claims re-verified against the kit's live source 2026-08-26; re-verify on a MINOR cut.)
 
 ## Why SSR is different
 

package/skills/pattern-catalog/references/annotations.yaml

@@ -1196,7 +1196,7 @@
   keywords: ["breadcrumb", "navigation", "path", "hierarchy", "link", "separator", "breadcrumb-ui", "trail", "link-ui", "icon-ui"]
 /packages/web-components/patterns/responsive-shell-sidebar/responsive-shell-sidebar.examples.html:
   category: shell-chrome
-  intent: Leading + trailing sidebars that collapse to drawer-ui twins below a 900px viewport breakpoint — dual-mount with signal-shared state and auto-close on widening; reach for it when a shell's rails must survive narrow viewports.
+  intent: Leading + trailing sidebars that collapse to drawer-ui twins below a 900px viewport breakpoint — dual-mount with signal-shared state and auto-close on widening; reach for it when a shell's rails must survive narrow viewports. Flagged (ADR-0090) — this pattern's own README documents a real defect (components with local DOM state lose it when the viewport crosses the breakpoint, since the inline copy unmounts while the drawer copy mounts) and names itself an unfinished stopgap deferred to a "v0.6.0" that was never built. For shell leading-nav collapse specifically, ADR-0090 supersedes this recipe in practice — relocate the live DOM subtree into a drawer-ui off-canvas panel at the canonical breakpoint rung instead of dual-mounting. Prefer drawer-relocation for new shell mobile-nav work; this recipe remains lawful only for non-shell or non-nav sidebar cases where duplicate markup is acceptable.
   keywords:
     - responsive sidebar
     - drawer collapse

package/skills/pattern-catalog/references/pattern-index.md

@@ -261,7 +261,7 @@
   - components: `code-ui`
   - source: `/packages/web-components/patterns/editor-shell/editor-shell.examples.html` · demo: `/packages/web-components/patterns/editor-shell/editor-shell.html` · docs: `/site/patterns/editor-shell`
   - ships: `npm`
-- **Responsive Shell Sidebar** (Patterns) — Leading + trailing sidebars that collapse to drawer-ui twins below a 900px viewport breakpoint — dual-mount with signal-shared state and auto-close on widening; reach for it when a shell's rails must survive narrow viewports.
+- **Responsive Shell Sidebar** (Patterns) — Leading + trailing sidebars that collapse to drawer-ui twins below a 900px viewport breakpoint — dual-mount with signal-shared state and auto-close on widening; reach for it when a shell's rails must survive narrow viewports. Flagged (ADR-0090) — this pattern's own README documents a real defect (components with local DOM state lose it when the viewport crosses the breakpoint, since the inline copy unmounts while the drawer copy mounts) and names itself an unfinished stopgap deferred to a "v0.6.0" that was never built. For shell leading-nav collapse specifically, ADR-0090 supersedes this recipe in practice — relocate the live DOM subtree into a drawer-ui off-canvas panel at the canonical breakpoint rung instead of dual-mounting. Prefer drawer-relocation for new shell mobile-nav work; this recipe remains lawful only for non-shell or non-nav sidebar cases where duplicate markup is acceptable.
   - keywords: responsive sidebar, drawer collapse, breakpoint, dual-mount, mobile shell
   - components: `list-item-ui` `list-ui` `button-ui` `code-ui` `drawer-ui` `pane-ui` `card-ui` `row-ui` `text-ui`
   - source: `/packages/web-components/patterns/responsive-shell-sidebar/responsive-shell-sidebar.examples.html` · demo: `/packages/web-components/patterns/responsive-shell-sidebar/responsive-shell-sidebar.html` · docs: `/site/patterns/responsive-shell-sidebar`
@@ -579,12 +579,12 @@
   - ships: `monorepo-only`
 - **Form Blocks** (Pattern Library) — File upload form with drag and drop zone and file list. Upload-ui with browse fallback, file-type hints, and max-size note.
   - keywords: file, upload, drag-and-drop, dnd, browse, attachments, form-input, drop, zone, file-list
-  - components: `field-ui` `button-ui` `col-ui` `text-ui` `input-ui` `row-ui` `card-ui` `tag-ui` `radio-ui` `calendar-picker-ui` `check-ui` `grid-ui` `icon-ui` `select-ui` `textarea-ui` `search-ui` `step-progress-ui` `time-picker-ui` `upload-ui`
+  - components: `field-ui` `button-ui` `col-ui` `text-ui` `input-ui` `row-ui` `card-ui` `tag-ui` `radio-ui` `calendar-picker-ui` `check-ui` `grid-ui` `icon-ui` `select-ui` `textarea-ui` `radio-group-ui` `search-ui` `step-progress-ui` `time-picker-ui` `upload-ui`
   - source: `/catalog/ui-patterns/v050-form-blocks/v050-form-blocks.contents.html` · demo: `/catalog/ui-patterns/v050-form-blocks/v050-form-blocks.html` · docs: `/site/examples/patterns/v050-form-blocks`
   - ships: `monorepo-only`
 - **Accordion Settings** (Pattern Library) — Settings panel organized as accordion — expandable sections (profile / notifications / privacy / advanced) each containing form controls.
   - keywords: accordion, settings, collapsible, expandable, sections, preferences, profile, notifications, privacy
-  - components: `field-ui` `accordion-item-ui` `toggle-ui` `col-ui` `input-ui` `accordion-ui`
+  - components: `accordion-item-ui` `switch-ui` `col-ui` `field-ui` `input-ui` `accordion-ui`
   - source: `/catalog/ui-patterns/app/accordion-settings/accordion-settings.contents.html` · demo: `/catalog/ui-patterns/app/accordion-settings/accordion-settings.html` · docs: `/site/examples/patterns/accordion-settings`
   - ships: `monorepo-only`
 - **Image Upload Preview** (Pattern Library) — Image upload with preview thumbnail, file metadata, and replace/remove actions.

package/skills/screen-composition/SKILL.md

@@ -92,6 +92,7 @@ composing or debugging a "renders wrong" report.
 | --- | --- |
 | PRD/spec/mockup/schema/user-story input | no reference here (gh#1207 — moved planning-side); check Orientation Record's Domain Plan (Precondition above) |
 | Picking/wiring primitives; "it renders wrong" | [`references/composition-traps.md`](references/composition-traps.md) |
+| Overlay-surface picks (modal/drawer/popover/tooltip/menu) | [`../../references/overlays.md`](../../references/overlays.md) |
 | `adia-info` field meaning | [`references/project-context-fields.md`](references/project-context-fields.md) |
 | Operator-facing inspection surface (gallery, eval browser, audit/drift) | [`references/meta-surfaces.md`](references/meta-surfaces.md) |
 | Authoring a project component | [`../../references/authoring-components.md`](../../references/authoring-components.md) |