@adia-ai/a2ui-retrieval 0.0.1 → 0.2.1

package/CHANGELOG.md

@@ -9,6 +9,85 @@ _Nothing yet._
 
 ---
 
+## [0.2.1] - 2026-05-02
+
+**Lockstep cut.** All 8 published `@adia-ai/*` packages bump 0.2.0 → 0.2.1 per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy). Patch cut — no breaking changes.
+
+### Changed
+
+- `version`: `0.2.0` → `0.2.1`.
+- `dependencies["@adia-ai/a2ui-corpus"]`: `^0.2.0` (covers `0.2.1`).
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.2.0` (covers `0.2.1`).
+- `embedding/chunk-embedding-retriever.js` + `embedding/embedding-retriever.js` — defensive resolution path: when the `chunk-embeddings.json` / `pattern-embeddings.json` indexes aren't reachable (e.g. inside a `node_modules/@adia-ai/a2ui-corpus/` install layout where the `files:` array now excludes them), the retriever falls back to keyword-only retrieval gracefully instead of throwing on `ENOENT`. Aligns with the `@adia-ai/a2ui-corpus` 0.2.0 tarball-trim decision.
+
+### No source-behavior changes
+
+Public API of `a2ui-retrieval` is byte-identical to `0.2.0`. The above embedding-retriever updates only affect the failure path (`ENOENT` graceful fallback) and don't change the contract for callers passing valid index files. The cut bumps version + tracks dep ranges + softens the embedding-index-missing failure mode.
+
+---
+
+## [0.2.0] - 2026-05-02
+
+**Lockstep cut + boundary reorganization.** All 8 published
+`@adia-ai/*` packages now share one version, governed by
+[`docs/specs/package-architecture.md` § 15 (Versioning Policy)](../../../docs/specs/package-architecture.md#15-versioning-policy).
+This release also lands the boundary cleanup from T4 of the
+[`docs/plans/packages-architecture-fixes-2026-05-02.md`](../../../.brain/archive/2026-Q2/PLAN-packages-architecture-fixes-2026-05-02.md)
+plan.
+
+### Changed
+
+- `version`: `0.0.1` → `0.2.0`.
+- `dependencies["@adia-ai/a2ui-utils"]`: `^0.0.2` → `^0.2.0`.
+
+- **Subdir reorganization** — 26 .js files at the top level
+  reorganized into 4 named concerns. Lookup-shaped files stay at the
+  top level; the rest move into subdirs. Top-level external imports
+  (`@adia-ai/a2ui-retrieval`) continue to work unchanged via the
+  re-exporting top-level barrel.
+
+  | New path | Members |
+  |---|---|
+  | `intent/` | `intent-alignment`, `intent-categorizer`, `intent-gate`, `prompt-analyzer`, `decomposer`, `clarity` |
+  | `embedding/` | `embedding-provider`, `embedding-retriever`, `chunk-embedding-retriever` |
+  | `feedback/` | `feedback`, `feedback-store`, `feedback-analyzer`, `dialog-recorder`, `gap-registry` |
+  | `authoring/` | `synthetic-data`, `web-research`, `pattern-promotion` |
+  | top level (kept) | `catalog`, `pattern-library`, `concept-mapper`, `domain-router`, `wiring-catalog`, `anti-patterns`, `context-assembler`, `component-entry`, `index` |
+
+- New subpath exports: `./intent`, `./embedding`, `./feedback`,
+  `./authoring` each expose a barrel `index.js`. Wildcard subpaths
+  (`./intent/*`, `./embedding/*`, etc.) expose individual files for
+  fine-grained imports. The old wildcard `./*` is retained for
+  backward compatibility — direct imports of moved files still work
+  (e.g. `import { feedbackStore } from '@adia-ai/a2ui-retrieval/feedback/feedback-store'`)
+  but consumers should prefer the barrel form.
+
+### Fixed
+
+- 6 `__dirname`-based path computations (in `dialog-recorder`,
+  `feedback-store`, `feedback-analyzer`, `gap-registry`, the two
+  embedding retrievers, and `prompt-analyzer`) gained one more `..`
+  segment to climb out of the new subdir to the corpus directory.
+  Without this, the moved files would write to a non-existent path
+  (`packages/a2ui/a2ui/corpus/...`). Caught during the post-move
+  smoke run; same class as the
+  `feedback_git_mv_audit_imports` memory entry.
+
+### Migration
+
+```diff
+- import { feedbackStore } from '@adia-ai/a2ui-retrieval';        // still works (top-level barrel)
+- import { feedbackStore } from '@adia-ai/a2ui-retrieval/feedback-store';  // BREAKS — file moved
++ import { feedbackStore } from '@adia-ai/a2ui-retrieval/feedback';        // new barrel
++ import { feedbackStore } from '@adia-ai/a2ui-retrieval/feedback/feedback-store';  // explicit
+```
+
+The top-level `index.js` still re-exports the previously-public surface
+(`assessClarity`, `isConversational`, `decomposeIntent`,
+`checkIntentAlignment`, etc.) — those imports do not need updating.
+
+---
+
 ## [0.0.1] - 2026-04-24
 
 First public release. Extracted from

package/README.md

@@ -14,18 +14,49 @@ npm install @adia-ai/a2ui-retrieval
 
 ## What's here
 
-- **Pattern library** — indexed search over the catalog's patterns and
-  fragments; domain-aware ranking.
-- **Intent gate** — classifies a user intent as UI-generating vs
-  conversational based on domain-keyword signal.
-- **Domain router** — maps free-form text to catalog domains
-  (`forms`, `data`, `agent`, `navigation`, etc.).
-- **Anti-pattern detector** — flags compositions that violate invariants
-  (invented components, bad attribute combos).
-- **Clarity analyzer** — scores how specific an intent is; drives
-  clarification prompts when the signal is too weak to generate.
-- **Context assembly** — stitches retrieval results into the prompt
-  context consumed by the LLM adapters.
+The package groups its 26 source files into 4 sub-concerns plus a
+top-level lookup surface. Importers can pull the top-level barrel
+(`@adia-ai/a2ui-retrieval`) for the previously-public surface, the
+per-subdir barrels (`@adia-ai/a2ui-retrieval/intent` etc.), or
+individual files for fine-grained imports.
+
+```
+a2ui-retrieval/
+├── catalog.js              top-level — catalog lookup (loaded from corpus)
+├── pattern-library.js      top-level — keyword + semantic pattern search
+├── concept-mapper.js       top-level — concept → catalog-entry mapping
+├── domain-router.js        top-level — intent → catalog-domain classifier
+├── wiring-catalog.js       top-level — controller / handler reference
+├── anti-patterns.js        top-level — known-bad pattern detector
+├── context-assembler.js    top-level — retrieval results → LLM context
+├── component-entry.js      top-level — catalog row serializer
+├── index.js                top-level — barrel
+│
+├── intent/                 intent classification + decomposition
+│   ├── intent-alignment.js
+│   ├── intent-categorizer.js
+│   ├── intent-gate.js          UI-generating vs conversational
+│   ├── prompt-analyzer.js
+│   ├── decomposer.js           compound intents → subtasks
+│   └── clarity.js              clarity scoring
+│
+├── embedding/              dense-vector retrieval
+│   ├── embedding-provider.js   adapter (Voyage / OpenAI / fallback)
+│   ├── embedding-retriever.js  top-N pattern retrieval
+│   └── chunk-embedding-retriever.js  chunk-level retrieval
+│
+├── feedback/               user-feedback ingestion loop
+│   ├── feedback.js
+│   ├── feedback-store.js       JSONL store under .brain/feedback/
+│   ├── feedback-analyzer.js
+│   ├── dialog-recorder.js      LLM round-trip capture (gated by env)
+│   └── gap-registry.js         tracked gaps in catalog coverage
+│
+└── authoring/              corpus-authoring helpers (upstream of retrieval)
+    ├── synthetic-data.js
+    ├── web-research.js
+    └── pattern-promotion.js
+```
 
 ## Runtime
 

package/anti-patterns.js

@@ -76,7 +76,7 @@ const antiPatterns = [
         'table-ui', 'chart-ui', 'embed-ui', 'stack-ui', 'block-ui', 'code-ui',
         'textarea-ui', 'radio-ui', 'radio-ui', 'tag-ui', 'accordion-ui',
         'modal-ui', 'alert-ui', 'tooltip-ui', 'menu-ui', 'breadcrumb-ui',
-        'nav-n', 'pagination-ui', 'avatar-group-ui', 'segmented-ui',
+        'nav-ui', 'pagination-ui', 'avatar-group-ui', 'segmented-ui',
         'segment-ui', 'command-ui', 'command-item-ui', 'command-group-ui',
         'calendar-picker-ui', 'color-picker-ui', 'kbd-ui', 'toolbar-ui',
         'otp-input-ui',

package/authoring/index.js

@@ -0,0 +1,13 @@
+/**
+ * @adia-ai/a2ui-retrieval/authoring — corpus authoring helpers.
+ *
+ * Scripts and helpers that produce or extend retrieval inputs:
+ * synthetic-data generation, web research, pattern promotion. These are
+ * upstream of retrieval (they create what retrieval reads) — kept inside
+ * the retrieval package because they share the catalog + pattern-library
+ * surfaces, but logically a separate concern from lookup.
+ */
+
+export * from './synthetic-data.js';
+export * from './web-research.js';
+export * from './pattern-promotion.js';

