@adia-ai/a2ui-corpus 0.3.2 → 0.3.3

package/chunks/reg-usecase-picker.json

@@ -12,5 +12,5 @@
   },
   "html": "<section data-reg-form role=\"radiogroup\" aria-label=\"Use case\">\n          <col-ui gap=\"2\">\n            <option-card-ui\n              name=\"use-case\"\n              value=\"build\"\n              checked\n              heading=\"I'm building a product\"\n              description=\"Spinning up a new project — design, ship, iterate.\"\n            ></option-card-ui>\n            <option-card-ui\n              name=\"use-case\"\n              value=\"explore\"\n              heading=\"I'm exploring the product\"\n              description=\"Kicking the tires before bringing a team along.\"\n            ></option-card-ui>\n            <option-card-ui\n              name=\"use-case\"\n              value=\"migrate\"\n              heading=\"I'm migrating from another tool\"\n              description=\"Moving an existing workspace and want a smooth port.\"\n            ></option-card-ui>\n            <option-card-ui\n              name=\"use-case\"\n              value=\"evaluate\"\n              heading=\"I'm evaluating for my team\"\n              description=\"Comparing options and want to dig into specifics.\"\n            ></option-card-ui>\n            <option-card-ui name=\"use-case\" value=\"other\" heading=\"Something else\" description=\"Tell us more — we read every response.\">\n              <textarea-ui name=\"use-case-detail\" placeholder=\"What brings you to AdiaUI?\" rows=\"3\"></textarea-ui>\n            </option-card-ui>\n          </col-ui>\n        </section>",
   "source": "apps/user-flow/app/registration/use-case/use-case.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/reg-workspace-name.json

@@ -16,5 +16,5 @@
   },
   "html": "<form data-reg-input action=\"/site/examples/registration/profile\" method=\"get\">\n        <header data-reg-heading><!-- nested: reg-step-header --></header>\n\n        <section data-reg-form>\n          <field-ui inline label=\"Workspace Name\" hint=\"Letters, numbers, and spaces.\">\n            <input-ui name=\"workspace\" autocomplete=\"organization\" placeholder=\"Acme, Inc.\" required></input-ui>\n          </field-ui>\n          <field-ui inline label=\"Workspace URL\" hint=\"your-workspace.adia.ai\">\n            <input-ui name=\"slug\" autocomplete=\"off\" placeholder=\"acme\" suffix=\".adia.ai\" required></input-ui>\n          </field-ui>\n        </section>\n\n        <footer><!-- nested: reg-step-footer --></footer>\n      </form>",
   "source": "apps/user-flow/app/registration/workspace/workspace.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/settings-billing-plan.json

@@ -10,5 +10,5 @@
   },
   "html": "<div data-col>\n      <card-ui size=\"sm\">\n        <header>\n          <span slot=\"icon\">\n            <avatar-ui icon=\"star\"></avatar-ui>\n          </span>\n          <span slot=\"heading\">\n            <text-ui strong>Pro</text-ui>\n            <badge-ui text=\"Current\" variant=\"accent\"></badge-ui>\n          </span>\n          <span slot=\"action\">\n            <button-ui text=\"Change plan\" variant=\"primary\" size=\"sm\" onclick=\"document.getElementById('drawer-change-plan').open = true\"></button-ui>\n          </span>\n          <span slot=\"description\">\n            <text-ui color=\"subtle\" size=\"sm\">$49/month · billed monthly · Next invoice May 14, 2026</text-ui>\n          </span>\n        </header>\n      </card-ui>\n      <field-ui label=\"Billing interval\">\n        <segmented-ui value=\"monthly\">\n          <segment-ui value=\"monthly\" text=\"Monthly\"></segment-ui>\n          <segment-ui value=\"annual\" text=\"Annual · 2 months free\"></segment-ui>\n        </segmented-ui>\n      </field-ui>\n    </div>",
   "source": "apps/saas/app/billing/billing.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/settings-general-form.json

