md-semantic-search 1.0.3 → 2.0.0

package/bin/cli.mjs

@@ -16,11 +16,12 @@ import fs from 'node:fs';
 import os from 'node:os';
 import crypto from 'node:crypto';
 import { buildIndex } from '../dist/indexer.js';
-import { search } from '../dist/search.js';
+import { loadIndex, search } from '../dist/search.js';
 import { searchFederated } from '../dist/federation.js';
 import { createServe, DEFAULT_PORT, DEFAULT_HOST, isLoopbackHost, validateBindSecurity, loadApiKeyFile } from '../dist/serve.js';
 import { MODELS, DEFAULT_MODEL, resolveModel } from '../dist/models.js';
 import { decodeVec, walkMarkdown, SCHEMA_VERSION, assertSafePath, setDownloadProgressListener } from '../dist/core.js';
+import { findRelatedNotes } from '../dist/wikilinks.js';
 import { DownloadProgressAggregator } from '../dist/download-progress.js';
 import { generateCompletion, COMPLETION_SHELLS } from '../dist/completions.js';
 import { openHit, resolveOpenCommand } from '../dist/open.js';
@@ -93,6 +94,7 @@ function parseArgs(argv) {
     else if (a === '--watch-interval') opts.watchInterval = nextInt(argv, ++i, a);
     else if (a === '--rate-limit') opts.rateLimit = nextNonNegInt(argv, ++i, a);
     else if (a === '--max-concurrency') opts.maxConcurrency = nextNonNegInt(argv, ++i, a);
+    else if (a === '--dimensions' || a === '--dim') opts.dimensions = nextInt(argv, ++i, a);
     else if (a === '--since') opts.since = nextValue(argv, ++i, a);
     else if (a === '--path') opts.path.push(nextValue(argv, ++i, a));
     else if (a === '--ignore') opts.ignore.push(nextValue(argv, ++i, a));
@@ -100,7 +102,16 @@ function parseArgs(argv) {
       const v = nextValue(argv, ++i, a);
       opts.tag = opts.tag ? (Array.isArray(opts.tag) ? [...opts.tag, v] : [opts.tag, v]) : v;
     }
-    else if (a === '--ann') opts.ann = true;
+    else if (a === '--ann') {
+      // issue #201: optional engine choice — bare --ann keeps the default
+      const next = argv[i + 1];
+      if (next === 'ivf' || next === 'hnsw') {
+        opts.ann = next;
+        i++;
+      } else {
+        opts.ann = true;
+      }
+    }
     else if (a === '--nprobe') opts.nprobe = nextInt(argv, ++i, a);
     else if (a === '--project') opts.project = nextValue(argv, ++i, a);
     else if (a === '--type') opts.type = nextValue(argv, ++i, a);
@@ -108,13 +119,31 @@ function parseArgs(argv) {
     else if (a === '--canonical') opts.canonical = true;
     else if (a === '--graph-boost') opts.graphBoost = nextFloat(argv, ++i, a);
     else if (a === '--filter') opts.filter = nextValue(argv, ++i, a);
+    else if (a === '--direction') opts.direction = nextValue(argv, ++i, a);
+    else if (a === '--no-semantic') opts.noSemantic = true;
     else if (a === '--quantize') opts.quantize = nextValue(argv, ++i, a);
+    else if (a === '--max-chunk-tokens') {
+      // issue #202: 0 explicitly restores the legacy char budget
+      opts.maxChunkTokens = nextNonNegInt(argv, ++i, a);
+    }
+    else if (a === '--multi-query') {
+      // issue #203: N total query variants (>=2 activates; LLM required)
+      opts.multiQuery = nextInt(argv, ++i, a);
+      if (opts.multiQuery > 5) die('--multi-query must be <= 5');
+    }
+    else if (a === '--rerank-model') opts.rerankModel = nextValue(argv, ++i, a);
     else if (a === '--rag') opts.rag = true;
     else if (a === '--auto-tag') opts.autoTag = true;
     else if (a === '--auto-summarize') opts.autoSummarize = true;
     else if (a === '--llm-endpoint') opts.llmEndpoint = nextValue(argv, ++i, a);
     else if (a === '--llm-model') opts.llmModel = nextValue(argv, ++i, a);
+    else if (a === '--llm-provider') {
+      opts.llmProvider = nextValue(argv, ++i, a);
+      if (!['openai', 'ollama'].includes(opts.llmProvider)) die(`unknown --llm-provider "${opts.llmProvider}" - use openai|ollama`);
+    }
     else if (a === '--system-prompt') opts.systemPrompt = nextValue(argv, ++i, a);
+    else if (a === '--session') opts.session = nextValue(argv, ++i, a);
+    else if (a === '--resume') opts.resume = true;
     else if (a === '--open') {
       // `--open` opens the top hit; `--open N` opens the Nth hit (issue #110).
       const next = argv[i + 1];
@@ -202,9 +231,13 @@ const KNOWN_CONFIG_KEYS = new Set([
   'healthPublic', 'health-public', 'watch', 'watchInterval', 'watch-interval',
   'watchDelay', 'watch-delay', 'offline', 'rerank', 'semantic', 'tag', 'project', 'type', 'status', 'canonical',
   'watchDebug', 'watch-debug',
-  'format', 'noVectors', 'no-vectors', 'output', 'workers', 'ann', 'nprobe', 'graphBoost', 'graph-boost', 'filter', 'quantize',
+  'format', 'noVectors', 'no-vectors', 'output', 'workers', 'dimensions', 'dim', 'ann', 'nprobe', 'graphBoost', 'graph-boost', 'filter', 'quantize',
+  'maxChunkTokens', 'max-chunk-tokens',
+  'multiQuery', 'multi-query', 'rerankModel', 'rerank-model',
   'vault', 'vaults', 'rag', 'autoTag', 'auto-tag', 'autoSummarize', 'auto-summarize',
   'llmEndpoint', 'llm-endpoint', 'llmModel', 'llm-model', 'systemPrompt', 'system-prompt',
+  'llmProvider', 'llm-provider',
+  'session', 'resume',
   'completions', 'open', 'dry-run', 'fix', 'yes', 'no-ui', 'noUi',
   'noQueryCache', 'no-query-cache',
   'mcp',
@@ -213,6 +246,27 @@ const KNOWN_CONFIG_KEYS = new Set([
   'expand', 'expandPassages', 'expand-passages', 'llm-endpoint', 'llmEndpoint'
 ]);
 
+const CONFIG_NETWORK_KEYS = new Set([
+  'port', 'host', 'apiKey', 'api-key', 'apiKeyFile', 'api-key-file',
+  'allowUnsecured', 'allow-unsecured', 'allowedHost', 'allowed-host',
+  'allowedHosts', 'allowed-hosts', 'corsOrigin', 'cors-origin',
+  'rateLimit', 'rate-limit', 'maxConcurrency', 'max-concurrency',
+  'healthPublic', 'health-public', 'mcp', 'llmEndpoint', 'llm-endpoint',
+  'llmModel', 'llm-model', 'llmProvider', 'llm-provider', 'embedder', 'embedder-model', 'embedder-base-url',
+  'embedder-key-file', 'embedderModel', 'embedderBaseUrl', 'embedderKeyFile'
+]);
+
+const CONFIG_EXEC_KEYS = new Set([
+  // No execution surfaces permitted in local repo config
+]);
+
+function getConfigKeyTrustTier(key) {
+  if (CONFIG_EXEC_KEYS.has(key)) return 'exec';
+  if (CONFIG_NETWORK_KEYS.has(key)) return 'network';
+  if (KNOWN_CONFIG_KEYS.has(key)) return 'local-safe';
+  return 'unknown';
+}
+
 function findConfigFile(explicitPath) {
   if (explicitPath) {
     const abs = path.resolve(explicitPath);
@@ -252,22 +306,26 @@ function findConfigFile(explicitPath) {
 }
 
 function loadConfigFile(configPath) {
-  if (!configPath) return { config: {}, path: null, unknownKeys: [], error: null };
+  if (!configPath) return { config: {}, path: null, unknownKeys: [], trustTiers: {}, error: null };
   try {
     const raw = fs.readFileSync(configPath, 'utf8');
     const parsed = JSON.parse(raw);
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
-      return { config: {}, path: configPath, unknownKeys: [], error: `Config at ${configPath} must be a JSON object` };
+      return { config: {}, path: configPath, unknownKeys: [], trustTiers: {}, error: `Config at ${configPath} must be a JSON object` };
     }
     const unknownKeys = Object.keys(parsed).filter(k => !KNOWN_CONFIG_KEYS.has(k));
+    const trustTiers = {};
+    for (const k of Object.keys(parsed)) {
+      trustTiers[k] = getConfigKeyTrustTier(k);
+    }
     const normalized = {};
     for (const [k, v] of Object.entries(parsed)) {
       const camel = k.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
       normalized[camel] = v;
     }
-    return { config: normalized, path: configPath, unknownKeys, error: null };
+    return { config: normalized, path: configPath, unknownKeys, trustTiers, error: null };
   } catch (e) {
-    return { config: {}, path: configPath, unknownKeys: [], error: `Failed to parse config at ${configPath}: ${e.message}` };
+    return { config: {}, path: configPath, unknownKeys: [], trustTiers: {}, error: `Failed to parse config at ${configPath}: ${e.message}` };
   }
 }
 
@@ -328,6 +386,9 @@ Usage:
   mdss check  --db <dir> [--json]             Diagnose index/db/model cache (alias: doctor)
   mdss export --db <dir> [options]            Export index to JSONL / CSV / Parquet
   mdss search --db <dir> [options] "query"    Search by meaning
+  mdss related --db <dir> [options] <note>    Find related notes via graph links and similarity
+  mdss ask    --db <dir> [options] "question" Grounded QA synthesis with citations
+  mdss chat   --db <dir> [options]            Multi-turn persistent chat with citation manifest
   mdss serve  --db <dir> [--port <n>] [--host <ip>] [--watch]  Daemon: warm model + index
   mdss mcp    --db <dir> [--list-tools]       Start MCP server over stdio for LLM agents / IDEs
   mdss models                                  List available models
@@ -339,7 +400,13 @@ Options:
   --index-dir <dir>   Where to store the index (default: <db>/.mdss).
   --cache-dir <dir>   Model cache dir (default: ~/.cache/mdss, or MDSS_CACHE_DIR).
   --model <name|id>   Embedding model (default: ${DEFAULT_MODEL}). See \`mdss models\`.
+  --dimensions <n>    Truncate vector dimensions for Matryoshka/MRL models (alias: --dim).
   --workers <n>       Number of parallel batch workers for indexing (default: 1).
+  --max-chunk-tokens <n>  index/serve: chunk budget in TOKENS (issue #202) —
+                      default min(model maxTokens, 512), so Cyrillic notes are
+                      chunked by the same real budget as English ones instead
+                      of an English-calibrated char count; 0 restores the
+                      legacy char budget (1400).
   --format <fmt>      Export format: jsonl (default), csv, parquet (export).
   --no-vectors        Omit vector embeddings from export (export).
   --output <file>     Output file path (export, default: stdout).
@@ -350,9 +417,21 @@ Options:
   --json              Machine-readable output (index, stats, search).
   --semantic          Pure vector ranking, skip lexical/RRF fusion (search).
   --rerank            Re-rank candidates with a cross-encoder (search; ~280MB model).
+  --rerank-model <m>  Reranker registry alias (issue #203): "bge-reranker-base"
+                      (default) or "gte-reranker-modernbert" (144MB, 8k ctx,
+                      Apache-2.0); also accepts id[@revision].
+  --multi-query <n>   Multi-query expansion (issue #203): N total query
+                      variants (original + N-1 LLM paraphrases, one extra
+                      embedding each) fused by union-RRF — recall lift on
+                      heavy paraphrases. Needs --llm-endpoint; silently falls
+                      back to the single query without one. 0/1 = off.
   --graph-boost <n>   Boost weight for graph PageRank / Obsidian wikilinks (search, default: 0).
   --filter <expr>     Rich boolean filter across frontmatter tags and properties (search).
-  --ann               Approximate nearest neighbor search via IVF (search).
+  --ann [ivf|hnsw]    Approximate nearest neighbor search (search/index).
+                      Engines (issue #201): "ivf" (k-means clusters, the
+                      historical default) or "hnsw" (graph index — no
+                      training phase, incremental inserts, hnsw.json
+                      sidecar). Bare --ann prefers an existing sidecar.
   --nprobe <n>        Number of centroids to probe for ANN (search, default: 8).
   --port <n>          HTTP port for serve (default: ${DEFAULT_PORT}).
   --host <ip>         Bind address for serve (default: ${DEFAULT_HOST} — loopback
@@ -408,6 +487,13 @@ Options:
                       ONE embed total; issue #125) or "hyde" (LLM-generated
                       passage via --llm-endpoint; degrades silently without it).
   --expand-passages <n>  prf feedback pool size (default 3, max 20).
+  --llm-endpoint <u>  OpenAI-compatible chat endpoint for ask/chat/serve /ask
+                      and --expand hyde: POST {base}/chat/completions
+                      (llama.cpp, LM Studio, vLLM, Ollama at .../v1).
+  --llm-provider <p>  Chat wire format for --llm-endpoint: "openai" (default,
+                      SSE streaming) or "ollama" (native /api/generate,
+                      NDJSON streaming) (issue #199).
+  --llm-model <m>     Provider-side chat model for --llm-endpoint.
   --open [N]          search: open the top (or Nth) hit in your editor at its
                       startLine — MDSS_EDITOR/VISUAL/EDITOR, then VS Code
                       --goto, then the GUI opener (issue #110). With --json on
@@ -426,6 +512,9 @@ Examples:
   mdss search --db ./docs "incident runbook" --path "docs/**" --since 2026-01-01
   mdss serve  --db ./docs --port 8747 --watch
   curl -X POST localhost:8747/search -d '{"query":"rotate api token","k":5}'
+  mdss ask    --db ./docs "how do tokens expire?" \\
+              --llm-endpoint http://127.0.0.1:8080/v1 --llm-model qwen2.5
+  mdss chat   --db ./docs --llm-endpoint http://127.0.0.1:11434/v1 --resume
 `;
 
 function formatDuration(sec) {
@@ -456,6 +545,9 @@ async function resolveEmbedderOverrides(opts) {
     baseUrl: opts.embedderBaseUrl,
     keyFile: opts.embedderKeyFile,
   });
+  const egressUrl = opts.embedderBaseUrl ||
+    (opts.embedder === 'ollama' ? process.env.OLLAMA_HOST || 'http://127.0.0.1:11434' : 'https://api.openai.com/v1');
+  warnDataEgress(`--embedder ${opts.embedder}`, egressUrl);
   const descriptor = await emb.descriptor();
   logErr(`embedder: ${emb.id}/${emb.model} (dim ${descriptor.dim} via ${opts.embedderBaseUrl || 'default endpoint'})`);
   return { modelName: descriptor, embedFn: emb.embedFn };
@@ -465,6 +557,36 @@ function logErr(s) {
   process.stderr.write(s + '\n');
 }
 
+// ---------------------------------------------------------------------------
+// Data egress notice (issue #183): two opt-in paths send PRIVATE note content
+// to non-loopback destinations — external embedders and the RAG LLM bridge.
+// The default local pipeline never transmits anything; the notice fires once
+// per process before the first send and can be silenced via env.
+// ---------------------------------------------------------------------------
+
+export function isLoopbackEndpoint(url) {
+  try {
+    const u = new URL(url);
+    const h = u.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    return h === 'localhost' || h === '127.0.0.1' || h === '::1';
+  } catch {
+    return false;
+  }
+}
+
+let egressWarned = false;
+
+export function warnDataEgress(kind, destination, write = (m) => process.stderr.write(m + '\n')) {
+  if (egressWarned || process.env.MDSS_NO_EGRESS_WARNING === '1') return;
+  if (isLoopbackEndpoint(destination)) return; // local Ollama/llama.cpp — nothing leaves the machine
+  egressWarned = true;
+  write(
+    `⚠ data egress: ${kind} sends NOTE CONTENT to ${destination} (an external service).\n` +
+    `  Everything stays local with --offline, a loopback endpoint, or the default local embedder.\n` +
+    `  Set MDSS_NO_EGRESS_WARNING=1 to silence this notice. See SECURITY.md "Data egress".`
+  );
+}
+
 async function cmdIndex(opts) {
   const db = resolveDb(opts);
   const indexDir = resolveIndexDir(opts, db);
@@ -499,12 +621,15 @@ async function cmdIndex(opts) {
     r = await buildIndex({
       db, indexDir, cacheDir,
       modelName: embedderOverrides.modelName || opts.model || DEFAULT_MODEL,
+      dimensions: opts.dimensions,
       ...(embedderOverrides.embedFn ? { embedFn: embedderOverrides.embedFn } : {}),
       ignore: opts.ignore,
       offline: resolveOffline(opts),
       workers: opts.workers,
       ann: opts.ann,
       quantize: opts.quantize,
+      // issue #202: token-budget chunking — default min(adapter.maxTokens, 512)
+      ...(opts.maxChunkTokens !== undefined ? { maxChunkTokens: opts.maxChunkTokens } : {}),
       log: s => {
         if (process.stderr.isTTY && !opts.json && /^\s+\d+\/\d+$/.test(s)) return;
         process.stderr.write(s + '\n');
@@ -775,6 +900,7 @@ function checkHealth({ db, indexDir, cacheDir, requireOffline = false, config =
       path: config.path,
       valid: !config.error && (!config.unknownKeys || config.unknownKeys.length === 0),
       unknownKeys: config.unknownKeys || [],
+      trustTiers: config.trustTiers || {},
       error: config.error || (config.unknownKeys && config.unknownKeys.length > 0 ? `unknown config keys: ${config.unknownKeys.join(', ')}` : null),
     };
     if (!report.config.valid) {
@@ -1088,11 +1214,42 @@ async function cmdTui(opts) {
     semanticOnly: !!opts.semantic,
     offline: resolveOffline(opts),
     path: opts.path.length > 0 ? opts.path : undefined,
+    since: opts.since || undefined,
+    filter: opts.filter || undefined,
+    tag: opts.tag.length > 0 ? opts.tag : undefined,
+    project: opts.project || undefined,
+    type: opts.type || undefined,
+    status: opts.status || undefined,
+    graphBoost: typeof opts.graphBoost === 'number' ? opts.graphBoost : undefined,
     rerank: !!opts.rerank,
+    ...(opts.multiQuery ? { multiQuery: opts.multiQuery, llmEndpoint: opts.llmEndpoint, ...(opts.llmModel ? { llmModel: opts.llmModel } : {}) } : {}),
+    ...(opts.rerankModel ? { rerankModel: opts.rerankModel } : {}),
     rag: !!opts.rag,
+    // issue #199: the RAG panel streams a real LLM answer when an endpoint
+    // is configured; without one it stays on the extractive fallback.
+    llmEndpoint: opts.llmEndpoint,
+    llmModel: opts.llmModel,
+    llmProvider: opts.llmProvider,
+    systemPrompt: opts.systemPrompt,
   });
 }
 
+/**
+ * issue #199: finish the answer render after synthesis. When LLM deltas
+ * already went to the terminal, only trailing whitespace is added; when the
+ * stream died mid-way and synthesis fell back to extractive, the fallback
+ * answer is printed under an explicit notice so the two texts can't blur.
+ */
+function finishAnswerRender(streamedChars, result, end = '\n\n') {
+  if (streamedChars === 0) {
+    process.stdout.write(`\n${result.answer}${end}`);
+  } else if (result.mode === 'endpoint') {
+    process.stdout.write(end);
+  } else {
+    process.stdout.write(`\n\n[llm stream interrupted — extractive fallback:]\n\n${result.answer}${end}`);
+  }
+}
+
 async function cmdAsk(opts) {
   const query = opts._.join(' ').trim();
   if (!query) die('missing question to ask. Usage: mdss ask [--db <dir>] "question"');
@@ -1101,15 +1258,25 @@ async function cmdAsk(opts) {
   const indexDir = resolveIndexDir(opts, db);
   const cacheDir = resolveCache(opts);
   const k = opts.k || 5;
+  const offline = resolveOffline(opts);
+  const embedderOverrides = await resolveEmbedderOverrides(opts);
 
+  if (opts.llmEndpoint) warnDataEgress('--llm-endpoint', opts.llmEndpoint);
   const { askQuestion } = await import('../dist/rag.js');
+  let streamedChars = 0;
   const result = await askQuestion({
     query,
     indexDir,
     cacheDir,
     k,
+    offline,
+    ...(embedderOverrides.embedFn ? { embedFn: embedderOverrides.embedFn } : {}),
     llmEndpoint: opts.llmEndpoint,
     llmModel: opts.llmModel,
+    llmProvider: opts.llmProvider,
+    // issue #199: incremental render — first token lands immediately. JSON
+    // mode stays a single machine-readable write.
+    ...(opts.json ? {} : { onDelta: (d) => { streamedChars += d.length; process.stdout.write(d); } }),
     systemPrompt: opts.systemPrompt,
   });
 
@@ -1118,7 +1285,7 @@ async function cmdAsk(opts) {
     return;
   }
 
-  process.stdout.write(`\n${result.answer}\n\n`);
+  finishAnswerRender(streamedChars, result);
   if (result.citations && result.citations.length > 0) {
     process.stdout.write('Sources:\n');
     for (const c of result.citations) {
@@ -1129,18 +1296,183 @@ async function cmdAsk(opts) {
   }
 }
 
+async function cmdChat(opts) {
+  const db = resolveDb(opts);
+  const indexDir = resolveIndexDir(opts, db);
+  const cacheDir = resolveCache(opts);
+  const k = opts.k || 5;
+  const offline = resolveOffline(opts);
+  const embedderOverrides = await resolveEmbedderOverrides(opts);
+
+  const vectorsPath = path.join(indexDir, 'vectors.json');
+  if (!fs.existsSync(vectorsPath)) {
+    die(`No index at ${vectorsPath}. Run \`mdss index --db ${db}\` first.`);
+  }
+
+  if (opts.llmEndpoint) warnDataEgress('--llm-endpoint', opts.llmEndpoint);
+  const { chatTurn, loadChatSession, listChatSessions } = await import('../dist/rag.js');
+  const loaded = loadIndex(indexDir);
+
+  let sessionId = opts.session;
+  if (!sessionId && opts.resume) {
+    const existing = listChatSessions(indexDir);
+    if (existing.length > 0) {
+      sessionId = existing[0].id;
+    }
+  }
+  if (!sessionId) {
+    sessionId = crypto.randomUUID().slice(0, 8);
+  }
+
+  const session = loadChatSession(indexDir, sessionId, (msg) => {
+    if (!opts.json) process.stderr.write(`${msg}\n`);
+  });
+
+  const query = opts._.join(' ').trim();
+  // If one-shot query provided as argument:
+  if (query) {
+    let streamedChars = 0;
+    const res = await chatTurn({
+      session,
+      query,
+      loaded,
+      indexDir,
+      cacheDir,
+      k,
+      offline,
+      ...(embedderOverrides.embedFn ? { embedFn: embedderOverrides.embedFn } : {}),
+      llmEndpoint: opts.llmEndpoint,
+      llmModel: opts.llmModel,
+      llmProvider: opts.llmProvider,
+      ...(opts.json ? {} : { onDelta: (d) => { streamedChars += d.length; process.stdout.write(d); } }),
+      systemPrompt: opts.systemPrompt,
+    });
+
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(res, null, 2) + '\n');
+      return;
+    }
+
+    finishAnswerRender(streamedChars, res);
+    if (res.citations && res.citations.length > 0) {
+      process.stdout.write('Sources:\n');
+      for (const c of res.citations) {
+        const heading = c.heading ? ` › ${c.heading}` : '';
+        process.stdout.write(`  - ${c.file}${heading} [score: ${c.score.toFixed(3)}]\n`);
+      }
+      process.stdout.write('\n');
+    }
+    return;
+  }
+
+  // Interactive REPL mode:
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const banner = `\x1b[1mmdss chat\x1b[0m (session: \x1b[36m${session.id}\x1b[0m, turns: ${session.turns.length}, chunks: ${loaded.index.chunks.length})\nCommands: /session, /sources, /help, /exit\n`;
+  process.stdout.write(banner);
+
+  const promptUser = () => {
+    rl.question('\n\x1b[1mmdss chat>\x1b[0m ', async (input) => {
+      const line = (input || '').trim();
+      if (!line) {
+        promptUser();
+        return;
+      }
+
+      if (line === '/exit' || line === '/quit' || line === ':q') {
+        rl.close();
+        return;
+      }
+
+      if (line === '/help') {
+        process.stdout.write('Available commands:\n  /session   Show current session information\n  /sources   Show retrieved sources manifest from last turn\n  /help      Show this help message\n  /exit      Quit chat\n');
+        promptUser();
+        return;
+      }
+
+      if (line === '/session') {
+        process.stdout.write(`Session ID: ${session.id}\nCreated: ${session.createdAt}\nTurns: ${session.turns.length}\n`);
+        promptUser();
+        return;
+      }
+
+      if (line === '/sources') {
+        const lastTurn = session.turns[session.turns.length - 1];
+        if (!lastTurn || !lastTurn.manifest || lastTurn.manifest.length === 0) {
+          process.stdout.write('No sources available yet.\n');
+        } else {
+          process.stdout.write('Sources from last turn:\n');
+          for (const m of lastTurn.manifest) {
+            const loc = (m.startLine && m.endLine) ? `:L${m.startLine}-L${m.endLine}` : '';
+            const heading = m.heading ? ` › ${m.heading}` : '';
+            process.stdout.write(`  - ${m.file}${heading}${loc} [score: ${m.score.toFixed(3)}]\n`);
+          }
+        }
+        promptUser();
+        return;
+      }
+
+      try {
+        let streamedChars = 0;
+        const res = await chatTurn({
+          session,
+          query: line,
+          loaded,
+          indexDir,
+          cacheDir,
+          k,
+          offline,
+          ...(embedderOverrides.embedFn ? { embedFn: embedderOverrides.embedFn } : {}),
+          llmEndpoint: opts.llmEndpoint,
+          llmModel: opts.llmModel,
+          llmProvider: opts.llmProvider,
+          // issue #199: REPL deltas stream as they arrive; session/history
+          // persistence still happens on the complete answer only.
+          onDelta: (d) => { streamedChars += d.length; process.stdout.write(d); },
+          systemPrompt: opts.systemPrompt,
+        });
+
+        finishAnswerRender(streamedChars, res, '\n');
+        if (res.citations && res.citations.length > 0) {
+          process.stdout.write('\nSources:\n');
+          for (const c of res.citations) {
+            const heading = c.heading ? ` › ${c.heading}` : '';
+            process.stdout.write(`  - ${c.file}${heading} [score: ${c.score.toFixed(3)}]\n`);
+          }
+        }
+      } catch (e) {
+        process.stdout.write(`\nError: ${e.message}\n`);
+      }
+
+      promptUser();
+    });
+  };
+
+  promptUser();
+}
+
 async function cmdSearch(opts) {
   if (opts.interactive) return cmdTui(opts);
   const cacheDir = resolveCache(opts);
   const query = opts._.join(' ').trim();
   if (!query) die('Missing query text. e.g. mdss search --db ./docs "your question"');
 
+  // issue #203: multi-query paraphrases and HyDE both send note-derived text
+  // through the LLM endpoint — same one-time disclosure as ask/chat
+  if ((opts.multiQuery || opts.expand === 'hyde') && opts.llmEndpoint) {
+    warnDataEgress('--llm-endpoint', opts.llmEndpoint);
+  }
+
   const embedderOverrides = await resolveEmbedderOverrides(opts);
   let results;
   const isFederated = Array.isArray(opts.vaults) && opts.vaults.length > 0;
 
   if (isFederated) {
-    results = await searchFederated({
+    const fed = await searchFederated({
       ...(embedderOverrides.embedFn ? { embedFn: embedderOverrides.embedFn } : {}),
       vaults: opts.vaults,
       cacheDir,
@@ -1155,6 +1487,9 @@ async function cmdSearch(opts) {
       path: opts.path.length > 0 ? opts.path : undefined,
       since: opts.since,
       rerank: !!opts.rerank,
+      // issue #203: multi-query expansion + reranker registry alias
+      ...(opts.multiQuery ? { multiQuery: opts.multiQuery, llmEndpoint: opts.llmEndpoint, ...(opts.llmModel ? { llmModel: opts.llmModel } : {}) } : {}),
+      ...(opts.rerankModel ? { rerankModel: opts.rerankModel } : {}),
       tag: opts.tag,
       project: opts.project,
       type: opts.type,
@@ -1167,6 +1502,9 @@ async function cmdSearch(opts) {
       graphBoost: opts.graphBoost,
       filter: opts.filter,
     });
+    // issue #189: a broken vault must not look like "no results"
+    for (const ve of fed.vaultErrors) process.stderr.write(`warning: ${ve}\n`);
+    results = fed.hits;
   } else {
     const db = resolveDb(opts);
     const indexDir = resolveIndexDir(opts, db);
@@ -1185,6 +1523,9 @@ async function cmdSearch(opts) {
       path: opts.path.length > 0 ? opts.path : undefined,
       since: opts.since,
       rerank: !!opts.rerank,
+      // issue #203: multi-query expansion + reranker registry alias
+      ...(opts.multiQuery ? { multiQuery: opts.multiQuery, llmEndpoint: opts.llmEndpoint, ...(opts.llmModel ? { llmModel: opts.llmModel } : {}) } : {}),
+      ...(opts.rerankModel ? { rerankModel: opts.rerankModel } : {}),
       tag: opts.tag,
       project: opts.project,
       type: opts.type,
@@ -1196,6 +1537,7 @@ async function cmdSearch(opts) {
       nprobe: opts.nprobe,
       graphBoost: opts.graphBoost,
       filter: opts.filter,
+      dimensions: opts.dimensions,
     });
   }
 
@@ -1289,9 +1631,10 @@ function cmdModels() {
     const pooling = m.pooling ?? 'mean';
     const normalized = m.normalize !== false ? 'L2' : 'raw';
     const rev = m.revision ? ` · rev ${m.revision.slice(0, 8)}` : '';
+    const mrl = m.dimensions ? ` · MRL: ${m.dimensions.join(', ')}` : '';
     process.stdout.write(
       `  ${alias}${star}\n` +
-      `    ${m.id} · dim ${m.dim}${rev}\n` +
+      `    ${m.id} · dim ${m.dim}${mrl}${rev}\n` +
       `    ${pooling} · ${normalized} · maxTokens ${m.maxTokens ?? '—'} ` +
       (m.family ? `· family ${m.family}\n` : '\n') +
       `    ${m.note}\n\n`,
@@ -1327,12 +1670,23 @@ async function cmdServe(opts) {
   // Refuse to serve the whole knowledge base to the network unauthenticated (issue #121).
   validateBindSecurity({ host, hasApiKey: !!apiKey, allowUnsecured: !!opts.allowUnsecured });
 
+  // POST /ask egress (issue #199): the daemon forwards queries to the chat
+  // endpoint — same disclosure gate as the CLI ask/chat paths.
+  if (opts.llmEndpoint) warnDataEgress('--llm-endpoint', opts.llmEndpoint);
+
   const { server, state, close } = await createServe({
     db, indexDir, cacheDir,
     modelName: embedderOverrides.modelName || opts.model || DEFAULT_MODEL,
     ignore: opts.ignore,
     offline: resolveOffline(opts),
     ...(embedderOverrides.embedFn ? { embedFn: embedderOverrides.embedFn } : {}),
+    // issue #202: token-budget chunking for serve's initial + watch rebuilds.
+    ...(opts.maxChunkTokens !== undefined ? { maxChunkTokens: opts.maxChunkTokens } : {}),
+    // issue #199: chat endpoint for POST /ask SSE synthesis.
+    ...(opts.llmEndpoint ? { llmEndpoint: opts.llmEndpoint } : {}),
+    ...(opts.llmModel ? { llmModel: opts.llmModel } : {}),
+    ...(opts.llmProvider ? { llmProvider: opts.llmProvider } : {}),
+    ...(opts.systemPrompt ? { systemPrompt: opts.systemPrompt } : {}),
     watch: !!opts.watch,
     watchInterval: opts.watchInterval,
     watchDelay: opts.watchDelay,
@@ -1357,6 +1711,25 @@ async function cmdServe(opts) {
     log,
   });
 
+  // issue #186: the most common serve failure (EADDRINUSE) used to surface as
+  // a raw stack trace — name the cause and the fix instead.
+  server.on('error', (err) => {
+    if (err?.code === 'EADDRINUSE') {
+      process.stderr.write(
+        `mdss serve: port ${port} is already in use — another daemon (or program) is listening on it.\n` +
+        `  Fix: pick another port, e.g. mdss serve --port ${port + 1}\n`
+      );
+    } else if (err?.code === 'EACCES') {
+      process.stderr.write(
+        `mdss serve: no permission to bind ${host}:${port}.\n` +
+        `  Fix: use an unprivileged port (1024+), e.g. mdss serve --port 8747\n`
+      );
+    } else {
+      process.stderr.write(`mdss serve: ${err?.message || err}\n`);
+    }
+    process.exit(1);
+  });
+
   server.listen(port, host, () => {
     const idx = state.loaded.index;
     log(`mdss serve listening on http://${host}:${port}` +
@@ -1364,6 +1737,7 @@ async function cmdServe(opts) {
     log(`  index: ${idx.chunks.length} chunks · model ${state.loaded.model.id}` +
       (state.watching ? ' · watching for changes' : ''));
     log(`  POST /search  {"query": "...", "k": 6}`);
+    if (state.llmEndpoint) log(`  POST /ask     {"query": "...", "k": 5} — SSE answer streams via ${state.llmEndpoint}`);
     log(`  GET  /health`);
     if (!isLoopbackHost(host) && !state.apiKey) {
       log('');
@@ -1378,11 +1752,17 @@ async function cmdServe(opts) {
 
   const stop = async (sig) => {
     log(`\n${sig} — shutting down.`);
-    await close();
+    try {
+      await close();
+    } catch {
+      // issue #186: a second signal (or a listen error) can make close()
+      // reject with ERR_SERVER_NOT_RUNNING — always exit, never hang
+    }
     process.exit(0);
   };
   process.on('SIGINT', () => stop('SIGINT'));
   process.on('SIGTERM', () => stop('SIGTERM'));
+  if (process.platform === 'win32') process.on('SIGBREAK', () => stop('SIGBREAK'));
 }
 
 async function cmdMcp(opts) {
@@ -1414,7 +1794,7 @@ async function cmdMcp(opts) {
 // on STDERR so stdout stays machine-readable; warm cache emits nothing at all.
 // ---------------------------------------------------------------------------
 
-const DOWNLOAD_COMMANDS = new Set(['index', 'search', 'ask', 'serve']);
+const DOWNLOAD_COMMANDS = new Set(['index', 'search', 'ask', 'chat', 'serve']);
 
 function formatMb(bytes) {
   if (!Number.isFinite(bytes) || bytes <= 0) return '0 MB';
@@ -1469,6 +1849,59 @@ async function cmdCompletions(opts) {
   process.stdout.write(generateCompletion(shell));
 }
 
+async function cmdRelated(opts) {
+  const db = resolveDb(opts);
+  const indexDir = resolveIndexDir(opts, db);
+  const vectorsPath = path.join(indexDir, 'vectors.json');
+  if (!fs.existsSync(vectorsPath)) {
+    die(`No index at ${vectorsPath}. Run \`mdss index --db ${db}\` first.`);
+  }
+  const target = opts._.shift();
+  if (!target) {
+    die('Missing note path/title/alias to find relations for. e.g. `mdss related --db . "Architecture"`');
+  }
+
+  const loaded = loadIndex(indexDir);
+  const k = Number.isInteger(opts.k) && opts.k > 0 ? opts.k : 10;
+  const direction = opts.direction || 'both';
+  const semantic = !opts.noSemantic;
+
+  let r;
+  try {
+    r = findRelatedNotes({
+      loaded,
+      target,
+      k,
+      direction,
+      semantic,
+    });
+  } catch (e) {
+    die(e.message);
+  }
+
+  if (opts.json) {
+    process.stdout.write(JSON.stringify(r, null, 2) + '\n');
+    return;
+  }
+
+  if (r.results.length === 0) {
+    process.stdout.write(`No related notes found for "${target}" (${r.resolvedFile}).\n`);
+    if (opts.noSemantic) {
+      process.stdout.write('Hint: Try running without `--no-semantic` to discover conceptually related notes without explicit links.\n');
+    }
+    return;
+  }
+
+  process.stdout.write(`Related notes for "${target}" (${r.resolvedFile}):\n\n`);
+  r.results.forEach((hit, idx) => {
+    const scoreStr = hit.score.toFixed(2);
+    process.stdout.write(`  ${idx + 1}. \x1b[1m${hit.file}\x1b[0m — score: ${scoreStr} [${hit.reason}]\n`);
+    if (hit.title && hit.title !== hit.file) {
+      process.stdout.write(`     title: "${hit.title}"\n`);
+    }
+  });
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   const opts = parseArgs(argv);
@@ -1496,7 +1929,9 @@ async function main() {
       case 'doctor': return await cmdCheck(opts);
       case 'export': return await cmdExport(opts);
       case 'search': return await cmdSearch(opts);
+      case 'related': return await cmdRelated(opts);
       case 'ask': return await cmdAsk(opts);
+      case 'chat': return await cmdChat(opts);
       case 'tui': return await cmdTui(opts);
       case 'serve': return await cmdServe(opts);
       case 'mcp': return await cmdMcp(opts);
@@ -1542,6 +1977,7 @@ export {
   parseArgs, nextInt, nextFloat, nextValue,
   resolveDb, resolveIndexDir, resolveCache, resolveOffline,
   findConfigFile, loadConfigFile, applyConfigDefaults, KNOWN_CONFIG_KEYS,
+  CONFIG_NETWORK_KEYS, CONFIG_EXEC_KEYS, getConfigKeyTrustTier,
   checkHealth, cmdExport,
   die, main, HELP, VERSION,
 };