md-semantic-search 0.5.0 → 1.0.2

package/src/search.ts

@@ -8,6 +8,10 @@ import { bm25Scores, matchingTerms, tokenize, fuzzyTitleAliasScores, LexicalInde
 import { collapseResults } from './collapse.js';
 import { DocumentMetadata } from './frontmatter.js';
 import { trainIVF, searchIVFCandidates, deserializeIVF, IVFIndex, ANN_THRESHOLD, DEFAULT_NPROBE } from './ivf.js';
+import { buildRelationshipGraph, computePageRank, expandGraphNeighborhood, RelationshipGraph } from './wikilinks.js';
+import { evaluateFilter, FilterNode } from './filter.js';
+import { deserializeBinaryIndex } from './binary-format.js';
+import { dequantizeFromInt8 } from './quantization.js';
 
 export { tokenize } from './lexical.js';
 
@@ -36,15 +40,22 @@ export function keywordScores(chunks: IndexChunk[], query: string): number[] {
   });
 }
 
-export function rrf(rankings: Array<Array<{ idx: number; score: number }>>, k = 60): Map<number, number> {
+export function rrf(
+  rankings: Array<Array<{ idx: number; score: number }>>,
+  k = 60,
+  weights?: number[]
+): Map<number, number> {
   const fused = new Map<number, number>();
-  for (const ranking of rankings) {
+  for (let rankingIdx = 0; rankingIdx < rankings.length; rankingIdx++) {
+    const ranking = rankings[rankingIdx];
+    const weight = weights ? (weights[rankingIdx] ?? 1) : 1;
+    if (weight <= 0) continue;
     const sorted = [...ranking].sort((a, b) => b.score - a.score);
     let scoreRank = 0;
     sorted.forEach((item, rank) => {
       if (item.score <= 0) return;
       if (rank > 0 && item.score < sorted[rank - 1].score) scoreRank = rank;
-      fused.set(item.idx, (fused.get(item.idx) || 0) + 1 / (k + scoreRank + 1));
+      fused.set(item.idx, (fused.get(item.idx) || 0) + weight / (k + scoreRank + 1));
     });
   }
   return fused;
@@ -155,7 +166,7 @@ export interface RuntimeChunk {
   startLine?: number;
   endLine?: number;
   meta?: DocumentMetadata;
-  vec: Float32Array;
+  vec: Float32Array | Int8Array;
 }
 
 export interface RuntimeIndexState {
@@ -167,29 +178,66 @@ export interface RuntimeIndexState {
   model: ModelDescriptor;
   queryCache: QueryEmbeddingCache;
   ivf?: IVFIndex;
+  graph?: RelationshipGraph;
+  pageRank?: Map<string, number>;
+}
+
+export function getRuntimeGraph(runtime: RuntimeIndexState): { graph: RelationshipGraph; pageRank: Map<string, number> } {
+  if (runtime.graph && runtime.pageRank) {
+    return { graph: runtime.graph, pageRank: runtime.pageRank };
+  }
+  const docsMap = new Map<string, { file: string; title?: string; meta?: DocumentMetadata; text?: string }>();
+  for (const chunk of runtime.chunks) {
+    const existing = docsMap.get(chunk.file);
+    if (!existing) {
+      docsMap.set(chunk.file, {
+        file: chunk.file,
+        title: chunk.title,
+        meta: chunk.meta,
+        text: chunk.text,
+      });
+    } else {
+      existing.text = (existing.text || '') + '\n' + chunk.text;
+    }
+  }
+  const docs = Array.from(docsMap.values());
+  const graph = buildRelationshipGraph(docs);
+  const pageRank = computePageRank(graph);
+  runtime.graph = graph;
+  runtime.pageRank = pageRank;
+  return { graph, pageRank };
 }
 
 const runtimeIndexStates = new WeakMap<IndexFile, RuntimeIndexState>();
 
 function snapshotRuntimeIndex(
   index: IndexFile,
-  validation: { schema: number; dim: number | undefined; model: ModelDescriptor; ivf?: IVFIndex }
+  validation: {
+    schema: number;
+    dim: number | undefined;
+    model: ModelDescriptor;
+    ivf?: IVFIndex;
+    rawVectorsBuffer?: Float32Array | Int8Array;
+  }
 ): RuntimeIndexState {
   const dim = validation.dim || (index.chunks[0]?.vec?.length ?? 0);
   const count = index.chunks.length;
-  const vectorsBuffer = dim > 0 ? new Float32Array(count * dim) : null;
+  const isZeroCopy = !!validation.rawVectorsBuffer;
+  const vectorsBuffer = validation.rawVectorsBuffer ?? (dim > 0 ? new Float32Array(count * dim) : null);
 
   const chunks: RuntimeChunk[] = index.chunks.map((chunk, i) => {
-    let vec: Float32Array;
+    let vec: Float32Array | Int8Array;
     if (vectorsBuffer && dim > 0) {
       const offset = i * dim;
-      if (chunk.vec instanceof Float32Array) {
-        vectorsBuffer.set(chunk.vec, offset);
-      } else {
-        const arr = chunk.vec as number[];
-        for (let j = 0; j < dim; j++) vectorsBuffer[offset + j] = arr[j];
+      if (!isZeroCopy) {
+        if (chunk.vec instanceof Float32Array || chunk.vec instanceof Int8Array) {
+          (vectorsBuffer as any).set(chunk.vec, offset);
+        } else {
+          const arr = chunk.vec as number[];
+          for (let j = 0; j < dim; j++) (vectorsBuffer as any)[offset + j] = arr[j];
+        }
       }
-      vec = vectorsBuffer.subarray(offset, offset + dim);
+      vec = (vectorsBuffer as any).subarray(offset, offset + dim);
     } else {
       vec = Float32Array.from(chunk.vec as number[]);
     }
@@ -280,7 +328,73 @@ function warnIfStale(index: IndexFile): void {
 }
 
 export function loadIndex(indexDir: string): { index: IndexFile; model: ModelDescriptor } {
+  const vectorsBinPath = path.join(indexDir, 'vectors.bin');
   const vectorsPath = path.join(indexDir, 'vectors.json');
+
+  let useBinary = false;
+  if (fs.existsSync(vectorsBinPath)) {
+    if (!fs.existsSync(vectorsPath)) {
+      useBinary = true;
+    } else {
+      try {
+        const binStat = fs.statSync(vectorsBinPath);
+        const jsonStat = fs.statSync(vectorsPath);
+        if (binStat.mtimeMs >= jsonStat.mtimeMs) {
+          useBinary = true;
+        }
+      } catch {
+        useBinary = false;
+      }
+    }
+  }
+
+  if (useBinary) {
+    try {
+      const binBuffer = fs.readFileSync(vectorsBinPath);
+      const shaBinPath = path.join(indexDir, 'vectors.bin.sha256');
+      if (fs.existsSync(shaBinPath)) {
+        const expectedHash = fs.readFileSync(shaBinPath, 'utf8').trim().split(/\s+/)[0];
+        const actualHash = crypto.createHash('sha256').update(binBuffer).digest('hex');
+        if (expectedHash && actualHash !== expectedHash) {
+          throw new Error('vectors.bin integrity check failed (SHA-256 mismatch) — run `mdss index` to rebuild.');
+        }
+      }
+      const deserialized = deserializeBinaryIndex(binBuffer);
+      const validated = validateIndexEnvelope(deserialized, vectorsBinPath, { encoding: 'loaded', validateVectors: true });
+      const index = validated.index as IndexFile;
+      const { model, dim: validatedDim } = validated;
+      const expectedDim = validatedDim ?? deserialized.dim;
+
+      warnIfStale(index);
+
+      const ivfPath = path.join(indexDir, 'ivf.json');
+      let ivf: IVFIndex | undefined;
+      if (fs.existsSync(ivfPath)) {
+        try {
+          const raw = JSON.parse(fs.readFileSync(ivfPath, 'utf8'));
+          ivf = deserializeIVF(raw);
+        } catch {}
+      }
+
+      runtimeIndexStates.set(
+        index,
+        snapshotRuntimeIndex(index, {
+          schema: validated.schema,
+          dim: expectedDim,
+          model,
+          ivf,
+          rawVectorsBuffer: deserialized.rawVectorsBuffer,
+        })
+      );
+
+      return { index, model };
+    } catch (e: any) {
+      if (e.message?.includes('integrity check failed')) throw e;
+      if (!fs.existsSync(vectorsPath)) throw e;
+      // If vectors.bin was corrupt or unreadable, fall through to vectors.json fallback
+    }
+  }
+
   if (!fs.existsSync(vectorsPath)) {
     throw new Error(`No index at ${vectorsPath}. Run \`mdss index\` first.`);
   }
@@ -358,8 +472,13 @@ export function loadIndex(indexDir: string): { index: IndexFile; model: ModelDes
 
 export const MAX_QUERY_LENGTH = 2048;
 
+export interface LoadedIndex {
+  index: IndexFile;
+  model: ModelDescriptor;
+}
+
 export interface SearchOptions {
-  loaded: { index: IndexFile; model: ModelDescriptor };
+  loaded: LoadedIndex;
   cacheDir: string;
   query: string;
   k?: number;
@@ -383,6 +502,8 @@ export interface SearchOptions {
   useQueryCache?: boolean;
   ann?: boolean;
   nprobe?: number;
+  graphBoost?: number;
+  filter?: string | FilterNode;
 }
 
 export interface SearchResultHit {
@@ -394,10 +515,13 @@ export interface SearchResultHit {
   matches: string[];
   snippet: string;
   meta?: DocumentMetadata;
+  graphScore?: number;
   explain?: {
     cosine: number;
     rrfScore: number;
     bm25Weights: { title: number; aliases: number; headingPath: number; body: number };
+    graphScore?: number;
+    pageRank?: number;
   };
   rerankScore?: number;
 }
@@ -420,8 +544,11 @@ export async function searchIndex(opts: SearchOptions): Promise<SearchResultHit[
     status,
     canonicalOnly,
     custom,
+    filter: filterExpr,
   } = opts;
 
+  const graphBoost = typeof opts.graphBoost === 'number' && Number.isFinite(opts.graphBoost) ? opts.graphBoost : 0;
+
   if (typeof query === 'string' && query.length > MAX_QUERY_LENGTH) {
     throw new Error(`query exceeds maximum length of ${MAX_QUERY_LENGTH} characters`);
   }
@@ -445,7 +572,8 @@ export async function searchIndex(opts: SearchOptions): Promise<SearchResultHit[
     type !== undefined ||
     status !== undefined ||
     canonicalOnly !== undefined ||
-    custom !== undefined;
+    custom !== undefined ||
+    filterExpr !== undefined;
 
   if (pathRes.length > 0 || sinceMs !== undefined || hasMetaFilter) {
     if (sinceMs !== undefined && !db) {
@@ -466,6 +594,9 @@ export async function searchIndex(opts: SearchOptions): Promise<SearchResultHit[
         }
         if (m < sinceMs) return false;
       }
+      if (filterExpr !== undefined) {
+        if (!evaluateFilter(filterExpr, chunk.meta, { file: chunk.file, title: chunk.title })) return false;
+      }
       if (tag !== undefined) {
         const reqTags = (Array.isArray(tag) ? tag : [tag]).map((t) => String(t).toLowerCase().replace(/^#/, ''));
         const chunkTags = chunk.meta?.tags || [];
@@ -509,7 +640,7 @@ export async function searchIndex(opts: SearchOptions): Promise<SearchResultHit[
   const useAnn = opts.ann ?? (runtime.ivf !== undefined && candidates.length >= ANN_THRESHOLD);
   if (useAnn && candidates.length >= ANN_THRESHOLD) {
     if (!runtime.ivf) {
-      const rawVecs = chunks.map((c) => c.vec);
+      const rawVecs = chunks.map((c) => (c.vec instanceof Float32Array ? c.vec : dequantizeFromInt8(c.vec)));
       runtime.ivf = trainIVF(rawVecs);
     }
     const qVecF32 = qVec instanceof Float32Array ? qVec : Float32Array.from(qVec);
@@ -529,12 +660,45 @@ export async function searchIndex(opts: SearchOptions): Promise<SearchResultHit[
 
   const pool = rerank ? rerankPool || Math.max(20, k * 3) : k;
 
+  let graphRanking: Array<{ idx: number; score: number }> = [];
+  let graphMap: Map<number, number> | undefined;
+  if (graphBoost > 0) {
+    const { graph, pageRank } = getRuntimeGraph(runtime);
+    const seedFilesMap = new Map<string, number>();
+    for (const s of semantic) {
+      if (s.score > 0) {
+        const file = chunks[s.idx].file;
+        const curr = seedFilesMap.get(file) || 0;
+        if (s.score > curr) seedFilesMap.set(file, s.score);
+      }
+    }
+    const seedFiles = Array.from(seedFilesMap.entries()).map(([file, score]) => ({ file, score }));
+    const propagationScores = expandGraphNeighborhood(graph, seedFiles, { maxDepth: 2, decay: 0.5 });
+
+    graphMap = new Map<number, number>();
+    graphRanking = candidates.map(({ chunk, idx }) => {
+      const pr = pageRank.get(chunk.file) || 0;
+      const prop = propagationScores.get(chunk.file) || 0;
+      const totalGraph = pr + prop;
+      graphMap!.set(idx, totalGraph);
+      return { idx, score: totalGraph };
+    });
+  }
+
   let ranked: Array<{ idx: number; fscore: number; cos: number; rerank?: number }>;
   if (semanticOnly) {
-    ranked = [...semantic]
-      .sort((a, b) => b.score - a.score)
-      .slice(0, pool)
-      .map((s) => ({ idx: s.idx, fscore: s.score, cos: s.score }));
+    if (graphBoost > 0) {
+      const fused = rrf([semantic, graphRanking], 60, [1, graphBoost]);
+      ranked = [...fused.entries()]
+        .map(([idx, fscore]) => ({ idx, fscore, cos: cosByIdx.get(idx)! }))
+        .sort((a, b) => b.fscore - a.fscore)
+        .slice(0, pool);
+    } else {
+      ranked = [...semantic]
+        .sort((a, b) => b.score - a.score)
+        .slice(0, pool)
+        .map((s) => ({ idx: s.idx, fscore: s.score, cos: s.score }));
+    }
   } else {
     const kw =
       lexicalState.kind === 'persisted-bm25'
@@ -551,11 +715,19 @@ export async function searchIndex(opts: SearchOptions): Promise<SearchResultHit[
       score,
     }));
 
-    const fused = rrf([semantic, kw, fuzzy]);
-    ranked = [...fused.entries()]
-      .map(([idx, fscore]) => ({ idx, fscore, cos: cosByIdx.get(idx)! }))
-      .sort((a, b) => b.fscore - a.fscore)
-      .slice(0, pool);
+    if (graphBoost > 0) {
+      const fused = rrf([semantic, kw, fuzzy, graphRanking], 60, [1, 1, 1, graphBoost]);
+      ranked = [...fused.entries()]
+        .map(([idx, fscore]) => ({ idx, fscore, cos: cosByIdx.get(idx)! }))
+        .sort((a, b) => b.fscore - a.fscore)
+        .slice(0, pool);
+    } else {
+      const fused = rrf([semantic, kw, fuzzy]);
+      ranked = [...fused.entries()]
+        .map(([idx, fscore]) => ({ idx, fscore, cos: cosByIdx.get(idx)! }))
+        .sort((a, b) => b.fscore - a.fscore)
+        .slice(0, pool);
+    }
   }
 
   if (rerank && ranked.length > 0) {
@@ -590,6 +762,8 @@ export async function searchIndex(opts: SearchOptions): Promise<SearchResultHit[
       lexicalState.kind === 'persisted-bm25'
         ? matchingTerms(lexicalState.lexical, queryTerms, r.idx)
         : queryTerms.filter((term) => tokenSet(c as any).has(term));
+    const gScore = graphMap?.get(r.idx);
+    const prScore = runtime.pageRank?.get(c.file);
     return {
       file: c.file,
       title: c.title,
@@ -599,12 +773,15 @@ export async function searchIndex(opts: SearchOptions): Promise<SearchResultHit[
       matches,
       snippet: c.text.replace(/\s+/g, ' ').slice(0, 220),
       ...(hasMetaFields(c.meta) ? { meta: c.meta } : {}),
+      ...(gScore !== undefined ? { graphScore: +gScore.toFixed(4) } : {}),
       ...(explain
         ? {
             explain: {
               cosine: +r.cos.toFixed(4),
               rrfScore: +r.fscore.toFixed(4),
               bm25Weights: { title: 3.0, aliases: 3.0, headingPath: 1.8, body: 1.0 },
+              ...(gScore !== undefined ? { graphScore: +gScore.toFixed(4) } : {}),
+              ...(prScore !== undefined ? { pageRank: +prScore.toFixed(4) } : {}),
             },
           }
         : {}),

package/src/serve.ts

@@ -10,6 +10,7 @@ import path from 'node:path';
 import { buildIndex } from './indexer.js';
 import { loadIndex, searchIndex } from './search.js';
 import { walkMarkdown, assertSafePath, ModelDescriptor } from './core.js';
+import { createFileWatcher, FileWatcher } from './watcher.js';
 
 const DEFAULT_PORT = 8747;
 const DEFAULT_HOST = '127.0.0.1';
@@ -91,14 +92,20 @@ export async function createServe(opts: CreateServeOptions): Promise<{
     healthPublic,
   };
 
+  const sockets = new Set<import('node:net').Socket>();
   const server = http.createServer((req, res) => {
     handleRequest(req, res, state).catch((e) => {
       json(res, 500, { error: e.message });
     });
   });
+  server.on('connection', (socket) => {
+    sockets.add(socket);
+    socket.on('close', () => sockets.delete(socket));
+  });
 
   let stopped = false;
   let timer: NodeJS.Timeout | null = null;
+  let resolveTimer: (() => void) | null = null;
 
   const reload = async () => {
     if (!db) return false;
@@ -190,14 +197,22 @@ export async function createServe(opts: CreateServeOptions): Promise<{
     return out;
   };
 
+  let lastFingerprint = '';
+
   const watchLoop = async () => {
     let indexedHashes = readIndexedHashes();
-    let lastFingerprint = treeContentFingerprint(scanTree());
+    lastFingerprint = treeContentFingerprint(scanTree());
     let lastChangeAt = 0;
     let pending = false;
     while (!stopped) {
-      await new Promise((r) => {
-        timer = setTimeout(r, watchInterval);
+      await new Promise<void>((r) => {
+        resolveTimer = r;
+        timer = setTimeout(() => {
+          timer = null;
+          resolveTimer = null;
+          r();
+        }, watchInterval);
+        timer.unref?.();
       });
       if (stopped) return;
       const tree = scanTree();
@@ -228,14 +243,39 @@ export async function createServe(opts: CreateServeOptions): Promise<{
     }
   };
 
+  let nativeWatcher: FileWatcher | null = null;
+
   if (watch) {
     if (!db) throw new Error('serve --watch requires --db');
+    nativeWatcher = createFileWatcher(db, () => {
+      // Prompt watchLoop settle trigger on native event
+      lastFingerprint = '';
+    }, {
+      debounceMs: watchDelay,
+      ignore,
+      log,
+    });
     watchLoop();
   }
 
   const close = async (): Promise<void> => {
     stopped = true;
-    if (timer) clearTimeout(timer);
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (resolveTimer) {
+      resolveTimer();
+      resolveTimer = null;
+    }
+    if (nativeWatcher) nativeWatcher.close();
+    server.closeAllConnections?.();
+    for (const socket of sockets) {
+      try {
+        socket.destroy();
+      } catch {}
+    }
+    sockets.clear();
     await new Promise<void>((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
   };
 
@@ -329,6 +369,8 @@ async function handleRequest(req: http.IncomingMessage, res: http.ServerResponse
         maxPerFile: payload.maxPerFile || payload.maxPerDoc,
         ann: payload.ann,
         nprobe: payload.nprobe,
+        graphBoost: payload.graphBoost,
+        filter: payload.filter,
       });
       json(res, 200, { query, k, count: results.length, results });
     } catch (e: any) {

package/src/summarize.ts

@@ -0,0 +1,98 @@
+/**
+ * Automated Note Summarization & Semantic Keyword Tagging Pipeline (issue #103).
+ *
+ * Implements zero-dependency, deterministic extractive summarization and keyphrase
+ * tag extraction to enrich note chunks with discoverable semantic metadata.
+ */
+import { tokenize } from './lexical.js';
+
+export interface NoteAnalysis {
+  tags: string[];
+  summary: string;
+}
+
+/**
+ * Extracts salient topical tags from Markdown text using term frequency and position weighting.
+ */
+export function extractKeyphraseTags(text: string, maxTags: number = 5): string[] {
+  if (!text || !text.trim()) return [];
+
+  const lines = text.split('\n');
+  const termScores = new Map<string, number>();
+
+  lines.forEach((line, lineIdx) => {
+    const isHeading = /^#{1,6}\s+/.test(line);
+    const weight = isHeading ? 3.0 : lineIdx < 3 ? 1.5 : 1.0;
+    const tokens = tokenize(line);
+
+    for (const tok of tokens) {
+      if (tok.length < 3) continue;
+      // Skip purely numeric tokens
+      if (/^\d+$/.test(tok)) continue;
+
+      const current = termScores.get(tok) || 0;
+      termScores.set(tok, current + weight);
+    }
+  });
+
+  const sorted = Array.from(termScores.entries())
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, maxTags)
+    .map(([term]) => term);
+
+  return sorted;
+}
+
+/**
+ * Generates a concise extractive summary (1-2 sentences) representing the salient points of a note.
+ */
+export function summarizePassage(text: string, maxSentences: number = 2): string {
+  if (!text || !text.trim()) return '';
+
+  // Clean Markdown formatting
+  const clean = text
+    .replace(/^#{1,6}\s+.*$/gm, '')
+    .replace(/```[\s\S]*?```/g, '')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/[*_`~]/g, '')
+    .trim();
+
+  const sentences = clean
+    .split(/(?<=[.?!])\s+|\n\n+/)
+    .map((s) => s.trim())
+    .filter((s) => s.length >= 20 && s.length <= 300);
+
+  if (sentences.length <= maxSentences) {
+    return sentences.join(' ');
+  }
+
+  const salientTags = new Set(extractKeyphraseTags(clean, 8));
+
+  const scored = sentences.map((sent, index) => {
+    const tokens = tokenize(sent);
+    let tagMatches = 0;
+    for (const t of tokens) {
+      if (salientTags.has(t)) tagMatches++;
+    }
+    // Favor earlier sentences and sentences containing salient keywords
+    const posScore = 1.0 / (index + 1);
+    const salienceScore = tagMatches / (tokens.length + 1);
+    const score = posScore * 0.4 + salienceScore * 0.6;
+    return { sent, score, index };
+  });
+
+  scored.sort((a, b) => b.score - a.score);
+  const selected = scored.slice(0, maxSentences).sort((a, b) => a.index - b.index);
+
+  return selected.map((s) => s.sent).join(' ');
+}
+
+/**
+ * Analyzes a Markdown note to produce automated semantic tags and summary.
+ */
+export function analyzeNote(text: string): NoteAnalysis {
+  return {
+    tags: extractKeyphraseTags(text),
+    summary: summarizePassage(text),
+  };
+}

package/src/tui.ts

@@ -2,6 +2,7 @@ import readline from 'node:readline';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { loadIndex, searchIndex, SearchResultHit } from './search.js';
+import { extractAnswerFallback } from './rag.js';
 import { ModelDescriptor } from './core.js';
 
 export interface TuiOptions {
@@ -15,6 +16,7 @@ export interface TuiOptions {
   path?: string | string[];
   rerank?: boolean;
   rerankPool?: number;
+  rag?: boolean;
   embedFn?: any;
   rerankFn?: any;
   debounceMs?: number;
@@ -74,6 +76,8 @@ export async function runTui(opts: TuiOptions): Promise<SearchResultHit | null>
     }, opts.debounceMs ?? 300);
   };
 
+  let showRag = Boolean(opts.rag);
+
   const render = () => {
     const rows = process.stdout.rows || 24;
     const cols = process.stdout.columns || 80;
@@ -84,11 +88,12 @@ export async function runTui(opts: TuiOptions): Promise<SearchResultHit | null>
 
     // Header
     const searchStatus = searching ? ' [searching...]' : '';
-    const headerStr = ` mdss interactive search | Query: ${query}${searchStatus}`;
+    const modeLabel = showRag ? 'RAG QA & Synthesis' : 'search';
+    const headerStr = ` mdss interactive ${modeLabel} | Query: ${query}${searchStatus}`;
     buf += `\x1b[7m${headerStr.padEnd(cols).slice(0, cols)}\x1b[0m\n`;
 
     // Calculate layout heights
-    const listHeight = Math.max(4, Math.floor((rows - 4) * 0.4));
+    const listHeight = Math.max(3, Math.floor((rows - 4) * 0.35));
     const previewHeight = Math.max(4, rows - 4 - listHeight);
 
     // Render list
@@ -111,25 +116,38 @@ export async function runTui(opts: TuiOptions): Promise<SearchResultHit | null>
       }
     }
 
-    // Render Preview
-    buf += `\x1b[1m--- Passage Preview ---\x1b[0m\n`;
-    const selectedHit = results[selectedIndex];
-    if (selectedHit) {
-      const textLines = selectedHit.snippet.split('\n');
+    // Render Preview or RAG synthesis
+    if (showRag) {
+      buf += `\x1b[1m--- Grounded Answer Synthesis & Citations ---\x1b[0m\n`;
+      const answer = extractAnswerFallback(query, results);
+      const answerLines = answer.split('\n');
       for (let i = 0; i < previewHeight; i++) {
-        if (i < textLines.length) {
-          buf += `  ${textLines[i].slice(0, cols - 3)}\n`;
+        if (i < answerLines.length) {
+          buf += `  ${answerLines[i].slice(0, cols - 3)}\n`;
         } else {
           buf += '\n';
         }
       }
     } else {
-      buf += '  (no passage selected)\n';
-      for (let i = 1; i < previewHeight; i++) buf += '\n';
+      buf += `\x1b[1m--- Passage Preview ---\x1b[0m\n`;
+      const selectedHit = results[selectedIndex];
+      if (selectedHit) {
+        const textLines = selectedHit.snippet.split('\n');
+        for (let i = 0; i < previewHeight; i++) {
+          if (i < textLines.length) {
+            buf += `  ${textLines[i].slice(0, cols - 3)}\n`;
+          } else {
+            buf += '\n';
+          }
+        }
+      } else {
+        buf += '  (no passage selected)\n';
+        for (let i = 1; i < previewHeight; i++) buf += '\n';
+      }
     }
 
     // Footer
-    const footerStr = ' [Up/Down/j/k]: Navigate | [Enter]: Open in Editor | [Esc/q/Ctrl+C]: Quit';
+    const footerStr = ' [Tab]: Toggle RAG/Passage | [Up/Down]: Select | [Enter]: Open | [Esc]: Quit';
     buf += `\x1b[7m${footerStr.padEnd(cols).slice(0, cols)}\x1b[0m`;
 
     process.stdout.write(buf);
@@ -171,6 +189,12 @@ export async function runTui(opts: TuiOptions): Promise<SearchResultHit | null>
         return;
       }
 
+      if (key.name === 'tab') {
+        showRag = !showRag;
+        render();
+        return;
+      }
+
       if (key.name === 'up' || (key.name === 'k' && key.ctrl)) {
         if (selectedIndex > 0) {
           selectedIndex--;