@@ -10,5 +10,5 @@
   },
   "html": "<div data-col>\n      <field-ui label=\"Workspace name\">\n        <input-ui placeholder=\"My Workspace\" value=\"AdiaUI\"></input-ui>\n      </field-ui>\n      <field-ui label=\"Slug\">\n        <input-ui prefix=\"/\" placeholder=\"my-workspace\" value=\"adia-ui\"></input-ui>\n      </field-ui>\n    </div>",
   "source": "apps/saas/app/settings-page/settings-page.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/settings-integrations.json

@@ -10,5 +10,5 @@
   },
   "html": "<div data-col>\n      <card-ui size=\"sm\">\n        <header>\n          <span slot=\"icon\">\n            <avatar-ui icon=\"slack-logo\"></avatar-ui>\n          </span>\n          <span slot=\"heading\">\n            <text-ui strong>Slack</text-ui>\n            <badge-ui text=\"Connected\" variant=\"success\"></badge-ui>\n          </span>\n          <span slot=\"action\">\n            <button-ui text=\"Configure\" onclick=\"document.getElementById('drawer-slack').open = true\"></button-ui>\n          </span>\n          <span slot=\"description\">\n            <text-ui color=\"subtle\" size=\"sm\">Posts to #product-updates · connected by Alex Chen</text-ui>\n          </span>\n        </header>\n      </card-ui>\n      <card-ui size=\"sm\">\n        <header>\n          <span slot=\"icon\">\n            <avatar-ui icon=\"github-logo\"></avatar-ui>\n          </span>\n          <span slot=\"heading\">\n            <text-ui strong>GitHub</text-ui>\n            <badge-ui text=\"Connected\" variant=\"success\"></badge-ui>\n          </span>\n          <span slot=\"action\">\n            <button-ui text=\"Configure\" onclick=\"document.getElementById('drawer-github').open = true\"></button-ui>\n          </span>\n          <span slot=\"description\">\n            <text-ui color=\"subtle\" size=\"sm\">acme-corp organization · 14 repositories synced</text-ui>\n          </span>\n        </header>\n      </card-ui>\n      <card-ui size=\"sm\">\n        <header>\n          <span slot=\"icon\">\n            <avatar-ui icon=\"envelope\"></avatar-ui>\n          </span>\n          <span slot=\"heading\">\n            <text-ui strong>Email (SMTP)</text-ui>\n            <badge-ui text=\"Action needed\" variant=\"warning\"></badge-ui>\n          </span>\n          <span slot=\"action\">\n            <button-ui text=\"Reconnect\" variant=\"primary\" onclick=\"document.getElementById('drawer-smtp').open = true\"></button-ui>\n          </span>\n          <span slot=\"description\">\n            <text-ui color=\"subtle\" size=\"sm\">Credentials expired on April 12, 2026</text-ui>\n          </span>\n        </header>\n      </card-ui>\n    </div>",
   "source": "apps/saas/app/integrations/integrations.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/settings-members-invite.json

@@ -10,5 +10,5 @@
   },
   "html": "<div data-col>\n      <field-ui label=\"Email addresses\">\n        <textarea-ui placeholder=\"alex@acme.com, sarah@acme.com (comma or newline separated)\" rows=\"3\"></textarea-ui>\n      </field-ui>\n      <field-ui label=\"Default role\">\n        <select-ui value=\"member\">\n          <option value=\"admin\">Admin · can invite, remove, and billing</option>\n          <option value=\"member\">Member · can edit and invite</option>\n          <option value=\"viewer\">Viewer · read-only</option>\n        </select-ui>\n      </field-ui>\n      <field-ui label=\"Send welcome email\" inline>\n        <switch-ui checked></switch-ui>\n      </field-ui>\n      <button-ui text=\"Send invites\" variant=\"primary\" icon=\"paper-plane-tilt\"></button-ui>\n    </div>",
   "source": "apps/saas/app/members/members.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/settings-notifications.json

