@tobilu/qmd 1.1.1 → 1.1.5

package/dist/mcp.js

@@ -12,6 +12,7 @@ import { fileURLToPath } from "url";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { createStore, extractSnippet, addLineNumbers, structuredSearch, DEFAULT_MULTI_GET_MAX_BYTES, } from "./store.js";
 import { getCollection, getGlobalContext, getDefaultCollectionNames } from "./collections.js";
@@ -83,10 +84,13 @@ function buildInstructions(store) {
     lines.push("  - type:'vec' — semantic vector search (meaning-based)");
     lines.push("  - type:'hyde' — hypothetical document (write what the answer looks like)");
     lines.push("");
+    lines.push("  Always provide `intent` on every search call to disambiguate and improve snippets.");
+    lines.push("");
     lines.push("Examples:");
     lines.push("  Quick keyword lookup: [{type:'lex', query:'error handling'}]");
     lines.push("  Semantic search: [{type:'vec', query:'how to handle errors gracefully'}]");
     lines.push("  Best results: [{type:'lex', query:'error'}, {type:'vec', query:'error handling best practices'}]");
+    lines.push("  With intent: searches=[{type:'lex', query:'performance'}], intent='web page load times'");
     // --- Retrieval workflow ---
     lines.push("");
     lines.push("Retrieval:");
@@ -233,9 +237,11 @@ Intent-aware lex (C++ performance, not sports):
             searches: z.array(subSearchSchema).min(1).max(10).describe("Typed sub-queries to execute (lex/vec/hyde). First gets 2x weight."),
             limit: z.number().optional().default(10).describe("Max results (default: 10)"),
             minScore: z.number().optional().default(0).describe("Min relevance 0-1 (default: 0)"),
+            candidateLimit: z.number().optional().describe("Maximum candidates to rerank (default: 40, lower = faster but may miss results)"),
             collections: z.array(z.string()).optional().describe("Filter to collections (OR match)"),
+            intent: z.string().optional().describe("Background context to disambiguate the query. Example: query='performance', intent='web page load times and Core Web Vitals'. Does not search on its own."),
         },