package/{pattern-promotion.js → authoring/pattern-promotion.js}

@@ -14,7 +14,7 @@
  * the pattern library.
  */
 
-import { getAllPatterns } from './pattern-library.js';
+import { getAllPatterns } from '../pattern-library.js';
 
 /**
  * Evaluate whether a generation should be promoted to a named pattern.

package/{synthetic-data.js → authoring/synthetic-data.js}

@@ -9,10 +9,10 @@
  * Spec: A003 section 6 — Synthetic Data Generation
  */
 
-import { getCatalog } from './catalog.js';
-import { getAntiPatterns } from './anti-patterns.js';
-import { getAllPatterns } from './pattern-library.js';
-import { serializeEntry } from './component-entry.js';
+import { getCatalog } from '../catalog.js';
+import { getAntiPatterns } from '../anti-patterns.js';
+import { getAllPatterns } from '../pattern-library.js';
+import { serializeEntry } from '../component-entry.js';
 
 // ── Coverage targets (spec section 6.2) ──
 
@@ -409,7 +409,7 @@ export class SyntheticDataGenerator {
 
       // Map A2UI types to their AdiaUI tag names for anti-pattern checking
       const tag = type.toLowerCase().replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
-      const tagName = tag.endsWith('-n') ? tag : `${tag}-n`;
+      const tagName = tag.endsWith('-ui') ? tag : `${tag}-ui`;
 
       // Build a minimal HTML representation
       const attrs = [];
@@ -425,7 +425,7 @@ export class SyntheticDataGenerator {
           .filter(Boolean)
           .map(c => {
             const ct = c.component?.toLowerCase().replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase() || '';
-            return ct.endsWith('-n') ? ct : ct;
+            return ct.endsWith('-ui') ? ct : ct;
           });
         lines.push(`<${tagName}${attrStr}>${childTypes.map(ct => `<${ct}>`).join('')}</${tagName}>`);
       } else {

package/catalog.js

@@ -83,58 +83,63 @@ const categoryMap = {
   'section': 'card-child', 'header': 'card-child', 'footer': 'card-child',
   'stream-ui': 'agent', 'table-ui': 'agent', 'chart-ui': 'agent',
   'embed-ui': 'agent', 'noodles-ui': 'agent',
-  'breadcrumb-ui': 'navigation', 'nav-n': 'navigation', 'pagination-ui': 'navigation',
+  'breadcrumb-ui': 'navigation', 'nav-ui': 'navigation', 'pagination-ui': 'navigation',
   'segmented-ui': 'navigation', 'segment-ui': 'navigation', 'router-ui': 'navigation',
   'toggle-group-ui': 'navigation', 'toggle-option-ui': 'navigation',
 };
 
 // ── Trait registry ──
-const traitRegistry = [
-  { name: 'pressable',      category: 'input-interaction',    description: 'Normalizes click/tap/keyboard into a single "press" event' },
-  { name: 'focusable',      category: 'input-interaction',    description: 'Keyboard-only focus ring, ignores pointer focus' },
-  { name: 'hoverable',      category: 'input-interaction',    description: 'Pointer hover enter/leave state tracking' },
-  { name: 'active-state',   category: 'input-interaction',    description: 'Tracks pointer down / active interaction state' },
-  { name: 'disabled-state', category: 'input-interaction',    description: 'Enforces disabled behavior and interaction blocking' },
-  { name: 'keyboard-nav',     category: 'keyboard-navigation', description: 'Arrow keys, Enter, Escape — semantic navigation events' },
-  { name: 'roving-tabindex',  category: 'keyboard-navigation', description: 'Focus management within composite widgets' },
-  { name: 'typeahead',        category: 'keyboard-navigation', description: 'Incremental search within a collection' },
-  { name: 'hotkey',           category: 'keyboard-navigation', description: 'Global or scoped keyboard shortcuts' },
-  { name: 'focus-trap',       category: 'keyboard-navigation', description: 'Traps Tab/Shift+Tab within a container' },
-  { name: 'form-associated', category: 'forms-data', description: 'ElementInternals integration for form participation' },
-  { name: 'validation',      category: 'forms-data', description: 'Validation rules: required, minlength, pattern, email' },
-  { name: 'value-sync',      category: 'forms-data', description: 'Syncs value between attribute/property/controller' },
-  { name: 'dirty-state',     category: 'forms-data', description: 'Tracks modified vs initial value' },
-  { name: 'resettable',      category: 'forms-data', description: 'Responds to form reset events' },
-  { name: 'resize-observer-trait',       category: 'layout-measurement', description: 'Reacts to element size changes' },
-  { name: 'intersection-observer-trait', category: 'layout-measurement', description: 'Visibility detection (viewport)' },
-  { name: 'anchor-positioning',          category: 'layout-measurement', description: 'Positions relative to an anchor element' },
-  { name: 'portal',                      category: 'layout-measurement', description: 'Renders content in a different DOM root' },
-  { name: 'scroll-lock',                 category: 'layout-measurement', description: 'Disables background scrolling' },
-  { name: 'draggable',    category: 'motion-positioning', description: 'Pointer drag to reposition' },
-  { name: 'tossable',     category: 'motion-positioning', description: 'Flick with momentum + viewport bounce' },
-  { name: 'resizable',    category: 'motion-positioning', description: 'Drag edges/corners to resize' },
-  { name: 'inertia-drag', category: 'motion-positioning', description: 'Momentum-based dragging, smooth deceleration' },
-  { name: 'snap-to-grid', category: 'motion-positioning', description: 'Snaps position to configurable grid' },
-  { name: 'drag-ghost',   category: 'motion-positioning', description: 'Ghost clone at origin during drag' },
-  { name: 'ripple',         category: 'animation-feedback', description: 'Material-style press ripple effect' },
-  { name: 'spring-animate', category: 'animation-feedback', description: 'Spring-based motion transitions' },
-  { name: 'fade-presence',  category: 'animation-feedback', description: 'Enter/exit fade with lifecycle' },
-  { name: 'scale-press',    category: 'animation-feedback', description: 'Subtle scale transform on press' },
-  { name: 'tilt-hover',     category: 'animation-feedback', description: 'Tilt based on pointer position' },
-  { name: 'glow-focus',       category: 'visual-dynamics', description: 'Animated pulsing glow on focus' },
-  { name: 'gradient-shift',   category: 'visual-dynamics', description: 'Animated rainbow gradient backgrounds' },
-  { name: 'parallax',         category: 'visual-dynamics', description: 'Layered motion relative to pointer' },
-  { name: 'shimmer-loading',  category: 'visual-dynamics', description: 'Skeleton shimmer effect' },
-  { name: 'noise-texture',    category: 'visual-dynamics', description: 'Procedural grain overlay' },
-  { name: 'magnetic-hover',  category: 'interaction-delight', description: 'Element subtly follows cursor' },
-  { name: 'confetti',        category: 'interaction-delight', description: 'Radial particle burst on press' },
-  { name: 'confetti-burst',  category: 'interaction-delight', description: 'Upward fountain particle burst' },
-  { name: 'sound-feedback',  category: 'audio-haptics-sensory', description: 'Synthesized tones via Web Audio API' },
-  { name: 'haptic-feedback', category: 'audio-haptics-sensory', description: 'Vibration API feedback' },
-  { name: 'typewriter',      category: 'audio-haptics-sensory', description: 'Animated text reveal character by character' },
-  { name: 'count-up',        category: 'audio-haptics-sensory', description: 'Animated numeric transitions' },
-  { name: 'attention-pulse', category: 'audio-haptics-sensory', description: 'Periodic pulse to draw attention' },
-];
+//
+// Loaded from packages/web-components/traits/_catalog.json — generated
+// by `node scripts/build/traits-catalog.mjs` from the live defineTrait()
+// metadata. Hand-edits here will be overwritten. Treat the trait file
+// itself as the single source of truth.
+let traitRegistry = [];
+
+async function loadTraitRegistry() {
+  if (typeof process !== 'undefined' && process.versions?.node) {
+    try {
+      const { readFile } = await import(/* @vite-ignore */ 'node:fs/promises');
+      const { fileURLToPath } = await import(/* @vite-ignore */ 'node:url');
+      const { dirname, join } = await import(/* @vite-ignore */ 'node:path');
+      const path = join(dirname(fileURLToPath(import.meta.url)), '../../web-components/traits/_catalog.json');
+      const raw = await readFile(path, 'utf8');
+      const data = JSON.parse(raw);
+      traitRegistry = data.traits.map(t => ({
+        name: t.name,
+        category: t.category,
+        description: t.description,
+        attributes: [...t.attributes],
+        events: [...t.events],
+        config: [...t.config],
+      }));
+    } catch (err) {
+      console.warn('[a2ui-corpus] could not load trait catalog:', err.message);
+    }
+  } else {
+    // Browser branch — fetch via HTTP, not `import('… .json', { with: { type: 'json' } })`.
+    // Vite's dev server transforms JSON imports into JS modules and serves them
+    // with `Content-Type: text/javascript`; Chrome's strict MIME check rejects
+    // that when the spec-correct `with: { type: 'json' }` attribute is present.
+    // (Site pages already use fetch() for the same file — see
+    //  site/pages/traits/_api-table.js + site/pages/traits/catalog/index.setup.js.)
+    try {
+      const res = await fetch('/packages/web-components/traits/_catalog.json');
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      traitRegistry = data.traits.map(t => ({
+        name: t.name,
+        category: t.category,
+        description: t.description,
+        attributes: [...t.attributes],
+        events: [...t.events],
+        config: [...t.config],
+      }));
+    } catch { /* trait catalog not present in this build context */ }
+  }
+}
+
+await loadTraitRegistry();
 
 // ── Alias tracking ──
 const aliases = new Set([

package/concept-mapper.js

@@ -20,7 +20,7 @@
  */
 
 import { searchBlocks } from '../engine/reference.js';
-import { scoreAll as embeddingScoreAll, available as embeddingAvailable } from './embedding-retriever.js';
+import { scoreAll as embeddingScoreAll, available as embeddingAvailable } from './embedding/embedding-retriever.js';
 
 /** Weights for the combined score. Tuned to keep lexical authoritative
  *  but let strong conceptual+structural+semantic signals override marginal

package/embedding/chunk-embedding-retriever.js

@@ -0,0 +1,123 @@
+/**
+ * Chunk embedding retriever — loads the build-time chunk embedding index
+ * and scores a query against every chunk via cosine similarity.
+ *
+ * Sibling to `embedding-retriever.js` (pattern embeddings); same provider
+ * conventions, same graceful-degradation contract.
+ *
+ * Index: packages/a2ui/corpus/chunk-embeddings.json (built by
+ * scripts/build/embeddings-chunks.mjs). When missing or empty, the
+ * retriever is effectively a no-op — callers see an empty score map and
+ * should fall back to keyword-only ranking.
+ *
+ * Used by chunk-library.searchChunks() to blend semantic + keyword scores.
+ */
+
+import { detectProvider, cosine, voyage, openai } from './embedding-provider.js';
+
+const IS_NODE = typeof process !== 'undefined' && !!process.versions?.node;
+
+let _index = null;
+let _indexByName = null; // Map<chunk-name, Float32Array>
+let _loadPromise = null;
+let _embedFn = null;
+let _available = null;
+
+async function _loadIndex() {
+  if (_index !== null) return _index;
+  if (_loadPromise) return _loadPromise;
+  _loadPromise = (async () => {
+    try {
+      if (IS_NODE) {
+        const fs = await import(/* @vite-ignore */ 'node:fs/promises');
+        const path = await import(/* @vite-ignore */ 'node:path');
+        const url = await import(/* @vite-ignore */ 'node:url');
+        // Try the package-import path first (works under node_modules
+        // install layout — `@adia-ai/a2ui-corpus` exports
+        // `./chunk-embeddings`). Fall back to the relative source-tree
+        // path so a source-checkout monorepo without symlinked deps
+        // still resolves.
+        let p = null;
+        try {
+          const { createRequire } = await import(/* @vite-ignore */ 'node:module');
+          const require = createRequire(import.meta.url);
+          p = require.resolve('@adia-ai/a2ui-corpus/chunk-embeddings');
+        } catch {
+          const here = path.dirname(url.fileURLToPath(import.meta.url));
+          p = path.resolve(here, '../../corpus/chunk-embeddings.json');
+        }
+        const raw = await fs.readFile(p, 'utf8');
+        _index = JSON.parse(raw);
+      } else {
+        const url = new URL('../../corpus/chunk-embeddings.json', import.meta.url);
+        const res = await fetch(url).catch(() => null);
+        _index = res?.ok ? await res.json().catch(() => null) : null;
+      }
+    } catch {
+      _index = null;
+    }
+    if (_index?.chunks?.length) {
+      _indexByName = new Map();
+      for (const c of _index.chunks) {
+        if (c?.name && Array.isArray(c.vector)) {
+          _indexByName.set(c.name, Float32Array.from(c.vector));
+        }
+      }
+    }
+    return _index;
+  })();
+  return _loadPromise;
+}
+
+function _resolveEmbed(providerName, model) {
+  if (providerName === 'voyage') return voyage({ model });
+  if (providerName === 'openai') return openai({ model });
+  const auto = detectProvider();
+  return auto?.embed || null;
+}
+
+export async function available() {
+  if (_available !== null) return _available;
+  const idx = await _loadIndex();
+  if (!idx || !idx.chunks?.length) {
+    _available = false;
+    return false;
+  }
+  _embedFn = _resolveEmbed(idx.provider, idx.model);
+  _available = !!_embedFn;
+  return _available;
+}
+
+/**
+ * Embed a query and return a Map<chunk-name → cosine-score>.
+ * Returns an empty Map when unavailable (no index or no API key).
+ */
+export async function scoreAll(query) {
+  if (!query || typeof query !== 'string') return new Map();
+  if (!(await available())) return new Map();
+
+  let qVec;
+  try {
+    const [v] = await _embedFn([query]);
+    qVec = v;
+  } catch (e) {
+    if (typeof console !== 'undefined') console.warn('[chunk-embedding-retriever]', e.message);
+    return new Map();
+  }
+
+  const out = new Map();
+  for (const [name, vec] of _indexByName) {
+    out.set(name, cosine(qVec, vec));
+  }
+  return out;
+}
+
+export async function size() {
+  const idx = await _loadIndex();
+  return idx?.chunks?.length || 0;
+}
+
+export async function providerInfo() {
+  const idx = await _loadIndex();
+  return idx ? { provider: idx.provider, model: idx.model, dims: idx.dims } : null;
+}

package/{embedding-retriever.js → embedding/embedding-retriever.js}

@@ -32,12 +32,24 @@ async function _loadIndex() {
         const fs = await import(/* @vite-ignore */ 'node:fs/promises');
         const path = await import(/* @vite-ignore */ 'node:path');
         const url = await import(/* @vite-ignore */ 'node:url');
-        const here = path.dirname(url.fileURLToPath(import.meta.url));
-        const p = path.resolve(here, '../corpus/pattern-embeddings.json');
+        // Try the package-import path first (works under node_modules
+        // install layout — `@adia-ai/a2ui-corpus` exports
+        // `./pattern-embeddings`). Fall back to the relative source-tree
+        // path so a source-checkout monorepo without symlinked deps
+        // still resolves.
+        let p = null;
+        try {
+          const { createRequire } = await import(/* @vite-ignore */ 'node:module');
+          const require = createRequire(import.meta.url);
+          p = require.resolve('@adia-ai/a2ui-corpus/pattern-embeddings');
+        } catch {
+          const here = path.dirname(url.fileURLToPath(import.meta.url));
+          p = path.resolve(here, '../../corpus/pattern-embeddings.json');
+        }
         const raw = await fs.readFile(p, 'utf8');
         _index = JSON.parse(raw);
       } else {
-        const url = new URL('../corpus/pattern-embeddings.json', import.meta.url);
+        const url = new URL('../../corpus/pattern-embeddings.json', import.meta.url);
         const res = await fetch(url).catch(() => null);
         _index = res?.ok ? await res.json().catch(() => null) : null;
       }

package/embedding/index.js

@@ -0,0 +1,7 @@
+/**
+ * @adia-ai/a2ui-retrieval/embedding — embedding-provider + retrievers surface.
+ */
+
+export * from './embedding-provider.js';
+export * from './embedding-retriever.js';
+export * from './chunk-embedding-retriever.js';

package/{dialog-recorder.js → feedback/dialog-recorder.js}

@@ -36,9 +36,9 @@ async function _ensureModules() {
   _fs = await import(/* @vite-ignore */ 'node:fs/promises');
   _path = await import(/* @vite-ignore */ 'node:path');
   _url = await import(/* @vite-ignore */ 'node:url');
-  // logs/ lives at the repo root: packages/a2ui/retrieval → up 3 → repo root
+  // logs/ lives at the repo root: packages/a2ui/retrieval/feedback → up 4 → repo root
   const __dirname = _path.dirname(_url.fileURLToPath(import.meta.url));
-  _logsRoot = _path.resolve(__dirname, '..', '..', '..', 'logs', 'dialogs');
+  _logsRoot = _path.resolve(__dirname, '..', '..', '..', '..', 'logs', 'dialogs');
 }
 
 // In-memory turn counter per session — keeps the on-disk turn ordering correct

package/{feedback-analyzer.js → feedback/feedback-analyzer.js}

@@ -13,7 +13,7 @@
  */
 
 import { feedbackStore } from './feedback-store.js';
-import { categorizeIntent } from './intent-categorizer.js';
+import { categorizeIntent } from '../intent/intent-categorizer.js';
 
 let fs, path;
 const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
@@ -26,8 +26,9 @@ if (IS_NODE) {
   }
 }
 
+// packages/a2ui/retrieval/feedback → up 3 → packages/a2ui → corpus/feedback
 const FEEDBACK_DIR = path
-  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', 'a2ui/corpus', 'feedback')
+  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..', 'a2ui/corpus', 'feedback')
   : null;
 
 export class FeedbackAnalyzer {

package/{feedback-store.js → feedback/feedback-store.js}

@@ -23,8 +23,9 @@ if (IS_NODE) {
   }
 }
 
+// packages/a2ui/retrieval/feedback → up 3 → packages/a2ui → corpus/feedback
 const FEEDBACK_DIR = path
-  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', 'a2ui/corpus', 'feedback')
+  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..', 'a2ui/corpus', 'feedback')
   : null;
 
 function todayFile() {

package/{gap-registry.js → feedback/gap-registry.js}

@@ -24,8 +24,9 @@ if (IS_NODE) {
   }
 }
 
+// packages/a2ui/retrieval/feedback → up 3 → packages/a2ui → corpus/gaps/registry.json
 const REGISTRY_PATH = path
-  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', 'a2ui/corpus', 'gaps', 'registry.json')
+  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', '..', 'a2ui/corpus', 'gaps', 'registry.json')
   : null;
 
 /**

package/feedback/index.js

@@ -0,0 +1,12 @@
+/**
+ * @adia-ai/a2ui-retrieval/feedback — feedback-loop surface.
+ *
+ * Pairs the feedback store, analyzer, dialog recorder, and gap registry
+ * — all the artifacts that compose the user-feedback ingestion loop.
+ */
+
+export { feedbackStore } from './feedback-store.js';
+export { FeedbackAnalyzer } from './feedback-analyzer.js';
+export * from './feedback.js';
+export { recordTurn, isRecording } from './dialog-recorder.js';
+export { loadGaps, addGap, updateGapStatus } from './gap-registry.js';

package/index.js

@@ -6,11 +6,11 @@ export { getCatalog, getComponent, getComponentsByCategory, getTraits, getTraits
 export { serializeEntry } from './component-entry.js';
 export { getAntiPatterns, checkAntiPattern, checkAllAntiPatterns } from './anti-patterns.js';
 export { classifyIntent, getDomain, getAllDomains } from './domain-router.js';
-export { isConversational } from './intent-gate.js';
-export { assessClarity } from './clarity.js';
-export { detectReferences, researchIntent } from './web-research.js';
+export { isConversational } from './intent/intent-gate.js';
+export { assessClarity } from './intent/clarity.js';
+export { detectReferences, researchIntent } from './authoring/web-research.js';
 export { assembleContext } from './context-assembler.js';
 export { getPattern, searchPatterns, semanticSearchPatterns, getAllPatterns, registerPattern } from './pattern-library.js';
-export { extractExpectations, verifyAlignment, checkIntentAlignment } from './intent-alignment.js';
-export { decomposeIntent, composeSubtasks } from './decomposer.js';
+export { extractExpectations, verifyAlignment, checkIntentAlignment } from './intent/intent-alignment.js';
+export { decomposeIntent, composeSubtasks } from './intent/decomposer.js';
 export { getWiringCatalog, getControllerInfo, getHandlerInfo } from './wiring-catalog.js';

package/{clarity.js → intent/clarity.js}

@@ -12,8 +12,8 @@
  * Returns a clarity score (0-1) and targeted questions for what's missing.
  */
 
-import { classifyIntent } from './domain-router.js';
-import { searchPatterns } from './pattern-library.js';
+import { classifyIntent } from '../domain-router.js';
+import { searchPatterns } from '../pattern-library.js';
 
 // ── Dimension detectors ──────────────────────────────────────────────────
 

package/{decomposer.js → intent/decomposer.js}

@@ -14,7 +14,7 @@
  * is almost trivial."
  */
 
-import { classifyIntent } from './domain-router.js';
+import { classifyIntent } from '../domain-router.js';
 
 // ── Section Detection ────────────────────────────────────────────────────
 

package/intent/index.js

@@ -0,0 +1,14 @@
+/**
+ * @adia-ai/a2ui-retrieval/intent — intent classification + decomposition surface.
+ *
+ * Re-exports the intent-shaped retrieval primitives. Importers can reach
+ * individual files directly (e.g. `@adia-ai/a2ui-retrieval/intent/clarity`)
+ * or pull the bundle via this barrel.
+ */
+
+export { extractExpectations, verifyAlignment, checkIntentAlignment } from './intent-alignment.js';
+export { categorizeIntent } from './intent-categorizer.js';
+export { isConversational } from './intent-gate.js';
+export { analyzePrompt } from './prompt-analyzer.js';
+export { decomposeIntent, composeSubtasks } from './decomposer.js';
+export { assessClarity } from './clarity.js';

package/{prompt-analyzer.js → intent/prompt-analyzer.js}

@@ -45,11 +45,12 @@ async function getVocab() {
       const fs = await import(/* @vite-ignore */ 'node:fs/promises');
       const path = await import(/* @vite-ignore */ 'node:path');
       const url = await import(/* @vite-ignore */ 'node:url');
+      // packages/a2ui/retrieval/intent → up 2 → packages/a2ui → corpus/patterns/_components.json
       const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
-      const raw = await fs.readFile(path.join(__dirname, '../corpus/patterns/_components.json'), 'utf8');
+      const raw = await fs.readFile(path.join(__dirname, '../../corpus/patterns/_components.json'), 'utf8');
       catalog = JSON.parse(raw);
     } else {
-      const resp = await fetch(new URL('../corpus/patterns/_components.json', import.meta.url));
+      const resp = await fetch(new URL('../../corpus/patterns/_components.json', import.meta.url));
       if (resp.ok) catalog = await resp.json();
     }
   } catch { /* empty vocab — analyzer will still work, just unconstrained */ }

package/package.json

@@ -1,15 +1,27 @@
 {
   "name": "@adia-ai/a2ui-retrieval",
-  "version": "0.0.1",
+  "version": "0.2.1",
   "description": "AdiaUI A2UI retrieval layer — catalog lookup, intent classification, domain routing, pattern + anti-pattern matching, clarity + context assembly. Consumed by the compose engine and any A2UI-protocol tooling that needs to reason about user intent against the catalog.",
   "type": "module",
   "main": "./index.js",
   "exports": {
-    ".":   "./index.js",
-    "./*": "./*.js"
+    ".":             "./index.js",
+    "./intent":      "./intent/index.js",
+    "./intent/*":    "./intent/*.js",
+    "./embedding":   "./embedding/index.js",
+    "./embedding/*": "./embedding/*.js",
+    "./feedback":    "./feedback/index.js",
+    "./feedback/*":  "./feedback/*.js",
+    "./authoring":   "./authoring/index.js",
+    "./authoring/*": "./authoring/*.js",
+    "./*":           "./*.js"
   },
   "files": [
     "*.js",
+    "intent/",
+    "embedding/",
+    "feedback/",
+    "authoring/",
     "README.md",
     "CHANGELOG.md"
   ],
@@ -24,6 +36,9 @@
     "directory": "packages/a2ui/retrieval"
   },
   "dependencies": {
-    "@adia-ai/a2ui-utils": "^0.0.2"
+    "@adia-ai/a2ui-utils": "^0.2.0"
+  },
+  "optionalDependencies": {
+    "@adia-ai/a2ui-corpus": "^0.2.0"
   }
 }

package/pattern-library.js

@@ -535,7 +535,7 @@ export async function semanticSearchPatterns(query, options = {}) {
   // where keyword collisions pick the wrong pattern. Graceful degradation:
   // empty map → no effect, pipeline behaves exactly as pre-embedding.
   try {
-    const { scoreAll, available } = await import('./embedding-retriever.js');
+    const { scoreAll, available } = await import('./embedding/embedding-retriever.js');
     if (await available()) {
       const semanticMap = await scoreAll(query);
       if (semanticMap.size > 0) {

package/wiring-catalog.js

@@ -7,7 +7,7 @@
  * The schema has 5 docking points:
  *   DATA     — sources, params (how the surface gets its data)
  *   STATE    — controllers, model (how components manage behavior)
- *   ACTIONS  — AdiaEvent → handler chains (what happens on events)
+ *   ACTIONS  — UIEvent → handler chains (what happens on events)
  *   PROVIDES — context injection into subtrees
  *   LIFECYCLE — onMount, onUnmount, onModelChange hooks
  *
@@ -17,7 +17,7 @@
  * A full app needs all five.
  */
 
-// ── AdiaEvent ──────────────────────────────────────────────────
+// ── UIEvent ──────────────────────────────────────────────────
 // A typed event object that the wiring system understands natively.
 // Maps 1:1 to DOM events but with AdiaUI semantics and payload contracts.
 //
@@ -26,7 +26,7 @@
 //   { "event": "submit", "target": "form-col" }
 //   { "event": "mount" }
 //
-// "event"    — AdiaEvent type name (see adiaEvents below)
+// "event"    — UIEvent type name (see adiaEvents below)
 // "target"   — component id that emits. Omit for surface-level events.
 // "debounce" — ms, coalesce rapid-fire (input, resize)
 // "throttle" — ms, limit frequency (scroll, drag)
@@ -129,9 +129,9 @@ export function getWiringCatalog() {
       { name: 'notify', description: 'Show a toast/alert notification.', config: ['message', 'variant'] },
     ],
 
-    // ── ACTION SHAPE (AdiaEvent → handler) ──
+    // ── ACTION SHAPE (UIEvent → handler) ──
     actionShape: {
-      event: 'AdiaEvent object: { event, target?, debounce?, throttle?, condition? }',
+      event: 'UIEvent object: { event, target?, debounce?, throttle?, condition? }',
       handler: 'Handler name from the handlers list.',
       config: 'Handler-specific configuration object.',
       onSuccess: 'Follow-up actions array (each is { handler, config }).',
@@ -174,7 +174,7 @@ export function getWiringCatalog() {
 }
 
 /**
- * Get AdiaEvent type info.
+ * Get UIEvent type info.
  */
 export function getAdiaEvent(type) {
   return adiaEvents.find(e => e.event === type) || null;