@@ -8,5 +8,5 @@
   "attrs": {},
   "html": "<card-ui>\n  <header>\n    <h3>Notifications</h3>\n    <text-ui slot=\"description\" color=\"subtle\">Choose what you want to be notified about</text-ui>\n  </header>\n  <section>\n    <col-ui gap=\"4\">\n      <section>\n        <text-ui weight=\"semibold\">Email</text-ui>\n        <col-ui gap=\"2\">\n          <row-ui gap=\"2\" align=\"center\" justify=\"space-between\">\n            <text-ui>Weekly digest</text-ui>\n            <switch-ui checked></switch-ui>\n          </row-ui>\n          <row-ui gap=\"2\" align=\"center\" justify=\"space-between\">\n            <text-ui>New mentions</text-ui>\n            <switch-ui checked></switch-ui>\n          </row-ui>\n          <row-ui gap=\"2\" align=\"center\" justify=\"space-between\">\n            <text-ui>Product updates</text-ui>\n            <switch-ui></switch-ui>\n          </row-ui>\n        </col-ui>\n      </section>\n      <divider-ui></divider-ui>\n      <section>\n        <text-ui weight=\"semibold\">Push</text-ui>\n        <col-ui gap=\"2\">\n          <row-ui gap=\"2\" align=\"center\" justify=\"space-between\">\n            <text-ui>Direct messages</text-ui>\n            <switch-ui checked></switch-ui>\n          </row-ui>\n          <row-ui gap=\"2\" align=\"center\" justify=\"space-between\">\n            <text-ui>Team alerts</text-ui>\n            <switch-ui></switch-ui>\n          </row-ui>\n        </col-ui>\n      </section>\n    </col-ui>\n  </section>\n</card-ui>",
   "source": "apps/patterns/app/settings-notifications/settings-notifications.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/settings-page-shell.json

@@ -24,5 +24,5 @@
   "attrs": {},
   "html": "<article>\n  <header data-chunk-slot=\"page-header\">\n    <h1>Settings</h1>\n    <text-ui color=\"subtle\">Manage your account preferences</text-ui>\n  </header>\n\n  <tabs-ui value=\"general\" data-chunk-slot=\"page-tabs\">\n    <tab-ui value=\"general\" text=\"General\"></tab-ui>\n    <tab-ui value=\"integrations\" text=\"Integrations\"></tab-ui>\n    <tab-ui value=\"billing\" text=\"Billing\"></tab-ui>\n  </tabs-ui>\n\n  <section data-chunk-slot=\"page-content\">\n    <card-ui>\n      <header><h3>General settings</h3></header>\n      <section>\n        <field-ui label=\"Display name\">\n          <input-ui value=\"Jane Doe\"></input-ui>\n        </field-ui>\n        <field-ui label=\"Email\" hint=\"Used for notifications\">\n          <input-ui type=\"email\" value=\"jane@example.com\"></input-ui>\n        </field-ui>\n      </section>\n    </card-ui>\n  </section>\n</article>",
   "source": "apps/generic-shells/app/settings-page/settings-page.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/settings-profile-security.json

@@ -10,5 +10,5 @@
   },
   "html": "<div data-col>\n      <row-ui gap=\"4\" align=\"center\">\n        <avatar-ui text=\"Kim Granlund\" size=\"xl\"></avatar-ui>\n        <col-ui gap=\"2\">\n          <field-ui label=\"Upload new avatar\">\n            <upload-ui accept=\"image/*\"></upload-ui>\n          </field-ui>\n          <text-ui color=\"subtle\" size=\"sm\">JPG, PNG or WebP. Max 2 MB. Square images render best.</text-ui>\n        </col-ui>\n      </row-ui>\n      <field-ui label=\"Full name\">\n        <input-ui value=\"Kim Granlund\"></input-ui>\n      </field-ui>\n      <field-ui label=\"Display name\">\n        <input-ui value=\"kimba\" prefix=\"@\"></input-ui>\n      </field-ui>\n      <field-ui label=\"Email\">\n        <input-ui value=\"kim@acme.com\" type=\"email\"></input-ui>\n      </field-ui>\n      <field-ui label=\"Bio\">\n        <textarea-ui placeholder=\"Tell the team a bit about yourself\" rows=\"3\">Product engineer. Working on the gen-UI pipeline.</textarea-ui>\n      </field-ui>\n    </div>",
   "source": "apps/saas/app/profile-security/profile-security.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/user-profile-card.json

