@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/intent-classifier.mjs

@@ -0,0 +1,253 @@
+/**
+ * lib/intent-classifier.mjs — LLM-augmented routing verification.
+ *
+ * Keyword classifiers in orchestration-policy.mjs match by substring, which
+ * structurally cannot distinguish "fundamentally about X" from "casually
+ * mentions X". The verifier asks a fast-tier model that question per
+ * flavor match. Dispatch trusts the keyword verdict so requests never wait
+ * on an LLM round-trip; the verifier fires in the background and writes
+ * its agreement record to `~/.cx/intent-verifications.jsonl` for offline
+ * analysis (replay later to find low-agreement flavors that need keyword
+ * rewording, or to re-introduce inline gating behind a confidence threshold
+ * tuned on real data).
+ *
+ * Public API:
+ *   verifyIntent({ request, specialist, flavor, matchedKeywords, modelCaller })
+ *     → { verified, confidence, reason, source, latencyMs }
+ *   verifyRoute(route, { request, modelCaller, logger })
+ *     → original route + { verificationsPending: <count> }; background
+ *       verifications fire via the logger and do not block the caller
+ *   resetCache() — for tests
+ *
+ * `modelCaller` and `logger` are dependency-injected for deterministic
+ * tests; defaults call the OpenRouter / Anthropic-direct chain mirrored
+ * from lib/schema-infer.mjs and append to the JSONL log.
+ */
+
+import crypto from 'node:crypto';
+import { readCurrentModels, readOpenRouterApiKeyFromOpenCodeConfig } from './model-router.mjs';
+import { getUserEnvPath } from './env-config.mjs';
+import { logIntentVerification } from './telemetry/intent-verifications.mjs';
+
+export const INTENT_VERIFY_TIMEOUT_MS = 3000;
+export const CONFIDENCE_THRESHOLD = 0.6;
+
+const CACHE = new Map();
+const CACHE_MAX = 256;
+
+const SYSTEM_PROMPT = `You judge whether a keyword-based routing classifier match reflects the true intent of a request, or whether the keyword appears incidentally.
+
+Respond with strict JSON only:
+{"verified": <boolean>, "confidence": <number 0.0-1.0>, "reason": "<one short sentence>"}
+
+Verified=true means the request is fundamentally about the candidate flavor. Verified=false means the keyword appears casually or the request is about something else.`;
+
+function cacheKey({ request, specialist, flavor }) {
+  return crypto.createHash('sha1').update(`${specialist}|${flavor}|${request}`).digest('hex');
+}
+
+function cacheGet(key) {
+  const hit = CACHE.get(key);
+  if (!hit) return null;
+  CACHE.delete(key);
+  CACHE.set(key, hit);
+  return hit;
+}
+
+function cacheSet(key, value) {
+  CACHE.set(key, value);
+  if (CACHE.size > CACHE_MAX) {
+    const firstKey = CACHE.keys().next().value;
+    CACHE.delete(firstKey);
+  }
+}
+
+export function resetCache() {
+  CACHE.clear();
+}
+
+function isApiKeyConfigured() {
+  if (process.env.ANTHROPIC_API_KEY) return true;
+  if (process.env.OPENROUTER_API_KEY) return true;
+  try {
+    if (readOpenRouterApiKeyFromOpenCodeConfig()) return true;
+  } catch { /* ignore */ }
+  return false;
+}
+
+function buildUserContent({ request, specialist, flavor, matchedKeywords = [] }) {
+  return `Request: "${request}"
+Matched specialist: ${specialist}
+Candidate flavor: ${flavor}
+Matched keywords: ${JSON.stringify(matchedKeywords)}
+
+Is this request fundamentally about ${flavor}, or do the matched keywords appear incidentally?`;
+}
+
+function parseJudgeOutput(text) {
+  const trimmed = (text || '').trim();
+  const jsonStart = trimmed.indexOf('{');
+  const jsonEnd = trimmed.lastIndexOf('}');
+  if (jsonStart < 0 || jsonEnd <= jsonStart) {
+    throw new Error('No JSON object in judge output');
+  }
+  const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd + 1));
+  if (typeof parsed.verified !== 'boolean') throw new Error('verified must be boolean');
+  const confidence = Number(parsed.confidence);
+  if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+    throw new Error('confidence must be number in [0,1]');
+  }
+  return {
+    verified: parsed.verified,
+    confidence,
+    reason: String(parsed.reason || '').slice(0, 240),
+  };
+}
+
+async function fetchWithTimeout(url, options, timeoutMs = INTENT_VERIFY_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(url, { ...options, signal: controller.signal });
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function defaultModelCaller({ system, user }) {
+  const orKey = process.env.OPENROUTER_API_KEY || readOpenRouterApiKeyFromOpenCodeConfig();
+  const anthropicKey = process.env.ANTHROPIC_API_KEY;
+  if (!orKey && !anthropicKey) throw new Error('no model api key configured');
+
+  const envPath = getUserEnvPath();
+  const configured = readCurrentModels(envPath, {});
+  const modelId = configured.fast || 'anthropic/claude-haiku-4-5-20251001';
+  const isAnthropicDirect = /^anthropic\//.test(modelId);
+
+  if (isAnthropicDirect && anthropicKey) {
+    const res = await fetchWithTimeout('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'x-api-key': anthropicKey,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: modelId.replace(/^anthropic\//, ''),
+        max_tokens: 256,
+        system,
+        messages: [{ role: 'user', content: user }],
+      }),
+    });
+    if (!res.ok) throw new Error(`anthropic ${res.status}`);
+    const data = await res.json();
+    return data.content?.[0]?.text || '';
+  }
+
+  if (orKey) {
+    const res = await fetchWithTimeout('https://openrouter.ai/api/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${orKey}`,
+        'content-type': 'application/json',
+        'HTTP-Referer': 'https://github.com/construct',
+      },
+      body: JSON.stringify({
+        model: modelId.replace(/^openrouter\//, ''),
+        max_tokens: 256,
+        messages: [
+          { role: 'system', content: system },
+          { role: 'user', content: user },
+        ],
+      }),
+    });
+    if (!res.ok) throw new Error(`openrouter ${res.status}`);
+    const data = await res.json();
+    return data.choices?.[0]?.message?.content || '';
+  }
+
+  throw new Error('no usable model configured');
+}
+
+export async function verifyIntent({ request, specialist, flavor, matchedKeywords = [], modelCaller = defaultModelCaller } = {}) {
+  if (!flavor) {
+    return { verified: true, confidence: 1, source: 'no-flavor', reason: '', latencyMs: 0 };
+  }
+  if (process.env.CONSTRUCT_INTENT_VERIFY === 'off') {
+    return { verified: true, confidence: 1, source: 'disabled', reason: 'env opt-out', latencyMs: 0 };
+  }
+  if (modelCaller === defaultModelCaller && !isApiKeyConfigured()) {
+    return { verified: true, confidence: 1, source: 'fallback', reason: 'no model api key', latencyMs: 0 };
+  }
+
+  const key = cacheKey({ request, specialist, flavor });
+  const cached = cacheGet(key);
+  if (cached) return { ...cached, source: 'cache' };
+
+  const start = Date.now();
+  try {
+    const text = await modelCaller({
+      system: SYSTEM_PROMPT,
+      user: buildUserContent({ request, specialist, flavor, matchedKeywords }),
+    });
+    const parsed = parseJudgeOutput(text);
+    const record = { ...parsed, source: 'llm', latencyMs: Date.now() - start };
+    cacheSet(key, record);
+    return record;
+  } catch (err) {
+    return {
+      verified: true,
+      confidence: 1,
+      source: 'fallback',
+      reason: `intent-verify error: ${err.message}`,
+      latencyMs: Date.now() - start,
+    };
+  }
+}
+
+// Map keyword classifier → matched keywords for explainability in the prompt.
+// Kept here (not in orchestration-policy) so the classifier module stays
+// the canonical source of "what does verified mean for this role."
+const ROLE_PROMPT_KEYWORDS = {
+  productManager: ['platform', 'enterprise', 'ai-product', 'growth', 'go-to-market'],
+  architect: ['ai-systems', 'integration', 'data model', 'enterprise', 'platform'],
+  qa: ['ai-eval', 'api-contract', 'data-pipeline', 'web-ui'],
+  security: ['ai', 'privacy', 'supply-chain', 'cloud', 'appsec'],
+  dataAnalyst: ['product-intelligence', 'experiment', 'telemetry', 'product-metrics'],
+  dataEngineer: ['vector-retrieval', 'warehouse', 'pipeline'],
+};
+
+export function verifyRoute(route, { request, modelCaller = defaultModelCaller, logger = logIntentVerification } = {}) {
+  if (!route || !route.roleFlavors) return route;
+
+  let pending = 0;
+  for (const [role, flavor] of Object.entries(route.roleFlavors)) {
+    if (!flavor) continue;
+    pending += 1;
+    const specialist = `cx-${role.replace(/([A-Z])/g, '-$1').toLowerCase()}`;
+    verifyIntent({
+      request,
+      specialist,
+      flavor,
+      matchedKeywords: ROLE_PROMPT_KEYWORDS[role] || [],
+      modelCaller,
+    })
+      .then((result) => {
+        logger({
+          request,
+          specialist,
+          flavor,
+          keywordVerdict: true,
+          llmVerdict: result.verified,
+          agreed: result.verified,
+          confidence: result.confidence,
+          reason: result.reason,
+          source: result.source,
+          latencyMs: result.latencyMs,
+        });
+      })
+      .catch(() => { /* fire and forget; logger swallows its own errors */ });
+  }
+
+  return { ...route, verificationsPending: pending };
+}

