md-semantic-search 0.4.0 → 0.5.0

package/README.md

@@ -255,6 +255,52 @@ error, and `serve --watch` politely defers its cycle until the other writer
 finishes. A crashed writer can't wedge the index — the lock self-heals by
 pid-liveness + staleness (a dead-pid or abandoned lock is reclaimed).
 
+### Export the index (`mdss export`)
+
+Export chunks and decoded embedding vectors to JSONL, CSV, or Parquet for downstream pipelines (LangChain, LlamaIndex, Qdrant, Pandas):
+
+```bash
+# Export all chunks with decoded float vectors as JSONL:
+mdss export --db ./notes --format jsonl > chunks.jsonl
+
+# Export metadata only without vectors (fast & compact):
+mdss export --db ./notes --format jsonl --no-vectors > chunks_meta.jsonl
+
+# Export as CSV (metadata only):
+mdss export --db ./notes --format csv > chunks.csv
+
+# Export directly to file:
+mdss export --db ./notes --format jsonl --output ./data/corpus.jsonl
+```
+
+#### JSONL output schema:
+```json
+{
+  "file": "runbooks/failover.md",
+  "title": "Database Failover",
+  "heading": "Step 2: Promote Replica",
+  "headingPath": ["Database Failover", "Step 2: Promote Replica"],
+  "text": "Run the promote script...",
+  "vec": [0.012, -0.045, 0.089],
+  "chunkHash": "a1b2c3...",
+  "startLine": 14,
+  "endLine": 28
+}
+```
+
+#### Downstream integration example (Python / LangChain / LlamaIndex):
+```python
+import json
+
+# Load into custom vector store / pipeline
+with open("chunks.jsonl") as f:
+    for line in f:
+        chunk = json.loads(line)
+        text = chunk["text"]
+        vector = chunk["vec"]
+        meta = {"file": chunk["file"], "heading": chunk["heading"]}
+```
+
 ### Diagnose problems (`mdss check` / `mdss doctor`)
 
 `mdss check` (alias: `mdss doctor`) is an **offline, read-only** diagnostic for
@@ -384,10 +430,15 @@ instead of being silently swallowed.
 
 | Flag | Meaning |
 |------|---------|