@@ -8,5 +8,5 @@
   "attrs": {},
   "html": "<card-ui>\n  <header>\n    <row-ui gap=\"3\" align=\"center\">\n      <avatar-ui text=\"Jane Doe\" size=\"lg\"></avatar-ui>\n      <col-ui gap=\"0\">\n        <text-ui weight=\"semibold\" size=\"lg\">Jane Doe</text-ui>\n        <text-ui color=\"subtle\">Product Designer</text-ui>\n      </col-ui>\n    </row-ui>\n  </header>\n  <section>\n    <col-ui gap=\"3\">\n      <field-ui label=\"Email\" inline>\n        <input-ui type=\"email\" value=\"jane@example.com\"></input-ui>\n      </field-ui>\n      <field-ui label=\"Role\" inline>\n        <select-ui value=\"designer\">\n          <option value=\"designer\">Designer</option>\n          <option value=\"engineer\">Engineer</option>\n          <option value=\"manager\">Manager</option>\n        </select-ui>\n      </field-ui>\n      <field-ui label=\"Bio\" inline>\n        <textarea-ui rows=\"2\">Building design systems at AdiaUI</textarea-ui>\n      </field-ui>\n    </col-ui>\n  </section>\n  <footer>\n    <row-ui gap=\"2\" justify=\"end\">\n      <button-ui text=\"Cancel\" variant=\"ghost\" size=\"sm\"></button-ui>\n      <button-ui text=\"Save\" variant=\"primary\" size=\"sm\"></button-ui>\n    </row-ui>\n  </footer>\n</card-ui>",
   "source": "apps/patterns/app/user-profile-card/user-profile-card.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/chunks/users-table-badge.json

@@ -8,5 +8,5 @@
   "attrs": {},
   "html": "<card-ui>\n  <header>\n    <h3>Users</h3>\n    <text-ui slot=\"description\" color=\"subtle\">Team members and their roles</text-ui>\n  </header>\n  <section bleed>\n    <table-ui>\n      <thead>\n        <tr>\n          <th>User</th>\n          <th>Role</th>\n          <th>Status</th>\n          <th>Last active</th>\n        </tr>\n      </thead>\n      <tbody>\n        <tr>\n          <td><row-ui gap=\"2\" align=\"center\"><avatar-ui text=\"Alex Chen\" size=\"sm\"></avatar-ui><text-ui>Alex Chen</text-ui></row-ui></td>\n          <td><badge-ui text=\"Admin\" variant=\"accent\" size=\"sm\"></badge-ui></td>\n          <td><badge-ui text=\"Online\" variant=\"success\" size=\"sm\"></badge-ui></td>\n          <td><text-ui color=\"subtle\" size=\"sm\">2m ago</text-ui></td>\n        </tr>\n        <tr>\n          <td><row-ui gap=\"2\" align=\"center\"><avatar-ui text=\"Sarah Miller\" size=\"sm\"></avatar-ui><text-ui>Sarah Miller</text-ui></row-ui></td>\n          <td><badge-ui text=\"Editor\" variant=\"info\" size=\"sm\"></badge-ui></td>\n          <td><badge-ui text=\"Away\" variant=\"warning\" size=\"sm\"></badge-ui></td>\n          <td><text-ui color=\"subtle\" size=\"sm\">1h ago</text-ui></td>\n        </tr>\n        <tr>\n          <td><row-ui gap=\"2\" align=\"center\"><avatar-ui text=\"James Park\" size=\"sm\"></avatar-ui><text-ui>James Park</text-ui></row-ui></td>\n          <td><badge-ui text=\"Viewer\" variant=\"muted\" size=\"sm\"></badge-ui></td>\n          <td><badge-ui text=\"Offline\" variant=\"muted\" size=\"sm\"></badge-ui></td>\n          <td><text-ui color=\"subtle\" size=\"sm\">3h ago</text-ui></td>\n        </tr>\n      </tbody>\n    </table-ui>\n  </section>\n</card-ui>",
   "source": "apps/patterns/app/users-table-badge/users-table-badge.contents.html",