package/lib/knowledge/layout.mjs

@@ -0,0 +1,72 @@
+/**
+ * lib/knowledge/layout.mjs — canonical .cx/knowledge/ directory layout.
+ *
+ * Single source of truth for the typed knowledge subdirectories. Import this
+ * from inbox.mjs, document-ingest.mjs, and anywhere that writes into .cx/.
+ *
+ * Directory structure:
+ *   .cx/knowledge/
+ *     internal/    — team notes, meeting minutes, internal specs, ADRs, PRDs
+ *     external/    — customer feedback, support tickets, external research
+ *     decisions/   — architecture decision records, design decisions
+ *     how-tos/     — runbooks, setup guides, operational procedures, playbooks
+ *     reference/   — specs, RFCs, architecture docs, schemas, API references
+ *
+ * Inbox / ingest target names map 1-to-1 to subdirectory names.
+ * Use KNOWLEDGE_SUBDIRS to enumerate all valid targets.
+ * Use knowledgeDirForCategory() to pick the right subdir from an obs category.
+ * Use inferKnowledgeTarget() to pick the right subdir from a file path.
+ */
+
+export const KNOWLEDGE_ROOT = '.cx/knowledge';
+
+/**
+ * All valid knowledge subdirectory names.
+ * These are the values accepted by --target=knowledge/<name> in the ingest CLI.
+ */
+export const KNOWLEDGE_SUBDIRS = /** @type {const} */ ([
+  'internal',
+  'external',
+  'decisions',
+  'how-tos',
+  'reference',
+]);
+
+/**
+ * Map an observation category to the knowledge subdir that should store it.
+ * @param {string} category
+ * @returns {string}
+ */
+export function knowledgeDirForCategory(category) {
+  switch (category) {
+    case 'decision':     return 'decisions';
+    case 'anti-pattern': return 'internal';
+    case 'pattern':      return 'how-tos';
+    default:             return 'internal';
+  }
+}
+
+/**
+ * Infer the best knowledge subdir from a file path using naming conventions.
+ *
+ * Conventions (case-insensitive):
+ *   ADR / architecture-decision → decisions/
+ *   postmortem / incident / rca → internal/   (incident records)
+ *   spec / rfc / schema / api-ref → reference/
+ *   runbook / playbook / how-to / setup / guide → how-tos/
+ *   customer / feedback / support / external → external/
+ *   everything else → internal/
+ *
+ * @param {string} filePath
+ * @returns {string}  one of KNOWLEDGE_SUBDIRS
+ */
+export function inferKnowledgeTarget(filePath) {
+  const name = filePath.toLowerCase();
+
+  if (/\badr[-_]\d/.test(name) || /architecture.decision/.test(name)) return 'decisions';
+  if (/\bspec\b|\brfc\b|\bschema\b|\bapi.ref/.test(name))             return 'reference';
+  if (/\brunbook\b|\bplaybook\b|\bhow.to\b|\bsetup\b|\bguide\b/.test(name)) return 'how-tos';
+  if (/\bcustomer\b|\bfeedback\b|\bsupport\b|\bexternal\b/.test(name)) return 'external';
+  if (/\bpost.?mortem\b|\bincident\b|\brca\b/.test(name))             return 'internal';
+  return 'internal';
+}

