@adia-ai/a2ui-retrieval 0.0.1

package/gap-registry.js

@@ -0,0 +1,121 @@
+/**
+ * Gap Registry
+ *
+ * Manages a persistent JSON file tracking identified pattern/training gaps.
+ * Used by the feedback pipeline to record and track resolution of weak areas.
+ *
+ * Registry file: packages/a2ui/corpus/gaps/registry.json
+ *
+ * Usage:
+ *   import { loadGaps, addGap, updateGapStatus } from './gap-registry.js';
+ *   const gaps = await loadGaps();
+ *   await addGap({ intentCategory: 'form/checkout', ... });
+ *   await updateGapStatus('form/checkout', 'resolved', 'Added checkout pattern');
+ */
+
+let fs, path;
+const IS_NODE = typeof process !== 'undefined' && process.versions?.node;
+if (IS_NODE) {
+  try {
+    fs = await import(/* @vite-ignore */ 'node:fs/promises');
+    path = await import(/* @vite-ignore */ 'node:path');
+  } catch {
+    // Node builtins unavailable
+  }
+}
+
+const REGISTRY_PATH = path
+  ? path.join(path.dirname(new URL(import.meta.url).pathname), '..', '..', 'a2ui/corpus', 'gaps', 'registry.json')
+  : null;
+
+/**
+ * Load all gaps from the registry file.
+ * @returns {Promise<object[]>}
+ */
+export async function loadGaps() {
+  if (!fs || !REGISTRY_PATH) return [];
+  try {
+    const content = await fs.readFile(REGISTRY_PATH, 'utf8');
+    return JSON.parse(content);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Save the full gaps array to disk.
+ * @param {object[]} gaps
+ */
+export async function saveGaps(gaps) {
+  if (!fs || !REGISTRY_PATH) return;
+  const dir = path.dirname(REGISTRY_PATH);
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(REGISTRY_PATH, JSON.stringify(gaps, null, 2) + '\n');
+}
+
+/**
+ * Add a new gap to the registry. Merges with existing if same intentCategory.
+ *
+ * @param {object} gap
+ * @param {string} gap.intentCategory
+ * @param {number} gap.sampleCount
+ * @param {number} gap.avgScore
+ * @param {number} gap.avgRating
+ * @param {string[]} gap.sampleIntents
+ */
+export async function addGap(gap) {
+  const gaps = await loadGaps();
+  const existing = gaps.find(g => g.intentCategory === gap.intentCategory && g.status !== 'resolved');
+
+  if (existing) {
+    // Merge: update stats, add new sample intents
+    existing.sampleCount = gap.sampleCount;
+    existing.avgScore = gap.avgScore;
+    existing.avgRating = gap.avgRating;
+    existing.lastSeen = new Date().toISOString();
+    const intentSet = new Set([...existing.sampleIntents, ...(gap.sampleIntents || [])]);
+    existing.sampleIntents = [...intentSet].slice(0, 10);
+  } else {
+    gaps.push({
+      intentCategory: gap.intentCategory,
+      detectedAt: new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
+      sampleCount: gap.sampleCount || 0,
+      avgScore: gap.avgScore || 0,
+      avgRating: gap.avgRating || 0,
+      status: 'open',
+      resolution: null,
+      sampleIntents: (gap.sampleIntents || []).slice(0, 10),
+    });
+  }
+
+  await saveGaps(gaps);
+  return gaps;
+}
+
+/**
+ * Update the status of a gap by intent category.
+ *
+ * @param {string} category — Intent category to update
+ * @param {'open'|'in-progress'|'resolved'} status
+ * @param {string} [resolution] — Description of how the gap was resolved
+ */
+export async function updateGapStatus(category, status, resolution) {
+  const gaps = await loadGaps();
+  const gap = gaps.find(g => g.intentCategory === category && g.status !== 'resolved');
+
+  if (!gap) {
+    throw new Error(`No open gap found for category: ${category}`);
+  }
+
+  gap.status = status;
+  if (resolution) {
+    gap.resolution = resolution;
+  }
+  if (status === 'resolved') {
+    gap.resolvedAt = new Date().toISOString();
+  }
+
+  await saveGaps(gaps);
+  return gap;
+}

package/index.js

@@ -0,0 +1,16 @@
+/**
+ * A2UI Intelligence System — Public API
+ */
+
+export { getCatalog, getComponent, getComponentsByCategory, getTraits, getTraitsByCategory, getFullCatalog } from './catalog.js';
+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 { 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 { getWiringCatalog, getControllerInfo, getHandlerInfo } from './wiring-catalog.js';

package/intent-alignment.js

@@ -0,0 +1,243 @@
+/**
+ * Intent Alignment Verification — checks whether generated output
+ * actually contains what the user asked for.
+ *
+ * Extracts expectations from the intent (field labels, component types,
+ * quantities, action verbs) and verifies them against the A2UI output.
+ *
+ * Returns a structured alignment report with per-expectation pass/fail,
+ * an overall alignment score (0-1), and specific gaps.
+ */
+
+// ── Expectation Extractors ──────────────────────────────────────────────
+
+/** Field/label expectations — "email", "password", "name", etc. */
+const FIELD_PATTERNS = [
+  /\b(email|password|username|name|phone|address|city|state|zip|country|company|title|role|bio|url|website|date|time|description|message|subject|amount|price|quantity|search|notes?)\b/gi,
+];
+
+/** Component type expectations — "button", "form", "table", etc. */
+const COMPONENT_PATTERNS = [
+  /\b(button|form|table|chart|card|avatar|badge|alert|modal|drawer|tabs?|sidebar|navbar|breadcrumb|pagination|progress|slider|toggle|checkbox|radio|dropdown|select|upload|calendar|timeline|steps?|accordion)\b/gi,
+];
+
+/** Quantity expectations — "3 cards", "two columns", etc. */
+const QUANTITY_MAP = { one: 1, two: 2, three: 3, four: 4, five: 5, six: 6, seven: 7, eight: 8, nine: 9, ten: 10 };
+const QUANTITY_PATTERN = /\b(\d+|one|two|three|four|five|six|seven|eight|nine|ten)\s+(cards?|columns?|items?|fields?|buttons?|sections?|rows?|tiles?|steps?|tabs?|metrics?|stats?)\b/gi;
+
+/** Action expectations — "submit", "cancel", "delete", etc. */
+const ACTION_PATTERNS = [
+  /\b(submit|cancel|save|delete|edit|close|open|search|filter|sort|login|signup|register|checkout|confirm|reset|send|upload|download|share|copy|print)\b/gi,
+];
+
+/** Specific content expectations — quoted strings, dollar amounts, percentages */
+const CONTENT_PATTERNS = [
+  /["']([^"']+)["']/g,           // quoted strings
+  /\$[\d,.]+/g,                   // dollar amounts
+  /\d+%/g,                        // percentages
+];
+
+/**
+ * Extract expectations from a natural language intent.
+ *
+ * @param {string} intent
+ * @returns {{ fields: string[], componentTypes: string[], quantities: { count: number, type: string }[], actions: string[], content: string[] }}
+ */
+export function extractExpectations(intent) {
+  const lower = intent.toLowerCase();
+
+  // Fields
+  const fields = [];
+  for (const pattern of FIELD_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(lower))) {
+      const f = match[1].toLowerCase();
+      if (!fields.includes(f)) fields.push(f);
+    }
+  }
+
+  // Component types
+  const componentTypes = [];
+  for (const pattern of COMPONENT_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(lower))) {
+      const t = match[1].toLowerCase();
+      if (!componentTypes.includes(t)) componentTypes.push(t);
+    }
+  }
+
+  // Quantities
+  const quantities = [];
+  QUANTITY_PATTERN.lastIndex = 0;
+  let qMatch;
+  while ((qMatch = QUANTITY_PATTERN.exec(lower))) {
+    const num = QUANTITY_MAP[qMatch[1]] || parseInt(qMatch[1], 10);
+    const type = qMatch[2].replace(/s$/, ''); // singularize
+    if (!isNaN(num)) quantities.push({ count: num, type });
+  }
+
+  // Actions
+  const actions = [];
+  for (const pattern of ACTION_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(lower))) {
+      const a = match[1].toLowerCase();
+      if (!actions.includes(a)) actions.push(a);
+    }
+  }
+
+  // Specific content
+  const content = [];
+  for (const pattern of CONTENT_PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(intent))) {
+      content.push(match[1] || match[0]);
+    }
+  }
+
+  return { fields, componentTypes, quantities, actions, content };
+}
+
+// ── A2UI Type Mapping ───────────────────────────────────────────────────
+
+/** Map intent keywords to A2UI component types */
+const TYPE_MAP = {
+  button: ['Button'],
+  form: ['FormContainer', 'TextField', 'Column'],
+  table: ['Table'],
+  chart: ['Chart'],
+  card: ['Card'],
+  avatar: ['Avatar'],
+  badge: ['Badge'],
+  alert: ['Alert'],
+  modal: ['Modal', 'Dialog'],
+  drawer: ['Drawer'],
+  tab: ['Tabs', 'Tab'],
+  sidebar: ['Sidebar'],
+  navbar: ['Nav'],
+  breadcrumb: ['Breadcrumb'],
+  pagination: ['Pagination'],
+  progress: ['Progress'],
+  slider: ['Slider'],
+  toggle: ['Toggle'],
+  checkbox: ['CheckBox'],
+  radio: ['Radio'],
+  dropdown: ['ChoicePicker', 'Select'],
+  select: ['ChoicePicker', 'Select'],
+  upload: ['Upload'],
+  calendar: ['CalendarPicker', 'DateTimeInput'],
+  timeline: ['Timeline'],
+  step: ['Steps'],
+  accordion: ['Accordion'],
+};
+
+/**
+ * Verify generated A2UI output against extracted expectations.
+ *
+ * @param {object[]} components — Flat adjacency array from messages[0].components
+ * @param {{ fields: string[], componentTypes: string[], quantities: { count: number, type: string }[], actions: string[], content: string[] }} expectations
+ * @returns {{ score: number, checks: { category: string, expected: string, found: boolean, detail: string }[], gaps: string[] }}
+ */
+export function verifyAlignment(components, expectations) {
+  const checks = [];
+  const gaps = [];
+
+  // Collect all text content and properties from components
+  const allText = components.map(c => {
+    const texts = [c.textContent, c.text, c.label, c.placeholder, c.description, c.name];
+    return texts.filter(Boolean).join(' ').toLowerCase();
+  }).join(' ');
+
+  const allTypes = new Set(components.map(c => c.component));
+
+  // ── Check fields ──
+  for (const field of expectations.fields) {
+    const found = allText.includes(field) ||
+      components.some(c => (c.label || '').toLowerCase().includes(field) ||
+        (c.placeholder || '').toLowerCase().includes(field) ||
+        (c.name || '').toLowerCase().includes(field));
+    checks.push({
+      category: 'field',
+      expected: field,
+      found,
+      detail: found ? `Found "${field}" in component properties` : `Missing field: "${field}"`,
+    });
+    if (!found) gaps.push(`Missing field "${field}"`);
+  }
+
+  // ── Check component types ──
+  for (const type of expectations.componentTypes) {
+    const mappedTypes = TYPE_MAP[type] || [type.charAt(0).toUpperCase() + type.slice(1)];
+    const found = mappedTypes.some(t => allTypes.has(t));
+    checks.push({
+      category: 'componentType',
+      expected: type,
+      found,
+      detail: found ? `Found ${type} component` : `Missing component type: ${type}`,
+    });
+    if (!found) gaps.push(`Missing ${type} component`);
+  }
+
+  // ── Check quantities ──
+  for (const { count, type } of expectations.quantities) {
+    const mappedTypes = TYPE_MAP[type] || [type.charAt(0).toUpperCase() + type.slice(1)];
+    const actual = components.filter(c => mappedTypes.some(t => c.component === t)).length;
+    const found = actual >= count;
+    checks.push({
+      category: 'quantity',
+      expected: `${count} ${type}(s)`,
+      found,
+      detail: found ? `Found ${actual} ${type}(s) (expected ${count})` : `Only ${actual} ${type}(s), expected ${count}`,
+    });
+    if (!found) gaps.push(`Expected ${count} ${type}(s), found ${actual}`);
+  }
+
+  // ── Check actions ──
+  for (const action of expectations.actions) {
+    const found = allText.includes(action) ||
+      components.some(c => c.component === 'Button' && (c.text || '').toLowerCase().includes(action));
+    checks.push({
+      category: 'action',
+      expected: action,
+      found,
+      detail: found ? `Found "${action}" action` : `Missing action: "${action}"`,
+    });
+    if (!found) gaps.push(`Missing "${action}" action`);
+  }
+
+  // ── Check specific content ──
+  for (const text of expectations.content) {
+    const found = allText.includes(text.toLowerCase());
+    checks.push({
+      category: 'content',
+      expected: text,
+      found,
+      detail: found ? `Found content "${text}"` : `Missing content: "${text}"`,
+    });
+    if (!found) gaps.push(`Missing content "${text}"`);
+  }
+
+  // ── Score ──
+  const total = checks.length;
+  const passed = checks.filter(c => c.found).length;
+  const score = total > 0 ? Math.round((passed / total) * 100) / 100 : 1;
+
+  return { score, checks, gaps };
+}
+
+/**
+ * Full intent alignment check — extract + verify in one call.
+ *
+ * @param {string} intent
+ * @param {object[]} components
+ * @returns {{ score: number, checks: object[], gaps: string[], expectations: object }}
+ */
+export function checkIntentAlignment(intent, components) {
+  const expectations = extractExpectations(intent);
+  const result = verifyAlignment(components, expectations);
+  return { ...result, expectations };
+}