-  "captured_at": "2026-05-06T20:26:56.937Z"
+  "captured_at": "2026-05-07T15:03:20.693Z"
 }

package/compositions/{form → forms}/data-import-wizard.json

@@ -3,7 +3,7 @@
   "name": "data-import-wizard",
   "version": 1,
   "kind": "composition",
-  "domain": "form",
+  "domain": "forms",
   "description": "Multi-step data import wizard with a step progress indicator, file upload input, column-mapping form, preview feedback, and prev/next wizard navigation.",
   "tags": { "purpose": ["wizard", "import", "form", "multi-step"], "complexity": "high", "layout": "stacked" },
   "keywords": [

package/exemplars/README.md

@@ -0,0 +1,49 @@
+# `exemplars/` — RETIRED 2026-04-28
+
+> **This folder is no longer harvested into the corpus.**
+> Don't add `data-chunk` markers expecting them to land in
+> `packages/a2ui/corpus/chunks/`. Use the `apps/<name>/app/<demo>/`
+> layout instead, per ADR-0020.
+
+## What was here
+
+`exemplars/` was the v0.0.x and early v0.1.x source surface for
+hand-authored A2UI demonstrations: sample shells, blocks-reference
+prose, prototype layouts. Each piece was a static reference for
+designers and the gen-UI synthesizer's training corpus.
+
+## Why it was retired
+
+Three convergent reasons (per the v0.0.6 / mcp v0.0.5 cut on 2026-04-28):
+
+1. **The `data-chunk` marker pipeline replaced it.** Patterns that
+   matter as training material now live as live HTML demos under
+   `apps/<name>/app/<demo>/<demo>.contents.html` with
+   `data-chunk="<slug>"` and `data-chunk-kind` attributes. The
+   harvester (`scripts/build/harvest-chunks.mjs`) extracts them into
+   `packages/a2ui/corpus/chunks/`.
+2. **Single source of truth.** Maintaining hand-authored exemplars
+   alongside live apps doubled the surface that drifts. Apps are
+   already the artifacts users see; harvesting from them keeps demos
+   and training material in sync.
+3. **Composition vs. example.** Compositions and fragments with
+   live `$fragment` linking moved into
+   `packages/a2ui/corpus/{compositions,fragments}/`; everything else
+   (page-level demos) is now sourced from `apps/`.
+
+## What's still in this folder
+
+The 37 files (~248 KB) are kept on disk as historical reference
+(audit reports, blocks-reference prose, prototype shells) — they
+**don't ship** in the npm tarball (see the package.json `files`
+field in `packages/a2ui/corpus/`). Consider this folder a frozen
+snapshot of the pre-v0.1 era; it may be removed entirely in a
+future cleanup.
+
+## See also
+
+- [`packages/a2ui/corpus/README.md`](../README.md) — current corpus structure
+- [`docs/specs/genui-chunk-marker.md`](../../../../docs/specs/genui-chunk-marker.md) — `data-chunk` convention
+- [`.agents/skills/chunk-corpus-migration/SKILL.md`](../../../../.agents/skills/chunk-corpus-migration/SKILL.md) — corpus-migration playbook
+- ADR-0020 — apps/ + co-located component demos
+- Backlog item #92 (closed by this README)