package/lib/knowledge/rag.mjs

@@ -0,0 +1,331 @@
+/**
+ * lib/knowledge/rag.mjs — Retrieval-Augmented Generation pipeline.
+ *
+ * Indexes all knowledge sources into a unified corpus and answers natural-
+ * language queries by retrieving the most relevant chunks, then synthesising
+ * a response via the `claude` CLI.
+ *
+ * Sources indexed:
+ *   - Observations       (.cx/observations/)
+ *   - Artifacts          (docs/adr/, docs/prd/, docs/rfc/)
+ *   - Snapshots          (.cx/snapshot.md + any configured output paths)
+ *   - Approval queue     (.cx/approval-queue.jsonl)
+ *
+ * Retrieval strategy:
+ *   Hybrid BM25 + cosine similarity (hashing-bow-v1 embeddings, zero deps).
+ *   Top-K chunks from each source are merged, deduplicated by id, and re-ranked
+ *   by a combined score before being assembled into a prompt context window.
+ *
+ * Context budget:
+ *   MAX_CONTEXT_CHARS limits total text sent to the model. Chunks are trimmed
+ *   to fit. The budget is intentionally conservative so the answer fits in a
+ *   single claude --print call.
+ *
+ * Zero external deps — uses only the existing embeddings primitives.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { cosineSimilarity, rankByBm25 } from '../storage/embeddings.mjs';
+import { embedSync as embedText } from '../storage/embeddings-legacy.mjs';
+import { listObservations, getObservation } from '../observation-store.mjs';
+import { listArtifacts } from '../embed/artifact.mjs';
+
+const MAX_CONTEXT_CHARS = 12_000;
+const MAX_CHUNKS = 12;
+const CHUNK_PREVIEW = 600;
+
+// MIN_SCORE under RRF is a soft floor: with k=60 a top-1 doc in both rankers
+// scores ~0.033, so any positive score means the document appeared in at
+// least one ranker. We keep a tiny epsilon to drop chunks that scored 0
+// from BOTH rankers (which can happen for items not in either ranked list).
+const MIN_SCORE = 1e-6;
+
+// ── Source loaders ─────────────────────────────────────────────────────────
+
+/**
+ * Load all observations as indexable chunks.
+ */
+function loadObservationChunks(rootDir) {
+  try {
+    const entries = listObservations(rootDir, {});
+    return entries.map((e) => {
+      const full = getObservation(rootDir, e.id);
+      return {
+        id: `obs:${e.id}`,
+        source: 'observation',
+        title: e.summary || 'Observation',
+        body: [full?.content, full?.summary].filter(Boolean).join('\n'),
+        tags: e.tags || [],
+        role: e.role || null,
+        category: e.category || null,
+        createdAt: e.createdAt || null,
+      };
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Load markdown files from a directory tree as indexable chunks.
+ */
+function loadMarkdownChunks(dir, source) {
+  if (!fs.existsSync(dir)) return [];
+  const chunks = [];
+  const walk = (d) => {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const full = path.join(d, entry.name);
+      if (entry.isDirectory()) { walk(full); continue; }
+      if (!entry.name.endsWith('.md')) continue;
+      try {
+        const content = fs.readFileSync(full, 'utf8');
+        const titleMatch = content.match(/^#\s+(.+)/m);
+        chunks.push({
+          id: `${source}:${path.relative(process.cwd(), full)}`,
+          source,
+          title: titleMatch ? titleMatch[1].trim() : entry.name,
+          body: content,
+          filePath: full,
+          createdAt: fs.statSync(full).mtime.toISOString(),
+        });
+      } catch { /* skip unreadable */ }
+    }
+  };
+  walk(dir);
+  return chunks;
+}
+
+/**
+ * Load artifact docs (ADR, PRD, RFC) from docs/.
+ */
+function loadArtifactChunks(rootDir) {
+  const chunks = [];
+  for (const subdir of ['docs/adr', 'docs/prd', 'docs/rfc', 'docs/concepts/architecture.md']) {
+    const full = path.resolve(rootDir, subdir);
+    if (subdir.endsWith('.md')) {
+      if (!fs.existsSync(full)) continue;
+      try {
+        const content = fs.readFileSync(full, 'utf8');
+        const titleMatch = content.match(/^#\s+(.+)/m);
+        chunks.push({
+          id: `artifact:${subdir}`,
+          source: 'artifact',
+          title: titleMatch ? titleMatch[1].trim() : subdir,
+          body: content,
+          filePath: full,
+          createdAt: fs.statSync(full).mtime.toISOString(),
+        });
+      } catch { /* skip */ }
+    } else {
+      chunks.push(...loadMarkdownChunks(full, 'artifact'));
+    }
+  }
+  return chunks;
+}
+
+/**
+ * Load snapshot markdown files.
+ */
+function loadSnapshotChunks(rootDir) {
+  const candidates = [
+    path.resolve(rootDir, '.cx/snapshot.md'),
+    path.resolve(rootDir, '.cx/snapshots'),
+  ];
+  const chunks = [];
+  for (const c of candidates) {
+    if (!fs.existsSync(c)) continue;
+    if (fs.statSync(c).isDirectory()) {
+      chunks.push(...loadMarkdownChunks(c, 'snapshot'));
+    } else {
+      try {
+        const content = fs.readFileSync(c, 'utf8');
+        chunks.push({
+          id: 'snapshot:.cx/snapshot.md',
+          source: 'snapshot',
+          title: 'Latest Snapshot',
+          body: content,
+          filePath: c,
+          createdAt: fs.statSync(c).mtime.toISOString(),
+        });
+      } catch { /* skip */ }
+    }
+  }
+  return chunks;
+}
+
+// ── Index builder ──────────────────────────────────────────────────────────
+
+/**
+ * Build a full in-memory corpus from all sources.
+ * Each chunk gets an embedding vector for cosine scoring.
+ */
+export function buildCorpus(rootDir = process.cwd()) {
+  const chunks = [
+    ...loadObservationChunks(rootDir),
+    ...loadArtifactChunks(rootDir),
+    ...loadSnapshotChunks(rootDir),
+  ];
+
+  // Embed each chunk
+  return chunks.map((chunk) => ({
+    ...chunk,
+    embedding: embedText(`${chunk.title} ${chunk.body}`.slice(0, 2000)),
+  }));
+}
+
+// ── Retrieval ──────────────────────────────────────────────────────────────
+
+/**
+ * Retrieve the top-K most relevant chunks for a query.
+ *
+ * Pipeline:
+ *   1. BM25 ranks the FULL corpus (no top-K window so chunks outside any
+ *      bounded slice still contribute).
+ *   2. Cosine ranks the FULL corpus.
+ *   3. RRF fuses the two ranked lists into one (corpus-agnostic; rank-only).
+ *   4. MMR reranks the fused candidates with λ=0.7 to drop near-duplicates
+ *      while preserving relevance.
+ *
+ * Both fuser and reranker are pluggable via the engine layer
+ * (lib/engine/index.mjs); callers can swap RRF for any other Fuser plugin
+ * and MMR for any other Reranker plugin without touching this module. The
+ * defaults are wired in lib/engine/defaults.mjs.
+ *
+ * @param {string} query
+ * @param {object[]} corpus  — from buildCorpus()
+ * @param {object} [opts]
+ * @returns {Promise<object[]>} top chunks with `.score` (RRF) and `.mmrScore`,
+ *   sorted by MMR order. Returns a Promise so engine-aligned chunkers and
+ *   embedders can plug in without changing the call surface.
+ */
+export async function retrieve(query, corpus, { topK = MAX_CHUNKS, minScore = MIN_SCORE } = {}) {
+  if (!query || corpus.length === 0) return [];
+
+  const queryEmbedding = embedText(query);
+
+  const bm25Ranked = rankByBm25(
+    corpus.map((c) => ({ ...c, text: `${c.title} ${c.body}` })),
+    query,
+    { limit: corpus.length },
+  );
+
+  const cosineRanked = corpus
+    .map((chunk) => ({
+      ...chunk,
+      score: cosineSimilarity(queryEmbedding, chunk.embedding || []),
+    }))
+    .filter((c) => c.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  const { getEngine } = await import('../engine/index.mjs');
+  const engine = await getEngine({ rootDir: process.cwd() });
+  const fused = engine.layers.fuser.fuse({ bm25: bm25Ranked, cosine: cosineRanked });
+
+  const filtered = fused.filter((c) => c.score >= minScore);
+  if (filtered.length === 0) return [];
+
+  const reranked = await engine.layers.reranker.rerank(query, filtered, {
+    queryEmbedding,
+    topK,
+  });
+
+  return reranked;
+}
+
+// ── Context assembly ───────────────────────────────────────────────────────
+
+/**
+ * Format retrieved chunks into a context block for the prompt.
+ */
+export function assembleContext(chunks) {
+  let budget = MAX_CONTEXT_CHARS;
+  const parts = [];
+
+  for (const chunk of chunks) {
+    const preview = chunk.body?.slice(0, CHUNK_PREVIEW) || '';
+    const meta = [
+      chunk.source && `source:${chunk.source}`,
+      chunk.role && `role:${chunk.role}`,
+      chunk.category && `category:${chunk.category}`,
+      chunk.createdAt && `date:${chunk.createdAt.slice(0, 10)}`,
+    ].filter(Boolean).join('  ');
+
+    const block = `### ${chunk.title}\n${meta ? `_${meta}_\n` : ''}${preview}${preview.length === CHUNK_PREVIEW ? '\n…' : ''}`;
+    if (block.length > budget) break;
+    parts.push(block);
+    budget -= block.length;
+  }
+
+  return parts.join('\n\n---\n\n');
+}
+
+// ── Answer synthesis ───────────────────────────────────────────────────────
+
+const SYSTEM_PROMPT = `You are Construct's knowledge assistant. Answer questions about the project using only the provided context.
+- Be specific and cite which source you drew from (observation, artifact, snapshot).
+- If the context is insufficient, say so directly — do not speculate.
+- Keep answers concise (under 400 words unless the question demands detail).
+- Format as plain text unless the question explicitly asks for markdown.`;
+
+/**
+ * Ask a question against the knowledge base.
+ *
+ * @param {string} question
+ * @param {object} opts
+ * @param {string}   opts.rootDir
+ * @param {object[]} [opts.corpus]   — pre-built corpus (skips rebuild)
+ * @param {boolean}  [opts.dryRun]   — return retrieved chunks without calling claude
+ * @returns {{ answer: string, sources: object[], query: string }}
+ */
+export async function ask(question, { rootDir = process.cwd(), corpus, dryRun = false } = {}) {
+  const kb = corpus ?? buildCorpus(rootDir);
+  const chunks = await retrieve(question, kb);
+
+  if (dryRun) {
+    return {
+      answer: null,
+      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+      query: question,
+    };
+  }
+
+  if (chunks.length === 0) {
+    return {
+      answer: 'No relevant information found in the knowledge base for this query.',
+      sources: [],
+      query: question,
+    };
+  }
+
+  const context = assembleContext(chunks);
+  const prompt = `${SYSTEM_PROMPT}\n\n## Knowledge Base Context\n\n${context}\n\n## Question\n\n${question}\n\n## Answer`;
+
+  // Call claude CLI
+  const result = spawnSync('claude', ['--print', prompt], {
+    encoding: 'utf8',
+    timeout: 60_000,
+    env: { ...process.env },
+  });
+
+  if (result.error || result.status !== 0) {
+    // Fallback: return retrieved chunks as a structured answer
+    const fallback = chunks
+      .slice(0, 5)
+      .map((c) => `**${c.title}** (${c.source})\n${c.body?.slice(0, 300) || ''}`)
+      .join('\n\n');
+    return {
+      answer: `[Claude CLI unavailable — showing retrieved context]\n\n${fallback}`,
+      sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+      query: question,
+      cliMissing: true,
+    };
+  }
+
+  return {
+    answer: (result.stdout || '').trim(),
+    sources: chunks.map((c) => ({ id: c.id, source: c.source, title: c.title, score: c.score })),
+    query: question,
+  };
+}