package/intent-categorizer.js

@@ -0,0 +1,97 @@
+/**
+ * Intent Categorizer
+ *
+ * Maps free-text intents to a taxonomy of UI categories using keyword matching.
+ * Used by the feedback analyzer to aggregate metrics per intent type.
+ */
+
+const CATEGORY_RULES = [
+  // Form categories
+  { category: 'form/login',    keywords: ['login', 'sign in', 'signin', 'log in', 'authentication'] },
+  { category: 'form/signup',   keywords: ['signup', 'sign up', 'register', 'registration', 'create account', 'onboarding'] },
+  { category: 'form/contact',  keywords: ['contact', 'contact us', 'reach out', 'get in touch', 'enquiry', 'inquiry'] },
+  { category: 'form/settings', keywords: ['settings', 'preferences', 'config', 'configuration', 'account settings', 'profile edit'] },
+  { category: 'form/checkout', keywords: ['checkout', 'check out', 'payment', 'billing', 'purchase'] },
+
+  // Data categories
+  { category: 'data/table',     keywords: ['table', 'data table', 'spreadsheet', 'grid view', 'list view', 'datagrid'] },
+  { category: 'data/dashboard', keywords: ['dashboard', 'kpi', 'metrics', 'analytics', 'overview', 'summary panel', 'stats'] },
+  { category: 'data/chart',     keywords: ['chart', 'graph', 'visualization', 'pie chart', 'bar chart', 'line chart', 'histogram'] },
+
+  // Layout categories
+  { category: 'layout/landing', keywords: ['landing', 'landing page', 'homepage', 'hero', 'splash'] },
+  { category: 'layout/profile', keywords: ['profile', 'user profile', 'avatar', 'bio', 'about me'] },
+  { category: 'layout/pricing', keywords: ['pricing', 'pricing table', 'plans', 'subscription', 'tier'] },
+
+  // Navigation categories
+  { category: 'nav/sidebar', keywords: ['sidebar', 'side nav', 'navigation menu', 'drawer', 'side panel'] },
+  { category: 'nav/tabs',    keywords: ['tabs', 'tab bar', 'tabbed', 'tab navigation', 'tab panel'] },
+
+  // Agent categories
+  { category: 'agent/chat',         keywords: ['chat', 'chatbot', 'messenger', 'conversation', 'messaging', 'chat interface'] },
+  { category: 'agent/notification', keywords: ['notification', 'alert', 'toast', 'snackbar', 'banner', 'announcement'] },
+
+  // Content categories
+  { category: 'content/blog', keywords: ['blog', 'article', 'post', 'news', 'editorial', 'content feed'] },
+  { category: 'content/faq',  keywords: ['faq', 'frequently asked', 'questions', 'help center', 'knowledge base', 'accordion'] },
+
+  // Commerce categories
+  { category: 'commerce/product', keywords: ['product', 'product card', 'product page', 'product detail', 'item detail', 'catalog'] },
+  { category: 'commerce/cart',    keywords: ['cart', 'shopping cart', 'basket', 'bag'] },
+  { category: 'commerce/order',   keywords: ['order', 'order history', 'order summary', 'receipt', 'invoice', 'order tracking'] },
+
+  // Workflow categories
+  { category: 'workflow/wizard',  keywords: ['wizard', 'stepper', 'multi-step', 'step form', 'onboard flow', 'setup wizard'] },
+  { category: 'workflow/kanban',  keywords: ['kanban', 'board', 'task board', 'trello', 'project board', 'drag and drop'] },
+
+  // Status categories
+  { category: 'status/error',   keywords: ['error', 'error page', '404', '500', 'not found', 'something went wrong'] },
+  { category: 'status/empty',   keywords: ['empty state', 'no results', 'no data', 'zero state', 'blank slate'] },
+  { category: 'status/loading', keywords: ['loading', 'skeleton', 'spinner', 'progress', 'placeholder'] },
+];
+
+/**
+ * Categorize a free-text intent into a UI taxonomy category.
+ *
+ * @param {string} intent — Free-text intent string
+ * @returns {{ category: string, confidence: number }}
+ */
+export function categorizeIntent(intent) {
+  if (!intent || typeof intent !== 'string') {
+    return { category: 'other', confidence: 0 };
+  }
+
+  const lower = intent.toLowerCase().trim();
+  let bestCategory = 'other';
+  let bestScore = 0;
+
+  for (const rule of CATEGORY_RULES) {
+    let matchCount = 0;
+    let longestMatch = 0;
+
+    for (const kw of rule.keywords) {
+      if (lower.includes(kw)) {
+        matchCount++;
+        longestMatch = Math.max(longestMatch, kw.length);
+      }
+    }
+
+    if (matchCount === 0) continue;
+
+    // Score: multi-word keyword matches get higher confidence,
+    // more matches within a category = higher confidence
+    const kwLenBonus = longestMatch / lower.length; // longer keyword relative to intent = more specific
+    const multiMatchBonus = Math.min(matchCount * 0.15, 0.3);
+    const score = 0.5 + kwLenBonus * 0.3 + multiMatchBonus;
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestCategory = rule.category;
+    }
+  }
+
+  return {
+    category: bestCategory,
+    confidence: Math.min(Math.round(bestScore * 100) / 100, 1),
+  };
+}