package/fragments/layout/auth-card-header.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "../_schema.json",
+  "name": "auth-card-header",
+  "version": 1,
+  "kind": "fragment",
+  "semantic_role": "auth-titlebar",
+  "description": "Authentication card titlebar — centered logo (linking home), heading, and short body text. The canonical header for any auth, error, or onboarding shell card. Promoted from the chunk corpus where this exact shape appeared 23× across user-flow auth screens (sign-in, sign-up, forgot-password, MFA, account-locked, etc.) plus errors/{404,500,maintenance}.",
+  "shape": "Header(Column[align=center,gap=1](Image[role=logo], Text[v=heading], Text[v=body]))",
+  "tags": {
+    "purpose": ["auth-titlebar", "card-header"],
+    "layout": "stacked",
+    "alignment": "center"
+  },
+  "keywords": ["auth", "header", "title", "logo", "card", "sign-in", "sign-up", "error", "onboarding"],
+  "slots": [
+    {
+      "name": "logoSrc",
+      "targetId": "ach-logo",
+      "attribute": "src",
+      "required": true,
+      "description": "Path to the brand logo image (SVG preferred)"
+    },
+    {
+      "name": "logoAlt",
+      "targetId": "ach-logo",
+      "attribute": "alt",
+      "defaultValue": "Logo",
+      "description": "Alt text for the logo image"
+    },
+    {
+      "name": "heading",
+      "targetId": "ach-heading",
+      "attribute": "textContent",
+      "required": true,
+      "description": "Primary heading — auth state or error code (e.g. 'Sign in', '404 — Page not found', 'Reset your password')"
+    },
+    {
+      "name": "body",
+      "targetId": "ach-body",
+      "attribute": "textContent",
+      "description": "Short supporting copy below the heading"
+    }
+  ],
+  "template": [
+    { "id": "ach-root", "component": "Header", "children": ["ach-col"] },
+    { "id": "ach-col", "component": "Column", "align": "center", "gap": "1", "children": ["ach-logo", "ach-heading", "ach-body"] },
+    { "id": "ach-logo", "component": "Image", "src": "/icons/agent-ui-light.svg", "alt": "Logo" },
+    { "id": "ach-heading", "component": "Text", "variant": "heading", "textContent": "Heading" },
+    { "id": "ach-body", "component": "Text", "variant": "body", "textContent": "" }
+  ],
+  "links": {
+    "uses_components": ["Header", "Column", "Image", "Text"],
+    "uses_fragments": [],
+    "used_by": [],
+    "related": ["card-header-heading", "card-header-with-description"],
+    "spawned_from": ["chunk:auth-card-header"]
+  },
+  "metrics": {
+    "leverage": 23.0,
+    "pattern_count": 0,
+    "instance_count": 23,
+    "_provenance": "Promoted 2026-05-07 from chunks/auth-card-header.json (23 instances across user-flow auth + errors apps). See docs/reports/chunk-reconcile-2026-05-07.md for the full reconciliation context."
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-corpus",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "type": "module",
   "description": "AdiaUI A2UI training corpus \u2014 patterns, fragments, compositions, exemplars, eval fixtures, feedback, gap registry. Consumed by the compose engine's retrieval layer + the MCP pipeline.",
   "exports": {
@@ -38,4 +38,4 @@
     "url": "git+https://github.com/adiahealth/gen-ui-kit.git",
     "directory": "packages/a2ui/corpus"
   }
-}
+}

package/scripts/chunk-library.js

@@ -146,12 +146,20 @@ export async function searchChunksAsync(query, { kind, limit = 20 } = {}) {
   if (!query || typeof query !== 'string') return [];
 
   let cosineByName = null;
-  try {
-    const { scoreAll, available } = await import('../../retrieval/embedding/chunk-embedding-retriever.js');
-    if (await available()) {
-      cosineByName = await scoreAll(query);
-    }
-  } catch { /* embeddings unavailable — keyword-only */ }
+  // Env-var override: A2UI_DISABLE_EMBEDDINGS=1 forces keyword-only mode.
+  // Used by `npm run eval:diff -- --engine chunk-zettel-fast` and any
+  // diagnostic that needs to confirm the keyword path is independently
+  // healthy (i.e. retrieval works even when embeddings are stale or
+  // missing). Default: embeddings enabled when available.
+  const embeddingsDisabled = process.env.A2UI_DISABLE_EMBEDDINGS === '1';
+  if (!embeddingsDisabled) {
+    try {
+      const { scoreAll, available } = await import('../../retrieval/embedding/chunk-embedding-retriever.js');
+      if (await available()) {
+        cosineByName = await scoreAll(query);
+      }
+    } catch { /* embeddings unavailable — keyword-only */ }
+  }
 
   const candidates = [];
   for (const [name, rec] of chunks) {