+| `--config <file>` | Path to config file (default: `.mdssrc.json`, `mdss.config.json`, `.mdssrc`). |
 | `--db <dir>` | Folder of `.md` files (or set `MDSS_DB`). Can be anywhere on disk. |
 | `--index-dir <dir>` | Where to store the index (default: `<db>/.mdss`). |
 | `--cache-dir <dir>` | Model cache dir. Default: `$XDG_CACHE_HOME/mdss` if set, else `~/.cache/mdss` on **all** platforms (so on Windows that's `C:\Users\<you>\.cache\mdss` — *not* `%LOCALAPPDATA%`; override with `MDSS_CACHE_DIR`). |
 | `--model <name\|id>` | Embedding model (default `e5-base`). See `mdss models`. |
+| `--workers <n>` | Number of parallel batch workers for embedding (default: 1). |
+| `--format <fmt>` | Export format: `jsonl` (default), `csv`, `parquet` (`export`). |
+| `--no-vectors` | Omit embeddings from export (`export`). |
+| `--output <file>` | Output file path (`export`, default: stdout). |
 | `--ignore <glob>` | Skip files/paths; repeatable. e.g. `--ignore "log.md" --ignore "**/archive/**"`. |
 | `--path <glob>` | Search only files matching glob; repeatable. e.g. `--path "docs/**"`. |
 | `--since <date>` | Search only files modified at/after date (`YYYY-MM-DD` or ISO 8601). |
@@ -395,6 +446,8 @@ instead of being silently swallowed.
 | `--json` | Machine-readable output: `index` → build result JSON, `stats` → index stats JSON, `search` → hit list JSON (each hit includes `matches` — the query terms found in the chunk). |
 | `--semantic` | `search` only: pure vector ranking, skip lexical/RRF fusion (zero lexical tokenization). |
 | `--rerank` | Re-rank the candidate pool with a cross-encoder (`Xenova/bge-reranker-base`, ~280 MB model, downloaded on first use). Slower, sharper results — see *Reranking* below. |
+| `--ann` | Approximate nearest neighbor search via IVF clustering (search; auto-enables for large corpora). |
+| `--nprobe <n>` | Number of nearest centroid clusters to probe during ANN search (default 8). |
 | `--port <n>` | HTTP port for `serve` (default 8747, or `MDSS_PORT`). |
 | `--host <ip>` | Bind address for `serve` (default `127.0.0.1` — loopback only; use `0.0.0.0` to expose on the LAN, or `MDSS_HOST`). |
 | `--watch` | `serve`: re-index incrementally when files change. |
@@ -422,6 +475,30 @@ mdss index
 mdss search "incident runbook for db failover"
 ```
 
+### Configuration file (`.mdssrc` / `mdss.config.json`)
+
+Instead of repeating CLI options on every command, create a `.mdssrc.json` or `mdss.config.json` file.
+`mdss` discovers config files by searching:
+1. An explicit path passed via `--config <path>` or the `MDSS_CONFIG` environment variable.
+2. Current working directory up through ancestor directories (`.mdssrc.json`, `mdss.config.json`, `.mdssrc`).
+3. User global config at `~/.mdssrc.json` or `~/.mdssrc`.
+
+CLI flags always override configuration values.
+
+Example `.mdssrc.json`:
+
+```json
+{
+  "db": "./notes",
+  "model": "e5-base",
+  "indexDir": "./notes/.mdss",
+  "ignore": ["archive/**", "drafts/**"],
+  "k": 6
+}
+```
+
+Run `mdss check` to validate your configuration file schema and detect unknown keys.
+
 ## Models
 
 ```bash
@@ -527,6 +604,10 @@ section instead of silently producing wrong vectors.
 No external services, no database — the whole index is one JSON file and search
 is an in-memory dot-product sweep.
 
+## Integrations
+
+- **Obsidian**: An official plugin is available in [`integrations/obsidian`](./integrations/obsidian) providing a live semantic search panel directly in your vault connected to `mdss serve`.
+
 ## License
 
 MIT © chelslava

package/bin/cli.mjs

@@ -14,12 +14,13 @@ import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import fs from 'node:fs';
 import os from 'node:os';
-import { buildIndex } from '../src/indexer.mjs';
-import { search } from '../src/search.mjs';
-import { createServe, DEFAULT_PORT, DEFAULT_HOST } from '../src/serve.mjs';
-import { MODELS, DEFAULT_MODEL, resolveModel } from '../src/models.mjs';
-import { decodeVec, walkMarkdown, SCHEMA_VERSION } from '../src/core.mjs';
-import { inspectIndexSchema, validateCurrentChunk, validateIndexEnvelope, validateNumericVector } from '../src/index-format.mjs';
+import crypto from 'node:crypto';
+import { buildIndex } from '../dist/indexer.js';
+import { search } from '../dist/search.js';
+import { createServe, DEFAULT_PORT, DEFAULT_HOST } from '../dist/serve.js';
+import { MODELS, DEFAULT_MODEL, resolveModel } from '../dist/models.js';
+import { decodeVec, walkMarkdown, SCHEMA_VERSION, assertSafePath } from '../dist/core.js';
+import { inspectIndexSchema, validateCurrentChunk, validateIndexEnvelope, validateNumericVector } from '../dist/index-format.js';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(HERE, '..');
@@ -49,8 +50,15 @@ function parseArgs(argv) {
     else if (a === '--watch') opts.watch = true;
     else if (a === '--rerank') opts.rerank = true;
     else if (a === '--explain') opts.explain = true;
+    else if (a === '--interactive' || a === '-i') opts.interactive = true;
+    else if (a === '--list-tools') opts.listTools = true;
     else if (a === '--version') opts.version = true;
     else if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '--workers') opts.workers = nextInt(argv, ++i, a);
+    else if (a === '--config') opts.config = nextValue(argv, ++i, a);
+    else if (a === '--format') opts.format = nextValue(argv, ++i, a);
+    else if (a === '--no-vectors' || a === '--no-vector') opts.noVectors = true;
+    else if (a === '--output' || a === '-o') opts.output = nextValue(argv, ++i, a);
     else if (a === '--db') opts.db = nextValue(argv, ++i, a);
     else if (a === '--index-dir') opts.indexDir = nextValue(argv, ++i, a);
     else if (a === '--cache-dir') opts.cacheDir = nextValue(argv, ++i, a);
@@ -61,6 +69,8 @@ function parseArgs(argv) {
     else if (a === '--target-tokens') opts.targetTokens = nextInt(argv, ++i, a);
     else if (a === '--port') opts.port = nextInt(argv, ++i, a);
     else if (a === '--host') opts.host = nextValue(argv, ++i, a);
+    else if (a === '--api-key') opts.apiKey = nextValue(argv, ++i, a);
+    else if (a === '--health-public') opts.healthPublic = true;
     else if (a === '--watch-delay') opts.watchDelay = nextInt(argv, ++i, a);
     else if (a === '--watch-interval') opts.watchInterval = nextInt(argv, ++i, a);
     else if (a === '--since') opts.since = nextValue(argv, ++i, a);
@@ -70,6 +80,8 @@ 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 === '--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);
     else if (a === '--status') opts.status = nextValue(argv, ++i, a);
@@ -95,6 +107,86 @@ function nextInt(argv, i, flag) {
   return k;
 }
 
+const KNOWN_CONFIG_KEYS = new Set([
+  'db', 'model', 'indexDir', 'index-dir', 'cacheDir', 'cache-dir',
+  'ignore', 'path', 'k', 'maxPerFile', 'max-per-file', 'maxPerDoc', 'max-per-doc',
+  'targetTokens', 'target-tokens', 'port', 'host', 'apiKey', 'api-key',
+  'healthPublic', 'health-public', 'watch', 'watchInterval', 'watch-interval',
+  'watchDelay', 'watch-delay', 'offline', 'rerank', 'semantic', 'tag', 'project', 'type', 'status', 'canonical',
+  'format', 'noVectors', 'no-vectors', 'output', 'workers', 'ann', 'nprobe'
+]);
+
+function findConfigFile(explicitPath) {
+  if (explicitPath) {
+    const abs = path.resolve(explicitPath);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) die(`config file not found: ${abs}`);
+    return abs;
+  }
+  if (process.env.MDSS_CONFIG) {
+    const abs = path.resolve(process.env.MDSS_CONFIG);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isFile()) die(`config file from MDSS_CONFIG not found: ${abs}`);
+    return abs;
+  }
+  const configNames = ['.mdssrc.json', 'mdss.config.json', '.mdssrc'];
+  let curr = process.cwd();
+  while (true) {
+    for (const name of configNames) {
+      const candidate = path.join(curr, name);
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    }
+    const parent = path.dirname(curr);
+    if (parent === curr) break;
+    curr = parent;
+  }
+  try {
+    const home = os.homedir();
+    if (home) {
+      for (const name of ['.mdssrc.json', '.mdssrc']) {
+        const candidate = path.join(home, name);
+        if (fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
+          return candidate;
+        }
+      }
+    }
+  } catch {}
+  return null;
+}
+
+function loadConfigFile(configPath) {
+  if (!configPath) return { config: {}, path: null, unknownKeys: [], 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` };
+    }
+    const unknownKeys = Object.keys(parsed).filter(k => !KNOWN_CONFIG_KEYS.has(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 };
+  } catch (e) {
+    return { config: {}, path: configPath, unknownKeys: [], error: `Failed to parse config at ${configPath}: ${e.message}` };
+  }
+}
+
+function applyConfigDefaults(opts, config) {
+  for (const [k, v] of Object.entries(config)) {
+    if (k === 'ignore' || k === 'path') {
+      if ((!opts[k] || opts[k].length === 0) && v !== undefined) {
+        opts[k] = Array.isArray(v) ? [...v] : [v];
+      }
+    } else if (opts[k] === undefined && v !== undefined) {
+      opts[k] = v;
+    }
+  }
+  return opts;
+}
+
 function resolveDb(opts) {
   const db = opts.db || process.env.MDSS_DB;
   if (!db) die('Missing --db <dir> (or set MDSS_DB). Path to your .md folder.');
@@ -102,13 +194,23 @@ function resolveDb(opts) {
   if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) {
     die(`--db is not a directory: ${abs}`);
   }
-  return abs;
+  let safeDb;
+  try {
+    safeDb = assertSafePath(abs);
+  } catch (e) {
+    die(e.message);
+  }
+  return safeDb;
 }
 
 function resolveIndexDir(opts, db) {
   // Default: <db>/.mdss. Override with --index-dir or MDSS_INDEX_DIR.
   const dir = opts.indexDir || process.env.MDSS_INDEX_DIR || path.join(db, '.mdss');
-  return path.resolve(dir);
+  try {
+    return assertSafePath(dir);
+  } catch (e) {
+    die(e.message);
+  }
 }
 
 const resolveCache = (opts) =>
@@ -127,15 +229,22 @@ Usage:
   mdss index  --db <dir> [options]            Build/refresh the index
   mdss stats  --db <dir> [--json]             Index stats without loading the model
   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 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
 
 Options:
+  --config <file>     Path to config file (default: .mdssrc.json / mdss.config.json).
   --db <dir>          Folder of .md files (or env MDSS_DB). Can be anywhere.
   --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\`.
+  --workers <n>       Number of parallel batch workers for indexing (default: 1).
+  --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).
   --ignore <glob>     Skip files/paths (repeatable). e.g. --ignore "log.md".
   --path <glob>       Search only files matching glob (repeatable). e.g. --path "docs/**".
   --since <date>      Search only files modified at/after date (YYYY-MM-DD or ISO).
@@ -143,6 +252,8 @@ 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).
+  --ann               Approximate nearest neighbor search via IVF (search).
+  --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
                       only; use 0.0.0.0 to expose on the LAN, env MDSS_HOST).
@@ -164,11 +275,41 @@ Examples:
   curl -X POST localhost:8747/search -d '{"query":"rotate api token","k":5}'
 `;
 
+function formatDuration(sec) {
+  const s = Math.max(0, Math.floor(sec));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const remainingS = s % 60;
+  return `${h}:${String(m).padStart(2, '0')}:${String(remainingS).padStart(2, '0')}`;
+}
+
 async function cmdIndex(opts) {
   const db = resolveDb(opts);
   const indexDir = resolveIndexDir(opts, db);
   const cacheDir = resolveCache(opts);
   const t0 = Date.now();
+  let lastProgressUpdate = 0;
+
+  const onProgress = (done, total, chunksPerSec) => {
+    if (!process.stderr.isTTY || opts.json || total <= 100) return;
+    const now = Date.now();
+    if (now - lastProgressUpdate < 500 && done < total) return;
+    lastProgressUpdate = now;
+    const percent = Math.floor((done / total) * 100);
+    const barWidth = 10;
+    const filled = Math.min(barWidth, Math.max(0, Math.round((done / total) * barWidth)));
+    const bar = '[' + '#'.repeat(filled) + '-'.repeat(barWidth - filled) + ']';
+    const remaining = total - done;
+    const etaSec = chunksPerSec > 0 ? remaining / chunksPerSec : 0;
+    const etaStr = formatDuration(etaSec);
+    const speedStr = `${chunksPerSec.toFixed(1)} chunks/s`;
+    const line = `${bar} ${percent}% │ ${done}/${total} chunks │ ${speedStr} │ ETA ${etaStr}`;
+    process.stderr.write(`\r${line}`);
+    if (done >= total) {
+      process.stderr.write('\n');
+    }
+  };
+
   let r;
   try {
     r = await buildIndex({
@@ -176,7 +317,13 @@ async function cmdIndex(opts) {
       modelName: opts.model || DEFAULT_MODEL,
       ignore: opts.ignore,
       offline: resolveOffline(opts),
-      log: s => process.stderr.write(s + '\n'),
+      workers: opts.workers,
+      ann: opts.ann,
+      log: s => {
+        if (process.stderr.isTTY && !opts.json && /^\s+\d+\/\d+$/.test(s)) return;
+        process.stderr.write(s + '\n');
+      },
+      onProgress,
     });
   } catch (e) {
     // A held index lock (issue #37) is an EXPECTED operational state (a second
@@ -234,7 +381,7 @@ function cmdStats(opts) {
   // File count = keys of .hashes.json (per-file md5 map written by buildIndex).
   // Fall back to unique chunk file paths when the hashes file is missing (a
   // legacy/corrupt index) rather than dying.
-  let files = 0;
+  let files;
   try {
     const hashes = JSON.parse(fs.readFileSync(hashesPath, 'utf8'));
     files = Object.keys(hashes).length;
@@ -288,6 +435,119 @@ function cmdStats(opts) {
   );
 }
 
+/**
+ * `mdss export` — export the index as JSONL / CSV / Parquet for downstream pipelines (issue #77).
+ */
+async function cmdExport(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\` first.`);
+  }
+
+  let index;
+  try {
+    index = JSON.parse(fs.readFileSync(vectorsPath, 'utf8'));
+  } catch (e) {
+    die(`${vectorsPath} is not valid JSON (${e.message}); run \`mdss index\` to rebuild.`);
+  }
+
+  const format = (opts.format || 'jsonl').toLowerCase();
+  const noVectors = !!opts.noVectors;
+  const outStream = opts.output ? fs.createWriteStream(path.resolve(opts.output), 'utf8') : process.stdout;
+
+  const chunks = Array.isArray(index.chunks) ? index.chunks : [];
+  const dim = index.dim;
+
+  if (format === 'jsonl') {
+    for (const c of chunks) {
+      let vec = undefined;
+      if (!noVectors && c.vec !== undefined) {
+        if (typeof c.vec === 'string') {
+          try {
+            vec = Array.from(decodeVec(c.vec, dim));
+          } catch {
+            vec = null;
+          }
+        } else if (Array.isArray(c.vec) || ArrayBuffer.isView(c.vec)) {
+          vec = Array.from(c.vec);
+        }
+      }
+      const record = {
+        file: c.file,
+        title: c.title,
+        heading: c.heading,
+        headingPath: c.headingPath,
+        text: c.text,
+        ...(noVectors ? {} : { vec }),
+        ...(c.chunkHash ? { chunkHash: c.chunkHash } : {}),
+        ...(c.startLine !== undefined ? { startLine: c.startLine } : {}),
+        ...(c.endLine !== undefined ? { endLine: c.endLine } : {}),
+        ...(c.meta ? { meta: c.meta } : {}),
+      };
+      outStream.write(JSON.stringify(record) + '\n');
+    }
+    if (opts.output) {
+      await new Promise((resolve) => outStream.end(resolve));
+    }
+  } else if (format === 'csv') {
+    const escapeCsv = (val) => {
+      const str = String(val ?? '');
+      if (str.includes(',') || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+        return '"' + str.replace(/"/g, '""') + '"';
+      }
+      return str;
+    };
+    outStream.write('file,title,heading,headingPath,text\n');
+    for (const c of chunks) {
+      const pathStr = Array.isArray(c.headingPath) ? c.headingPath.join(' > ') : (c.heading || '');
+      const row = [
+        escapeCsv(c.file),
+        escapeCsv(c.title),
+        escapeCsv(c.heading),
+        escapeCsv(pathStr),
+        escapeCsv(c.text),
+      ].join(',');
+      outStream.write(row + '\n');
+    }
+    if (opts.output) {
+      await new Promise((resolve) => outStream.end(resolve));
+    }
+  } else if (format === 'parquet') {
+    let parquet;
+    try {
+      // @ts-ignore
+      parquet = await import('parquetjs-lite');
+    } catch {
+      die('Parquet export requires optional dependency "parquetjs-lite". Install with: npm install parquetjs-lite');
+    }
+    if (!opts.output) {
+      die('Parquet export requires an output file via --output <file.parquet>');
+    }
+    const schemaFields = {
+      file: { type: 'UTF8' },
+      title: { type: 'UTF8' },
+      heading: { type: 'UTF8' },
+      text: { type: 'UTF8' },
+    };
+    const schema = new parquet.ParquetSchema(schemaFields);
+    const outFile = path.resolve(opts.output);
+    const writer = await parquet.ParquetWriter.openFile(schema, outFile);
+    for (const c of chunks) {
+      await writer.appendRow({
+        file: c.file || '',
+        title: c.title || '',
+        heading: c.heading || '',
+        text: c.text || '',
+      });
+    }
+    await writer.close();
+  } else {
+    die(`unknown export format: "${format}". Supported formats: jsonl, csv, parquet.`);
+  }
+}
+
 /**
  * Offline diagnostics for the index/db/model-cache trio (issue #43) — the
  * `mdss check` / `mdss doctor` backend. Pure read-only: parses vectors.json +
@@ -295,7 +555,7 @@ function cmdStats(opts) {
  * validator the loader uses), walks the db for staleness, and checks the
  * transformers.js cache layout for the index's model. NEVER loads the
  * embedding model and NEVER touches the network.
- * @param {{db:string, indexDir:string, cacheDir:string, requireOffline?:boolean}} paths
+ * @param {{db:string, indexDir:string, cacheDir:string, requireOffline?:boolean, config?:any}} paths
  * @returns {CheckReport}
  */
 
@@ -312,7 +572,7 @@ function cmdStats(opts) {
  * @property {{exists:boolean, stale:boolean, error:(string|null)}} db
  * @property {{id:(string|null), cached:boolean, cachePath:(string|null), error:(string|null)}} model
  */
-export function checkHealth({ db, indexDir, cacheDir, requireOffline = false }) {
+function checkHealth({ db, indexDir, cacheDir, requireOffline = false, config = null }) {
   const report = {
     healthy: true,
     index: { exists: false, parses: false, schemaVersion: null, format: null, recognized: true, error: null },
@@ -320,7 +580,21 @@ export function checkHealth({ db, indexDir, cacheDir, requireOffline = false })
     chunks: { total: 0, valid: 0, invalid: [] },
     db: { exists: true, stale: false, error: null },
     model: { id: null, cached: false, cachePath: null, error: null },
+    config: null,
   };
+
+  // --- config file: exists, valid JSON, schema / unknown keys (issue #68) ---
+  if (config && config.path) {
+    report.config = {
+      path: config.path,
+      valid: !config.error && (!config.unknownKeys || config.unknownKeys.length === 0),
+      unknownKeys: config.unknownKeys || [],
+      error: config.error || (config.unknownKeys && config.unknownKeys.length > 0 ? `unknown config keys: ${config.unknownKeys.join(', ')}` : null),
+    };
+    if (!report.config.valid) {
+      report.healthy = false;
+    }
+  }
   const vectorsPath = path.join(indexDir, 'vectors.json');
   const hashesPath = path.join(indexDir, '.hashes.json');
 
@@ -332,8 +606,22 @@ export function checkHealth({ db, indexDir, cacheDir, requireOffline = false })
   }
   report.index.exists = true;
   let index;
+  const raw = fs.readFileSync(vectorsPath, 'utf8');
+  const shaPath = path.join(indexDir, 'vectors.json.sha256');
+  if (fs.existsSync(shaPath)) {
+    try {
+      const shaContent = fs.readFileSync(shaPath, 'utf8').trim();
+      const expectedHash = shaContent.split(/\s+/)[0];
+      const actualHash = crypto.createHash('sha256').update(raw).digest('hex');
+      if (expectedHash && actualHash !== expectedHash) {
+        report.index.error = `vectors.json integrity check failed (SHA-256 mismatch) — run \`mdss index\` to rebuild`;
+        report.healthy = false;
+        return report;
+      }
+    } catch { /* ignore unreadable sha file */ }
+  }
   try {
-    index = JSON.parse(fs.readFileSync(vectorsPath, 'utf8'));
+    index = JSON.parse(raw);
     report.index.parses = true;
   } catch (e) {
     report.index.error = `${vectorsPath} is not valid JSON (${e.message}); run \`mdss index\` to rebuild`;
@@ -469,7 +757,11 @@ function cmdCheck(opts) {
   const db = resolveDb(opts);
   const indexDir = resolveIndexDir(opts, db);
   const cacheDir = resolveCache(opts);
-  const report = checkHealth({ db, indexDir, cacheDir, requireOffline: resolveOffline(opts) });
+  const report = checkHealth({
+    db, indexDir, cacheDir,
+    requireOffline: resolveOffline(opts),
+    config: opts._config,
+  });
 
   if (opts.json) {
     process.stdout.write(JSON.stringify(report, null, 2) + '\n');
@@ -543,6 +835,14 @@ function cmdCheck(opts) {
     out += warn('model: index has no model field (legacy index)');
   }
 
+  if (report.config) {
+    if (report.config.valid) {
+      out += ok(`config: ${report.config.path}`);
+    } else {
+      out += fail(`config: ${report.config.path} (${report.config.error})`);
+    }
+  }
+
   out += report.healthy
     ? 'check: healthy (exit 0)\n'
     : 'check: 1+ problem(s) found (exit 1)\n';
@@ -550,7 +850,24 @@ function cmdCheck(opts) {
   process.exitCode = report.healthy ? 0 : 1;
 }
 
+async function cmdTui(opts) {
+  const db = resolveDb(opts);
+  const indexDir = resolveIndexDir(opts, db);
+  const cacheDir = resolveCache(opts);
+  const query = opts._.join(' ').trim();
+  const { runTui } = await import('../dist/tui.js');
+  await runTui({
+    db, indexDir, cacheDir, query,
+    k: opts.k || 20,
+    semanticOnly: !!opts.semantic,
+    offline: resolveOffline(opts),
+    path: opts.path.length > 0 ? opts.path : undefined,
+    rerank: !!opts.rerank,
+  });
+}
+
 async function cmdSearch(opts) {
+  if (opts.interactive) return cmdTui(opts);
   const db = resolveDb(opts);
   const indexDir = resolveIndexDir(opts, db);
   const cacheDir = resolveCache(opts);
@@ -572,6 +889,8 @@ async function cmdSearch(opts) {
     canonicalOnly: opts.canonical,
     explain: !!opts.explain,
     maxPerFile: opts.maxPerFile || opts.maxPerDoc,
+    ann: opts.ann,
+    nprobe: opts.nprobe,
   });
 
   if (opts.json) { process.stdout.write(JSON.stringify(results, null, 2) + '\n'); return; }
@@ -648,6 +967,8 @@ async function cmdServe(opts) {
     watch: !!opts.watch,
     watchInterval: opts.watchInterval,
     watchDelay: opts.watchDelay,
+    apiKey: opts.apiKey || process.env.MDSS_API_KEY,
+    healthPublic: !!opts.healthPublic || process.env.MDSS_HEALTH_PUBLIC === 'true',
     log,
   });
 
@@ -671,9 +992,37 @@ async function cmdServe(opts) {
   process.on('SIGTERM', () => stop('SIGTERM'));
 }
 
+async function cmdMcp(opts) {
+  if (opts.listTools) {
+    const { MCP_TOOLS } = await import('../dist/mcp.js');
+    process.stdout.write(JSON.stringify(MCP_TOOLS, null, 2) + '\n');
+    return;
+  }
+  const db = resolveDb(opts);
+  const indexDir = resolveIndexDir(opts, db);
+  const cacheDir = resolveCache(opts);
+  const log = s => process.stderr.write(s + '\n');
+  const { startMcpServer } = await import('../dist/mcp.js');
+  await startMcpServer({
+    db, indexDir, cacheDir,
+    modelName: opts.model || DEFAULT_MODEL,
+    ignore: opts.ignore,
+    offline: resolveOffline(opts),
+    log,
+  });
+}
+
 async function main() {
   const argv = process.argv.slice(2);
   const opts = parseArgs(argv);
+  const configPath = findConfigFile(opts.config);
+  const loadedConfig = loadConfigFile(configPath);
+  if (loadedConfig.error && opts.config) {
+    die(loadedConfig.error);
+  }
+  opts._config = loadedConfig;
+  applyConfigDefaults(opts, loadedConfig.config);
+
   const cmd = opts._.shift();
 
   if (opts.version) { process.stdout.write(`${VERSION}\n`); return; }
@@ -683,8 +1032,11 @@ async function main() {
     case 'stats': return cmdStats(opts);
     case 'check':
     case 'doctor': return cmdCheck(opts);
+    case 'export': return cmdExport(opts);
     case 'search': return cmdSearch(opts);
+    case 'tui': return cmdTui(opts);
     case 'serve': return cmdServe(opts);
+    case 'mcp': return cmdMcp(opts);
     case 'models': return cmdModels();
     default: die(`unknown command: ${cmd}. Try \`mdss --help\`.`);
   }
@@ -702,5 +1054,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
 export {
   parseArgs, nextInt, nextValue,
   resolveDb, resolveIndexDir, resolveCache, resolveOffline,
+  findConfigFile, loadConfigFile, applyConfigDefaults, KNOWN_CONFIG_KEYS,
+  checkHealth, cmdExport,
   die, main, HELP, VERSION,
 };