-    }, async ({ searches, limit, minScore, collections }) => {
+    }, async ({ searches, limit, minScore, candidateLimit, collections, intent }) => {
         // Map to internal format
         const subSearches = searches.map(s => ({
             type: s.type,
@@ -247,13 +253,15 @@ Intent-aware lex (C++ performance, not sports):
             collections: effectiveCollections.length > 0 ? effectiveCollections : undefined,
             limit,
             minScore,
+            candidateLimit,
+            intent,
         });
         // Use first lex or vec query for snippet extraction
         const primaryQuery = searches.find(s => s.type === 'lex')?.query
             || searches.find(s => s.type === 'vec')?.query
             || searches[0]?.query || "";
         const filtered = results.map(r => {
-            const { line, snippet } = extractSnippet(r.bestChunk, primaryQuery, 300);
+            const { line, snippet } = extractSnippet(r.bestChunk, primaryQuery, 300, undefined, undefined, intent);
             return {
                 docid: `#${r.docid}`,
                 file: r.displayPath,
@@ -425,12 +433,27 @@ export async function startMcpServer() {
  */
 export async function startMcpHttpServer(port, options) {
     const store = createStore();
-    const mcpServer = createMcpServer(store);
-    const transport = new WebStandardStreamableHTTPServerTransport({
-        sessionIdGenerator: () => randomUUID(),
-        enableJsonResponse: true,
-    });
-    await mcpServer.connect(transport);
+    // Session map: each client gets its own McpServer + Transport pair (MCP spec requirement).
+    // The store is shared — it's stateless SQLite, safe for concurrent access.
+    const sessions = new Map();
+    async function createSession() {
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            enableJsonResponse: true,
+            onsessioninitialized: (sessionId) => {
+                sessions.set(sessionId, transport);
+                log(`${ts()} New session ${sessionId} (${sessions.size} active)`);
+            },
+        });
+        const server = createMcpServer(store);
+        await server.connect(transport);
+        transport.onclose = () => {
+            if (transport.sessionId) {
+                sessions.delete(transport.sessionId);
+            }
+        };
+        return transport;
+    }
     const startTime = Date.now();
     const quiet = options?.quiet ?? false;
     /** Format timestamp for request logging */
@@ -500,6 +523,7 @@ export async function startMcpHttpServer(port, options) {
                     collections: effectiveCollections.length > 0 ? effectiveCollections : undefined,
                     limit: params.limit ?? 10,
                     minScore: params.minScore ?? 0,
+                    candidateLimit: params.candidateLimit,
                 });
                 // Use first lex or vec query for snippet extraction
                 const primaryQuery = params.searches.find((s) => s.type === 'lex')?.query
@@ -531,6 +555,34 @@ export async function startMcpHttpServer(port, options) {
                     if (typeof v === "string")
                         headers[k] = v;
                 }
+                // Route to existing session or create new one on initialize
+                const sessionId = headers["mcp-session-id"];
+                let transport;
+                if (sessionId) {
+                    const existing = sessions.get(sessionId);
+                    if (!existing) {
+                        nodeRes.writeHead(404, { "Content-Type": "application/json" });
+                        nodeRes.end(JSON.stringify({
+                            jsonrpc: "2.0",
+                            error: { code: -32001, message: "Session not found" },
+                            id: body?.id ?? null,
+                        }));
+                        return;
+                    }
+                    transport = existing;
+                }
+                else if (isInitializeRequest(body)) {
+                    transport = await createSession();
+                }
+                else {
+                    nodeRes.writeHead(400, { "Content-Type": "application/json" });
+                    nodeRes.end(JSON.stringify({
+                        jsonrpc: "2.0",
+                        error: { code: -32000, message: "Bad Request: Missing session ID" },
+                        id: body?.id ?? null,
+                    }));
+                    return;
+                }
                 const request = new Request(url, { method: "POST", headers, body: rawBody });
                 const response = await transport.handleRequest(request, { parsedBody: body });
                 nodeRes.writeHead(response.status, Object.fromEntries(response.headers));
@@ -539,12 +591,33 @@ export async function startMcpHttpServer(port, options) {
                 return;
             }
             if (pathname === "/mcp") {
-                const url = `http://localhost:${port}${pathname}`;
                 const headers = {};
                 for (const [k, v] of Object.entries(nodeReq.headers)) {
                     if (typeof v === "string")
                         headers[k] = v;
                 }
+                // GET/DELETE must have a valid session
+                const sessionId = headers["mcp-session-id"];
+                if (!sessionId) {
+                    nodeRes.writeHead(400, { "Content-Type": "application/json" });
+                    nodeRes.end(JSON.stringify({
+                        jsonrpc: "2.0",
+                        error: { code: -32000, message: "Bad Request: Missing session ID" },
+                        id: null,
+                    }));
+                    return;
+                }
+                const transport = sessions.get(sessionId);
+                if (!transport) {
+                    nodeRes.writeHead(404, { "Content-Type": "application/json" });
+                    nodeRes.end(JSON.stringify({
+                        jsonrpc: "2.0",
+                        error: { code: -32001, message: "Session not found" },
+                        id: null,
+                    }));
+                    return;
+                }
+                const url = `http://localhost:${port}${pathname}`;
                 const rawBody = nodeReq.method !== "GET" && nodeReq.method !== "HEAD" ? await collectBody(nodeReq) : undefined;
                 const request = new Request(url, { method: nodeReq.method || "GET", headers, ...(rawBody ? { body: rawBody } : {}) });
                 const response = await transport.handleRequest(request);
@@ -571,7 +644,10 @@ export async function startMcpHttpServer(port, options) {
         if (stopping)
             return;
         stopping = true;
-        await transport.close();
+        for (const transport of sessions.values()) {
+            await transport.close();
+        }
+        sessions.clear();
         httpServer.close();
         store.close();
         await disposeDefaultLlamaCpp();

package/dist/qmd.js

@@ -74,19 +74,24 @@ const cursor = {
 // Ensure cursor is restored on exit
 process.on('SIGINT', () => { cursor.show(); process.exit(130); });
 process.on('SIGTERM', () => { cursor.show(); process.exit(143); });
-// Terminal progress bar using OSC 9;4 escape sequence
+// Terminal progress bar using OSC 9;4 escape sequence (TTY only)
+const isTTY = process.stderr.isTTY;
 const progress = {
     set(percent) {
-        process.stderr.write(`\x1b]9;4;1;${Math.round(percent)}\x07`);
+        if (isTTY)
+            process.stderr.write(`\x1b]9;4;1;${Math.round(percent)}\x07`);
     },
     clear() {
-        process.stderr.write(`\x1b]9;4;0\x07`);
+        if (isTTY)
+            process.stderr.write(`\x1b]9;4;0\x07`);
     },
     indeterminate() {
-        process.stderr.write(`\x1b]9;4;3\x07`);
+        if (isTTY)
+            process.stderr.write(`\x1b]9;4;3\x07`);
     },
     error() {
-        process.stderr.write(`\x1b]9;4;2\x07`);
+        if (isTTY)
+            process.stderr.write(`\x1b]9;4;2\x07`);
     },
 };
 // Format seconds into human-readable ETA
@@ -398,7 +403,7 @@ async function updateCollections() {
                 process.exit(1);
             }
         }
-        await indexFiles(col.pwd, col.glob_pattern, col.name, true);
+        await indexFiles(col.pwd, col.glob_pattern, col.name, true, yamlCol?.ignore);
         console.log("");
     }
     // Check if any documents need embedding (show once at end)
@@ -1103,6 +1108,9 @@ function collectionList() {
         const excludeTag = excluded ? ` ${c.yellow}[excluded]${c.reset}` : '';
         console.log(`${c.cyan}${coll.name}${c.reset} ${c.dim}(qmd://${coll.name}/)${c.reset}${excludeTag}`);
         console.log(`  ${c.dim}Pattern:${c.reset}  ${coll.glob_pattern}`);
+        if (yamlColl?.ignore?.length) {
+            console.log(`  ${c.dim}Ignore:${c.reset}   ${yamlColl.ignore.join(', ')}`);
+        }
         console.log(`  ${c.dim}Files:${c.reset}    ${coll.active_count}`);
         console.log(`  ${c.dim}Updated:${c.reset}  ${timeAgo}`);
         console.log();
@@ -1138,7 +1146,8 @@ async function collectionAdd(pwd, globPattern, name) {
     addCollection(collName, pwd, globPattern);
     // Create the collection and index files
     console.log(`Creating collection '${collName}'...`);
-    await indexFiles(pwd, globPattern, collName);
+    const newColl = getCollectionFromYaml(collName);
+    await indexFiles(pwd, globPattern, collName, false, newColl?.ignore);
     console.log(`${c.green}✓${c.reset} Collection '${collName}' created successfully`);
 }
 function collectionRemove(name) {
@@ -1179,7 +1188,7 @@ function collectionRename(oldName, newName) {
     console.log(`${c.green}✓${c.reset} Renamed collection '${oldName}' to '${newName}'`);
     console.log(`  Virtual paths updated: ${c.cyan}qmd://${oldName}/${c.reset} → ${c.cyan}qmd://${newName}/${c.reset}`);
 }
-async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppressEmbedNotice = false) {
+async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppressEmbedNotice = false, ignorePatterns) {
     const db = getDb();
     const resolvedPwd = pwd || getPwd();
     const now = new Date().toISOString();
@@ -1192,12 +1201,16 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
     }
     console.log(`Collection: ${resolvedPwd} (${globPattern})`);
     progress.indeterminate();
+    const allIgnore = [
+        ...excludeDirs.map(d => `**/${d}/**`),
+        ...(ignorePatterns || []),
+    ];
     const allFiles = await fastGlob(globPattern, {
         cwd: resolvedPwd,
         onlyFiles: true,
         followSymbolicLinks: false,
         dot: false,
-        ignore: excludeDirs.map(d => `**/${d}/**`),
+        ignore: allIgnore,
     });
     // Filter hidden files/folders (dot: false handles top-level but not nested)
     const files = allFiles.filter(file => {
@@ -1205,11 +1218,11 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
         return !parts.some(part => part.startsWith("."));
     });
     const total = files.length;
-    if (total === 0) {
+    const hasNoFiles = total === 0;
+    if (hasNoFiles) {
         progress.clear();
         console.log("No files found matching pattern.");
-        closeDb();
-        return;
+        // Continue so the deactivation pass can mark previously indexed docs as inactive.
     }
     let indexed = 0, updated = 0, unchanged = 0, processed = 0;
     const seenPaths = new Set();
@@ -1218,7 +1231,16 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
         const filepath = getRealPath(resolve(resolvedPwd, relativeFile));
         const path = handelize(relativeFile); // Normalize path for token-friendliness
         seenPaths.add(path);
-        const content = readFileSync(filepath, "utf-8");
+        let content;
+        try {
+            content = readFileSync(filepath, "utf-8");
+        }
+        catch (err) {
+            // Skip files that can't be read (e.g. iCloud evicted files returning EAGAIN)
+            processed++;
+            progress.set((processed / total) * 100);
+            continue;
+        }
         // Skip empty files - nothing useful to index
         if (!content.trim()) {
             processed++;
@@ -1260,7 +1282,8 @@ async function indexFiles(pwd, globPattern = DEFAULT_GLOB, collectionName, suppr
         const rate = processed / elapsed;
         const remaining = (total - processed) / rate;
         const eta = processed > 2 ? ` ETA: ${formatETA(remaining)}` : "";
-        process.stderr.write(`\rIndexing: ${processed}/${total}${eta}        `);
+        if (isTTY)
+            process.stderr.write(`\rIndexing: ${processed}/${total}${eta}        `);
     }
     // Deactivate documents in this collection that no longer exist
     const allActive = getActiveDocumentPaths(db, collectionName);
@@ -1423,7 +1446,8 @@ async function vectorIndex(model = DEFAULT_EMBED_MODEL, force = false) {
             const throughput = `${formatBytes(bytesPerSec)}/s`;
             const eta = elapsed > 2 ? formatETA(etaSec) : "...";
             const errStr = errors > 0 ? ` ${c.yellow}${errors} err${c.reset}` : "";
-            process.stderr.write(`\r${c.cyan}${bar}${c.reset} ${c.bold}${percentStr}%${c.reset} ${c.dim}${chunksEmbedded}/${totalChunks}${c.reset}${errStr} ${c.dim}${throughput} ETA ${eta}${c.reset}   `);
+            if (isTTY)
+                process.stderr.write(`\r${c.cyan}${bar}${c.reset} ${c.bold}${percentStr}%${c.reset} ${c.dim}${chunksEmbedded}/${totalChunks}${c.reset}${errStr} ${c.dim}${throughput} ETA ${eta}${c.reset}   `);
         }
         progress.clear();
         cursor.show();
@@ -1496,6 +1520,9 @@ function formatScore(score) {
         return `${c.yellow}${pct}%${c.reset}`;
     return `${c.dim}${pct}%${c.reset}`;
 }
+function formatExplainNumber(value) {
+    return value.toFixed(4);
+}
 // Shorten directory path for display - relative to $HOME (used for context paths, not documents)
 function shortPath(dirpath) {
     const home = homedir();
@@ -1504,10 +1531,33 @@ function shortPath(dirpath) {
     }
     return dirpath;
 }
+// Emit format-safe empty output for search commands.
+function printEmptySearchResults(format, reason = "no_results") {
+    if (format === "json") {
+        console.log("[]");
+        return;
+    }
+    if (format === "csv") {
+        console.log("docid,score,file,title,context,line,snippet");
+        return;
+    }
+    if (format === "xml") {
+        console.log("<results></results>");
+        return;
+    }
+    if (format === "md" || format === "files") {
+        return;
+    }
+    if (reason === "min_score") {
+        console.log("No results found above minimum score threshold.");
+        return;
+    }
+    console.log("No results found.");
+}
 function outputResults(results, query, opts) {
     const filtered = results.filter(r => r.score >= opts.minScore).slice(0, opts.limit);
     if (filtered.length === 0) {
-        console.log("No results found above minimum score threshold.");
+        printEmptySearchResults(opts.format, "min_score");
         return;
     }
     // Helper to create qmd:// URI from displayPath
@@ -1517,7 +1567,7 @@ function outputResults(results, query, opts) {
         const output = filtered.map(row => {
             const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : undefined);
             let body = opts.full ? row.body : undefined;
-            let snippet = !opts.full ? extractSnippet(row.body, query, 300, row.chunkPos).snippet : undefined;
+            let snippet = !opts.full ? extractSnippet(row.body, query, 300, row.chunkPos, undefined, opts.intent).snippet : undefined;
             if (opts.lineNumbers) {
                 if (body)
                     body = addLineNumbers(body);
@@ -1532,6 +1582,7 @@ function outputResults(results, query, opts) {
                 ...(row.context && { context: row.context }),
                 ...(body && { body }),
                 ...(snippet && { snippet }),
+                ...(opts.explain && row.explain && { explain: row.explain }),
             };
         });
         console.log(JSON.stringify(output, null, 2));
@@ -1549,7 +1600,7 @@ function outputResults(results, query, opts) {
             const row = filtered[i];
             if (!row)
                 continue;
-            const { line, snippet } = extractSnippet(row.body, query, 500, row.chunkPos);
+            const { line, snippet } = extractSnippet(row.body, query, 500, row.chunkPos, undefined, opts.intent);
             const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : undefined);
             // Line 1: filepath with docid
             const path = toQmdPath(row.displayPath);
@@ -1570,6 +1621,27 @@ function outputResults(results, query, opts) {
             // Line 4: Score
             const score = formatScore(row.score);
             console.log(`Score: ${c.bold}${score}${c.reset}`);
+            if (opts.explain && row.explain) {
+                const explain = row.explain;
+                const ftsScores = explain.ftsScores.length > 0
+                    ? explain.ftsScores.map(formatExplainNumber).join(", ")
+                    : "none";
+                const vecScores = explain.vectorScores.length > 0
+                    ? explain.vectorScores.map(formatExplainNumber).join(", ")
+                    : "none";
+                const contribSummary = explain.rrf.contributions
+                    .slice()
+                    .sort((a, b) => b.rrfContribution - a.rrfContribution)
+                    .slice(0, 3)
+                    .map(c => `${c.source}/${c.queryType}#${c.rank}:${formatExplainNumber(c.rrfContribution)}`)
+                    .join(" | ");
+                console.log(`${c.dim}Explain: fts=[${ftsScores}] vec=[${vecScores}]${c.reset}`);
+                console.log(`${c.dim}  RRF: total=${formatExplainNumber(explain.rrf.totalScore)} base=${formatExplainNumber(explain.rrf.baseScore)} bonus=${formatExplainNumber(explain.rrf.topRankBonus)} rank=${explain.rrf.rank}${c.reset}`);
+                console.log(`${c.dim}  Blend: ${Math.round(explain.rrf.weight * 100)}%*${formatExplainNumber(explain.rrf.positionScore)} + ${Math.round((1 - explain.rrf.weight) * 100)}%*${formatExplainNumber(explain.rerankScore)} = ${formatExplainNumber(explain.blendedScore)}${c.reset}`);
+                if (contribSummary.length > 0) {
+                    console.log(`${c.dim}  Top RRF contributions: ${contribSummary}${c.reset}`);
+                }
+            }
             console.log();
             // Snippet with highlighting (diff-style header included)
             let displaySnippet = opts.lineNumbers ? addLineNumbers(snippet, line) : snippet;
@@ -1587,7 +1659,7 @@ function outputResults(results, query, opts) {
                 continue;
             const heading = row.title || row.displayPath;
             const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : undefined);
-            let content = opts.full ? row.body : extractSnippet(row.body, query, 500, row.chunkPos).snippet;
+            let content = opts.full ? row.body : extractSnippet(row.body, query, 500, row.chunkPos, undefined, opts.intent).snippet;
             if (opts.lineNumbers) {
                 content = addLineNumbers(content);
             }
@@ -1601,7 +1673,7 @@ function outputResults(results, query, opts) {
             const titleAttr = row.title ? ` title="${row.title.replace(/"/g, '&quot;')}"` : "";
             const contextAttr = row.context ? ` context="${row.context.replace(/"/g, '&quot;')}"` : "";
             const docid = row.docid || (row.hash ? row.hash.slice(0, 6) : "");
-            let content = opts.full ? row.body : extractSnippet(row.body, query, 500, row.chunkPos).snippet;
+            let content = opts.full ? row.body : extractSnippet(row.body, query, 500, row.chunkPos, undefined, opts.intent).snippet;
             if (opts.lineNumbers) {
                 content = addLineNumbers(content);
             }
@@ -1612,7 +1684,7 @@ function outputResults(results, query, opts) {
         // CSV format
         console.log("docid,score,file,title,context,line,snippet");
         for (const row of filtered) {
-            const { line, snippet } = extractSnippet(row.body, query, 500, row.chunkPos);
+            const { line, snippet } = extractSnippet(row.body, query, 500, row.chunkPos, undefined, opts.intent);
             let content = opts.full ? row.body : snippet;
             if (opts.lineNumbers) {
                 content = addLineNumbers(content, line);
@@ -1655,21 +1727,6 @@ function filterByCollections(results, collectionNames) {
         return prefixes.some(p => path.startsWith(p));
     });
 }
-/**
- * Parse structured search query syntax.
- * Lines starting with lex:, vec:, or hyde: are routed directly.
- * Plain lines without prefix go through query expansion.
- *
- * Returns null if this is a plain query (single line, no prefix).
- * Returns StructuredSubSearch[] if structured syntax detected.
- * Throws if multiple plain lines (ambiguous).
- *
- * Examples:
- *   "CAP theorem"                    -> null (plain query, use expansion)
- *   "lex: CAP theorem"               -> [{ type: 'lex', query: 'CAP theorem' }]
- *   "lex: CAP\nvec: consistency"     -> [{ type: 'lex', ... }, { type: 'vec', ... }]
- *   "CAP\nconsistency"               -> throws (multiple plain lines)
- */
 function parseStructuredQuery(query) {
     const rawLines = query.split('\n').map((line, idx) => ({
         raw: line,
@@ -1680,7 +1737,9 @@ function parseStructuredQuery(query) {
         return null;
     const prefixRe = /^(lex|vec|hyde):\s*/i;
     const expandRe = /^expand:\s*/i;
+    const intentRe = /^intent:\s*/i;
     const typed = [];
+    let intent;
     for (const line of rawLines) {
         if (expandRe.test(line.trimmed)) {
             if (rawLines.length > 1) {
@@ -1692,6 +1751,18 @@ function parseStructuredQuery(query) {
             }
             return null; // treat as standalone expand query
         }
+        // Parse intent: lines
+        if (intentRe.test(line.trimmed)) {
+            if (intent !== undefined) {
+                throw new Error(`Line ${line.number}: only one intent: line is allowed per query document.`);
+            }
+            const text = line.trimmed.replace(intentRe, '').trim();
+            if (!text) {
+                throw new Error(`Line ${line.number}: intent: must include text.`);
+            }
+            intent = text;
+            continue;
+        }
         const match = line.trimmed.match(prefixRe);
         if (match) {
             const type = match[1].toLowerCase();
@@ -1709,9 +1780,13 @@ function parseStructuredQuery(query) {
             // Single plain line -> implicit expand
             return null;
         }
-        throw new Error(`Line ${line.number} is missing a lex:/vec:/hyde: prefix. Each line in a query document must start with one.`);
+        throw new Error(`Line ${line.number} is missing a lex:/vec:/hyde:/intent: prefix. Each line in a query document must start with one.`);
     }
-    return typed.length > 0 ? typed : null;
+    // intent: alone is not a valid query — must have at least one search
+    if (intent && typed.length === 0) {
+        throw new Error('intent: cannot appear alone. Add at least one lex:, vec:, or hyde: line.');
+    }
+    return typed.length > 0 ? { searches: typed, intent } : null;
 }
 function search(query, opts) {
     const db = getDb();
@@ -1735,12 +1810,7 @@ function search(query, opts) {
     }));
     closeDb();
     if (resultsWithContext.length === 0) {
-        if (opts.format === "json") {
-            console.log("[]");
-        }
-        else {
-            console.log("No results found.");
-        }
+        printEmptySearchResults(opts.format);
         return;
     }
     outputResults(resultsWithContext, query, opts);
@@ -1773,6 +1843,7 @@ async function vectorSearch(query, opts, _model = DEFAULT_EMBED_MODEL) {
             collection: singleCollection,
             limit: opts.all ? 500 : (opts.limit || 10),
             minScore: opts.minScore || 0.3,
+            intent: opts.intent,
             hooks: {
                 onExpand: (original, expanded) => {
                     logExpansionTree(original, expanded);
@@ -1789,12 +1860,7 @@ async function vectorSearch(query, opts, _model = DEFAULT_EMBED_MODEL) {
         }
         closeDb();
         if (results.length === 0) {
-            if (opts.format === "json") {
-                console.log("[]");
-            }
-            else {
-                console.log("No results found.");
-            }
+            printEmptySearchResults(opts.format);
             return;
         }
         outputResults(results.map(r => ({
@@ -1815,14 +1881,20 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
     const collectionNames = resolveCollectionFilter(opts.collection, true);
     const singleCollection = collectionNames.length === 1 ? collectionNames[0] : undefined;
     checkIndexHealth(store.db);
-    // Check for structured query syntax (lex:/vec:/hyde: prefixes)
-    const structuredQueries = parseStructuredQuery(query);
+    // Check for structured query syntax (lex:/vec:/hyde:/intent: prefixes)
+    const parsed = parseStructuredQuery(query);
+    // Intent can come from --intent flag or from intent: line in query document
+    const intent = opts.intent || parsed?.intent;
     await withLLMSession(async () => {
         let results;
-        if (structuredQueries) {
+        if (parsed) {
+            const structuredQueries = parsed.searches;
             // Structured search — user provided their own query expansions
             const typeLabels = structuredQueries.map(s => s.type).join('+');
             process.stderr.write(`${c.dim}Structured search: ${structuredQueries.length} queries (${typeLabels})${c.reset}\n`);
+            if (intent) {
+                process.stderr.write(`${c.dim}├─ intent: ${intent}${c.reset}\n`);
+            }
             // Log each sub-query
             for (const s of structuredQueries) {
                 let preview = s.query.replace(/\n/g, ' ');
@@ -1835,6 +1907,9 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
                 collections: singleCollection ? [singleCollection] : undefined,
                 limit: opts.all ? 500 : (opts.limit || 10),
                 minScore: opts.minScore || 0,
+                candidateLimit: opts.candidateLimit,
+                explain: !!opts.explain,
+                intent,
                 hooks: {
                     onEmbedStart: (count) => {
                         process.stderr.write(`${c.dim}Embedding ${count} ${count === 1 ? 'query' : 'queries'}...${c.reset}`);
@@ -1859,6 +1934,9 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
                 collection: singleCollection,
                 limit: opts.all ? 500 : (opts.limit || 10),
                 minScore: opts.minScore || 0,
+                candidateLimit: opts.candidateLimit,
+                explain: !!opts.explain,
+                intent,
                 hooks: {
                     onStrongSignal: (score) => {
                         process.stderr.write(`${c.dim}Strong BM25 signal (${score.toFixed(2)}) — skipping expansion${c.reset}\n`);
@@ -1897,15 +1975,11 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
         }
         closeDb();
         if (results.length === 0) {
-            if (opts.format === "json") {
-                console.log("[]");
-            }
-            else {
-                console.log("No results found.");
-            }
+            printEmptySearchResults(opts.format);
             return;
         }
         // Use first lex/vec query for output context, or original query
+        const structuredQueries = parsed?.searches;
         const displayQuery = structuredQueries
             ? (structuredQueries.find(s => s.type === 'lex')?.query || structuredQueries.find(s => s.type === 'vec')?.query || query)
             : query;
@@ -1919,6 +1993,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
             score: r.score,
             context: r.context,
             docid: r.docid,
+            explain: r.explain,
         })), displayQuery, { ...opts, limit: results.length });
     }, { maxDuration: 10 * 60 * 1000, name: 'querySearch' });
 }
@@ -1947,6 +2022,7 @@ function parseCLI() {
             xml: { type: "boolean" },
             files: { type: "boolean" },
             json: { type: "boolean" },
+            explain: { type: "boolean" },
             collection: { type: "string", short: "c", multiple: true }, // Filter by collection(s)
             // Collection options
             name: { type: "string" }, // collection name
@@ -1961,6 +2037,9 @@ function parseCLI() {
             from: { type: "string" }, // start line
             "max-bytes": { type: "string" }, // max bytes for multi-get
             "line-numbers": { type: "boolean" }, // add line numbers to output
+            // Query options
+            "candidate-limit": { type: "string", short: "C" },
+            intent: { type: "string" },
             // MCP HTTP transport options
             http: { type: "boolean" },
             daemon: { type: "boolean" },
@@ -1999,6 +2078,9 @@ function parseCLI() {
         all: isAll,
         collection: values.collection,
         lineNumbers: !!values["line-numbers"],
+        candidateLimit: values["candidate-limit"] ? parseInt(String(values["candidate-limit"]), 10) : undefined,
+        explain: !!values.explain,
+        intent: values.intent,
     };
     return {
         command: positionals[0] || "",
@@ -2057,7 +2139,8 @@ function showHelp() {
         `query          = expand_query | query_document ;`,
         `expand_query   = text | explicit_expand ;`,
         `explicit_expand= "expand:" text ;`,
-        `query_document = { typed_line } ;`,
+        `query_document = [ intent_line ] { typed_line } ;`,
+        `intent_line    = "intent:" text newline ;`,
         `typed_line     = type ":" text newline ;`,
         `type           = "lex" | "vec" | "hyde" ;`,
         `text           = quoted_phrase | plain_text ;`,
@@ -2094,7 +2177,9 @@ function showHelp() {
     console.log("  --all                      - Return all matches (pair with --min-score)");
     console.log("  --min-score <num>          - Minimum similarity score");
     console.log("  --full                     - Output full document instead of snippet");
+    console.log("  -C, --candidate-limit <n>  - Max candidates to rerank (default 40, lower = faster)");
     console.log("  --line-numbers             - Include line numbers in output");
+    console.log("  --explain                  - Include retrieval score traces (query --json/CLI)");
     console.log("  --files | --json | --csv | --md | --xml  - Output format");
     console.log("  -c, --collection <name>    - Filter by one or more collections");
     console.log("");