package/intent-gate.js

@@ -0,0 +1,155 @@
+/**
+ * Intent Gate — Detect whether a user message is conversational (question,
+ * greeting, meta-question) vs. a UI generation request.
+ *
+ * Used by the chat setup to route non-generation messages to a text reply
+ * instead of the full 6-stage pipeline.
+ */
+
+/** Question starters that signal conversational intent */
+const QUESTION_STARTERS = /^\s*(what|how|why|can you|could you|tell me|explain|describe|help|who|where|when|is there|are there|do you|does|did|will|should|would|which|list|show me how)\b/i;
+
+/** Greetings and social signals */
+const GREETINGS = /^\s*(hi|hey|hello|thanks|thank you|bye|goodbye|ok|okay|sure|great|nice|cool|awesome|good|perfect)\b/i;
+
+/** Explicit meta-questions about the system itself */
+const META_PATTERNS = [
+  /what\s+(components?|types?|elements?)\s+(are|do|can)/i,
+  /available\s+(components?|types?|elements?)/i,
+  /how\s+(does|do)\s+(this|it|the system|gen ui|a2ui)/i,
+  /what\s+can\s+(you|this|it)\s+(do|generate|create|build)/i,
+  /help\s+me\s+understand/i,
+  /list\s+(of\s+)?(components?|types?|elements?)/i,
+  /what\s+(is|are)\s+(a2ui|agentui|agent ui|gen ui)/i,
+  /show\s+me\s+(the\s+)?(components?|options?|catalog)/i,
+  /explain\s+(the|how|what|a)/i,
+  /how\s+(to|do\s+I)\s+(use|create|build|make)/i,
+  /what\s+would\s+.+\s+look\s+like/i,
+  /show\s+me\s+how/i,
+];
+
+/** Content that is clearly not a UI intent (injection, noise, gibberish) */
+const NOISE_PATTERNS = [
+  /^<[^>]+>/,              // Starts with HTML tag
+  /^\s*[^\w\s]{3,}/,      // Starts with 3+ non-word chars
+];
+
+/** Vague, motivational, or abstract phrases with no UI-describing language.
+ *  These are common conversational inputs that the LLM hallucinates UIs from. */
+const VAGUE_PATTERNS = [
+  /^(do|just|go|let'?s|get|keep|stay|stop|try|move|make it|finish|start|begin|end|run)\b.{0,30}$/i,  // short imperative without UI nouns
+  /\b(you gotta|gotta do|no excuses|believe|motivat|inspir|goal|dream|life|love|hate|feel|think about)\b/i,
+  /\b(what is preventing|what stops|why can't|why won't)\b/i,  // philosophical/motivational questions
+  /\b(do it|get it done|let'?s go|make it happen|just do it|never give up)\b/i,  // motivational slogans
+];
+
+/** Tool-use and action-oriented intents that should be handled conversationally,
+ *  not as UI generation requests. These are commands directed at the system. */
+const TOOL_USE_PATTERNS = [
+  /\b(create|file|write|open|submit|log)\s+(a\s+)?(ticket|bug|issue|report|feature request)/i,
+  /\b(report|flag)\s+(a\s+)?(bug|issue|problem|error|regression)/i,
+  /\b(why|how come)\s+(does|did|is|was|are)\b/i,   // "why does X do Y" — asking for rationale
+  /\bthis\s+(is|looks?)\s+(broken|wrong|buggy|off|weird|strange)/i,
+  /\b(fix|repair|debug|investigate)\s+(this|the|that)/i,
+  /\bsomething\s+(is|seems|looks?)\s+(wrong|broken|off)/i,
+  /\bmark\s+(this|it)\s+as\b/i,
+  /\b(save|bookmark|pin)\s+(this|the)\s+(pattern|output|result)/i,
+];
+
+/**
+ * Determine if a user message is conversational (should get a text reply)
+ * or a UI generation request (should go through the pipeline).
+ *
+ * @param {string} text — Raw user input
+ * @param {{ confidence: number, matchedSignals: string[] }} classifyResult — From classifyIntent()
+ * @returns {{ conversational: boolean, reason: string }}
+ */
+export function isConversational(text, classifyResult) {
+  const trimmed = (text ?? '').trim();
+  if (!classifyResult || typeof classifyResult !== 'object') {
+    classifyResult = { confidence: 0, matchedSignals: [] };
+  }
+
+  // Very short messages without generation keywords are likely conversational
+  if (trimmed.length < 5 && classifyResult.confidence === 0) {
+    return { conversational: true, reason: 'short-input' };
+  }
+
+  // Noise/injection detection — not a real intent
+  for (const pattern of NOISE_PATTERNS) {
+    if (pattern.test(trimmed) && classifyResult.confidence === 0) {
+      return { conversational: true, reason: 'noise-input' };
+    }
+  }
+
+  // Explicit meta-questions about the system → always conversational
+  for (const pattern of META_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return { conversational: true, reason: 'meta-question' };
+    }
+  }
+
+  // Tool-use commands (create ticket, report bug, etc.) → conversational
+  for (const pattern of TOOL_USE_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return { conversational: true, reason: 'tool-use' };
+    }
+  }
+
+  // Vague / motivational / abstract input with no or weak domain signals
+  // Catches "do what you gotta do", "just do it", "what is preventing you?", etc.
+  // These have zero genuine UI intent but the LLM hallucinates full UIs from them.
+  if (classifyResult.confidence < 0.2) {
+    for (const pattern of VAGUE_PATTERNS) {
+      if (pattern.test(trimmed)) {
+        return { conversational: true, reason: 'vague-or-abstract' };
+      }
+    }
+  }
+
+  // Greetings with no generation signals
+  if (GREETINGS.test(trimmed) && classifyResult.confidence === 0) {
+    return { conversational: true, reason: 'greeting' };
+  }
+
+  // High confidence in a domain → generation request
+  if (classifyResult.confidence >= 0.3) {
+    return { conversational: false, reason: 'high-domain-confidence' };
+  }
+
+  // Has matched at least 2 domain signals → generation
+  if (classifyResult.matchedSignals?.length >= 2) {
+    return { conversational: false, reason: 'multiple-domain-signals' };
+  }
+
+  // Question pattern with single low-confidence signal → conversational
+  // Key insight: "explain the card content model" has 1 signal ("card") but
+  // the leading "explain" means the user wants information, not generation.
+  if (QUESTION_STARTERS.test(trimmed) && classifyResult.matchedSignals?.length <= 1) {
+    return { conversational: true, reason: 'question-single-signal' };
+  }
+
+  // Greetings even with some confidence → still conversational
+  if (GREETINGS.test(trimmed) && classifyResult.confidence < 0.2) {
+    return { conversational: true, reason: 'greeting-low-confidence' };
+  }
+
+  // Default: if there's any domain signal at all, treat as generation
+  if (classifyResult.confidence > 0) {
+    return { conversational: false, reason: 'has-domain-signal' };
+  }
+
+  // No signals — check for question marks or question patterns
+  if (trimmed.endsWith('?')) {
+    return { conversational: true, reason: 'ends-with-question-mark' };
+  }
+
+  // No domain signals at all — this input doesn't describe UI.
+  // Phrases like "do what you gotta do", "what is preventing you?", or
+  // motivational text have zero keyword overlap with any UI domain.
+  // Route to conversational so the system can ask for clarification
+  // instead of hallucinating a UI from abstract text.
+  // Legitimate UI intents like "sidebar with navigation" will have
+  // domain signals (sidebar → layout/navigation) and be caught above.
+  return { conversational: true, reason: 'no-ui-signals' };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@adia-ai/a2ui-retrieval",
+  "version": "0.0.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"
+  },
+  "files": [
+    "*.js",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adiahealth/gen-ui-kit.git",
+    "directory": "packages/a2ui/retrieval"
+  },
+  "dependencies": {
+    "@adia-ai/a2ui-utils": "^0.0.2"
+  }
+}