@tobilu/qmd 1.1.1 → 1.1.5

package/dist/store.js

@@ -667,8 +667,8 @@ export function createStore(dbPath) {
         searchFTS: (query, limit, collectionName) => searchFTS(db, query, limit, collectionName),
         searchVec: (query, model, limit, collectionName, session, precomputedEmbedding) => searchVec(db, query, model, limit, collectionName, session, precomputedEmbedding),
         // Query expansion & reranking
-        expandQuery: (query, model) => expandQuery(query, model, db),
-        rerank: (query, documents, model) => rerank(query, documents, model, db),
+        expandQuery: (query, model, intent) => expandQuery(query, model, db, intent),
+        rerank: (query, documents, model, intent) => rerank(query, documents, model, db, intent),
         // Document retrieval
         findDocument: (filename, options) => findDocument(db, filename, options),
         getDocumentBody: (doc, fromLine, maxLines) => getDocumentBody(db, doc, fromLine, maxLines),
@@ -706,15 +706,24 @@ export function getDocid(hash) {
  * - Preserve folder structure (a/b/c/d.md stays structured)
  * - Preserve file extension
  */
+/** Replace emoji/symbol codepoints with their hex representation (e.g. 🐘 → 1f418) */
+function emojiToHex(str) {
+    return str.replace(/(?:\p{So}\p{Mn}?|\p{Sk})+/gu, (run) => {
+        // Split the run into individual emoji and convert each to hex, dash-separated
+        return [...run].filter(c => /\p{So}|\p{Sk}/u.test(c))
+            .map(c => c.codePointAt(0).toString(16)).join('-');
+    });
+}
 export function handelize(path) {
     if (!path || path.trim() === '') {
         throw new Error('handelize: path cannot be empty');
     }
     // Allow route-style "$" filenames while still rejecting paths with no usable content.
+    // Emoji (\p{So}) counts as valid content — they get converted to hex codepoints below.
     const segments = path.split('/').filter(Boolean);
     const lastSegment = segments[segments.length - 1] || '';
     const filenameWithoutExt = lastSegment.replace(/\.[^.]+$/, '');
-    const hasValidContent = /[\p{L}\p{N}$]/u.test(filenameWithoutExt);
+    const hasValidContent = /[\p{L}\p{N}\p{So}\p{Sk}$]/u.test(filenameWithoutExt);
     if (!hasValidContent) {
         throw new Error(`handelize: path "${path}" has no valid filename content`);
     }
@@ -724,6 +733,8 @@ export function handelize(path) {
         .split('/')
         .map((segment, idx, arr) => {
         const isLastSegment = idx === arr.length - 1;
+        // Convert emoji to hex codepoints before cleaning
+        segment = emojiToHex(segment);
         if (isLastSegment) {
             // For the filename (last segment), preserve the extension
             const extMatch = segment.match(/(\.[a-z0-9]+)$/i);
@@ -1745,7 +1756,7 @@ export async function searchVec(db, query, model, limit = 20, collectionName, se
 // =============================================================================
 async function getEmbedding(text, model, isQuery, session) {
     // Format text using the appropriate prompt template
-    const formattedText = isQuery ? formatQueryForEmbedding(text) : formatDocForEmbedding(text);
+    const formattedText = isQuery ? formatQueryForEmbedding(text, model) : formatDocForEmbedding(text, undefined, model);
     const result = session
         ? await session.embed(formattedText, { model, isQuery })
         : await getDefaultLlamaCpp().embed(formattedText, { model, isQuery });
@@ -1787,9 +1798,9 @@ export function insertEmbedding(db, hash, seq, pos, embedding, model, embeddedAt
 // =============================================================================
 // Query expansion
 // =============================================================================
-export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db) {
+export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, intent) {
     // Check cache first — stored as JSON preserving types
-    const cacheKey = getCacheKey("expandQuery", { query, model });
+    const cacheKey = getCacheKey("expandQuery", { query, model, ...(intent && { intent }) });
     const cached = getCachedResult(db, cacheKey);
     if (cached) {
         try {
@@ -1801,7 +1812,7 @@ export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db) {
     }
     const llm = getDefaultLlamaCpp();
     // Note: LlamaCpp uses hardcoded model, model parameter is ignored
-    const results = await llm.expandQuery(query);
+    const results = await llm.expandQuery(query, { intent });
     // Map Queryable[] → ExpandedQuery[] (same shape, decoupled from llm.ts internals).
     // Filter out entries that duplicate the original query text.
     const expanded = results
@@ -1815,37 +1826,44 @@ export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db) {
 // =============================================================================
 // Reranking
 // =============================================================================
-export async function rerank(query, documents, model = DEFAULT_RERANK_MODEL, db) {
+export async function rerank(query, documents, model = DEFAULT_RERANK_MODEL, db, intent) {
+    // Prepend intent to rerank query so the reranker scores with domain context
+    const rerankQuery = intent ? `${intent}\n\n${query}` : query;
     const cachedResults = new Map();
-    const uncachedDocs = [];
+    const uncachedDocsByChunk = new Map();
     // Check cache for each document
     // Cache key includes chunk text — different queries can select different chunks
     // from the same file, and the reranker score depends on which chunk was sent.
+    // File path is excluded from the new cache key because the reranker score
+    // depends on the chunk content, not where it came from.
     for (const doc of documents) {
-        const cacheKey = getCacheKey("rerank", { query, file: doc.file, model, chunk: doc.text });
-        const cached = getCachedResult(db, cacheKey);
+        const cacheKey = getCacheKey("rerank", { query: rerankQuery, model, chunk: doc.text });
+        const legacyCacheKey = getCacheKey("rerank", { query, file: doc.file, model, chunk: doc.text });
+        const cached = getCachedResult(db, cacheKey) ?? getCachedResult(db, legacyCacheKey);
         if (cached !== null) {
-            cachedResults.set(doc.file, parseFloat(cached));
+            cachedResults.set(doc.text, parseFloat(cached));
         }
         else {
-            uncachedDocs.push({ file: doc.file, text: doc.text });
+            uncachedDocsByChunk.set(doc.text, { file: doc.file, text: doc.text });
         }
     }
     // Rerank uncached documents using LlamaCpp
-    if (uncachedDocs.length > 0) {
+    if (uncachedDocsByChunk.size > 0) {
         const llm = getDefaultLlamaCpp();
-        const rerankResult = await llm.rerank(query, uncachedDocs, { model });
-        // Cache results — use original doc.text for cache key (result.file lacks chunk text)
-        const textByFile = new Map(documents.map(d => [d.file, d.text]));
+        const uncachedDocs = [...uncachedDocsByChunk.values()];
+        const rerankResult = await llm.rerank(rerankQuery, uncachedDocs, { model });
+        // Cache results by chunk text so identical chunks across files are scored once.
+        const textByFile = new Map(uncachedDocs.map(d => [d.file, d.text]));
         for (const result of rerankResult.results) {
-            const cacheKey = getCacheKey("rerank", { query, file: result.file, model, chunk: textByFile.get(result.file) || "" });
+            const chunk = textByFile.get(result.file) || "";
+            const cacheKey = getCacheKey("rerank", { query: rerankQuery, model, chunk });
             setCachedResult(db, cacheKey, result.score.toString());
-            cachedResults.set(result.file, result.score);
+            cachedResults.set(chunk, result.score);
         }
     }
     // Return all results sorted by score
     return documents
-        .map(doc => ({ file: doc.file, score: cachedResults.get(doc.file) || 0 }))
+        .map(doc => ({ file: doc.file, score: cachedResults.get(doc.text) || 0 }))
         .sort((a, b) => b.score - a.score);
 }
 // =============================================================================
@@ -1890,6 +1908,65 @@ export function reciprocalRankFusion(resultLists, weights = [], k = 60) {
         .sort((a, b) => b.rrfScore - a.rrfScore)
         .map(e => ({ ...e.result, score: e.rrfScore }));
 }
+/**
+ * Build per-document RRF contribution traces for explain/debug output.
+ */
+export function buildRrfTrace(resultLists, weights = [], listMeta = [], k = 60) {
+    const traces = new Map();
+    for (let listIdx = 0; listIdx < resultLists.length; listIdx++) {
+        const list = resultLists[listIdx];
+        if (!list)
+            continue;
+        const weight = weights[listIdx] ?? 1.0;
+        const meta = listMeta[listIdx] ?? {
+            source: "fts",
+            queryType: "original",
+            query: "",
+        };
+        for (let rank0 = 0; rank0 < list.length; rank0++) {
+            const result = list[rank0];
+            if (!result)
+                continue;
+            const rank = rank0 + 1; // 1-indexed rank for explain output
+            const contribution = weight / (k + rank);
+            const existing = traces.get(result.file);
+            const detail = {
+                listIndex: listIdx,
+                source: meta.source,
+                queryType: meta.queryType,
+                query: meta.query,
+                rank,
+                weight,
+                backendScore: result.score,
+                rrfContribution: contribution,
+            };
+            if (existing) {
+                existing.baseScore += contribution;
+                existing.topRank = Math.min(existing.topRank, rank);
+                existing.contributions.push(detail);
+            }
+            else {
+                traces.set(result.file, {
+                    contributions: [detail],
+                    baseScore: contribution,
+                    topRank: rank,
+                    topRankBonus: 0,
+                    totalScore: 0,
+                });
+            }
+        }
+    }
+    for (const trace of traces.values()) {
+        let bonus = 0;
+        if (trace.topRank === 1)
+            bonus = 0.05;
+        else if (trace.topRank <= 3)
+            bonus = 0.02;
+        trace.topRankBonus = bonus;
+        trace.totalScore = trace.baseScore + bonus;
+    }
+    return traces;
+}
 /**
  * Find a document by filename/path, docid (#hash), or with fuzzy matching.
  * Returns document metadata without body by default.
@@ -2179,7 +2256,41 @@ export function getStatus(db) {
         collections,
     };
 }
-export function extractSnippet(body, query, maxLen = 500, chunkPos, chunkLen) {
+/** Weight for intent terms relative to query terms (1.0) in snippet scoring */
+export const INTENT_WEIGHT_SNIPPET = 0.3;
+/** Weight for intent terms relative to query terms (1.0) in chunk selection */
+export const INTENT_WEIGHT_CHUNK = 0.5;
+// Common stop words filtered from intent strings before tokenization.
+// Seeded from finetune/reward.py KEY_TERM_STOPWORDS, extended with common
+// 2-3 char function words so the length threshold can drop to >1 and let
+// short domain terms (API, SQL, LLM, CPU, CDN, …) survive.
+const INTENT_STOP_WORDS = new Set([
+    // 2-char function words
+    "am", "an", "as", "at", "be", "by", "do", "he", "if",
+    "in", "is", "it", "me", "my", "no", "of", "on", "or", "so",
+    "to", "up", "us", "we",
+    // 3-char function words
+    "all", "and", "any", "are", "but", "can", "did", "for", "get",
+    "has", "her", "him", "his", "how", "its", "let", "may", "not",
+    "our", "out", "the", "too", "was", "who", "why", "you",
+    // 4+ char common words
+    "also", "does", "find", "from", "have", "into", "more", "need",
+    "show", "some", "tell", "that", "them", "this", "want", "what",
+    "when", "will", "with", "your",
+    // Search-context noise
+    "about", "looking", "notes", "search", "where", "which",
+]);
+/**
+ * Extract meaningful terms from an intent string, filtering stop words and punctuation.
+ * Uses Unicode-aware punctuation stripping so domain terms like "API" survive.
+ * Returns lowercase terms suitable for text matching.
+ */
+export function extractIntentTerms(intent) {
+    return intent.toLowerCase().split(/\s+/)
+        .map(t => t.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, ""))
+        .filter(t => t.length > 1 && !INTENT_STOP_WORDS.has(t));
+}
+export function extractSnippet(body, query, maxLen = 500, chunkPos, chunkLen, intent) {
     const totalLines = body.split('\n').length;
     let searchBody = body;
     let lineOffset = 0;
@@ -2196,13 +2307,18 @@ export function extractSnippet(body, query, maxLen = 500, chunkPos, chunkLen) {
     }
     const lines = searchBody.split('\n');
     const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length > 0);
+    const intentTerms = intent ? extractIntentTerms(intent) : [];
     let bestLine = 0, bestScore = -1;
     for (let i = 0; i < lines.length; i++) {
         const lineLower = (lines[i] ?? "").toLowerCase();
         let score = 0;
         for (const term of queryTerms) {
             if (lineLower.includes(term))
-                score++;
+                score += 1.0;
+        }
+        for (const term of intentTerms) {
+            if (lineLower.includes(term))
+                score += INTENT_WEIGHT_SNIPPET;
         }
         if (score > bestScore) {
             bestScore = score;
@@ -2216,7 +2332,7 @@ export function extractSnippet(body, query, maxLen = 500, chunkPos, chunkLen) {
     // If we focused on a chunk window and it produced an empty/whitespace-only snippet,
     // fall back to a full-document snippet so we always show something useful.
     if (chunkPos && chunkPos > 0 && snippetText.trim().length === 0) {
-        return extractSnippet(body, query, maxLen, undefined);
+        return extractSnippet(body, query, maxLen, undefined, undefined, intent);
     }
     if (snippetText.length > maxLen)
         snippetText = snippetText.substring(0, maxLen - 3) + "...";
@@ -2264,16 +2380,22 @@ export async function hybridQuery(store, query, options) {
     const minScore = options?.minScore ?? 0;
     const candidateLimit = options?.candidateLimit ?? RERANK_CANDIDATE_LIMIT;
     const collection = options?.collection;
+    const explain = options?.explain ?? false;
+    const intent = options?.intent;
     const hooks = options?.hooks;
     const rankedLists = [];
+    const rankedListMeta = [];
     const docidMap = new Map(); // filepath -> docid
     const hasVectors = !!store.db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
     // Step 1: BM25 probe — strong signal skips expensive LLM expansion
+    // When intent is provided, disable strong-signal bypass — the obvious BM25
+    // match may not be what the caller wants (e.g. "performance" with intent
+    // "web page load times" should NOT shortcut to a sports-performance doc).
     // Pass collection directly into FTS query (filter at SQL level, not post-hoc)
     const initialFts = store.searchFTS(query, 20, collection);
     const topScore = initialFts[0]?.score ?? 0;
     const secondScore = initialFts[1]?.score ?? 0;
-    const hasStrongSignal = initialFts.length > 0
+    const hasStrongSignal = !intent && initialFts.length > 0
         && topScore >= STRONG_SIGNAL_MIN_SCORE
         && (topScore - secondScore) >= STRONG_SIGNAL_MIN_GAP;
     if (hasStrongSignal)
@@ -2283,7 +2405,7 @@ export async function hybridQuery(store, query, options) {
     const expandStart = Date.now();
     const expanded = hasStrongSignal
         ? []
-        : await store.expandQuery(query);
+        : await store.expandQuery(query, undefined, intent);
     hooks?.onExpand?.(query, expanded, Date.now() - expandStart);
     // Seed with initial FTS results (avoid re-running original query FTS)
     if (initialFts.length > 0) {
@@ -2293,6 +2415,7 @@ export async function hybridQuery(store, query, options) {
             file: r.filepath, displayPath: r.displayPath,
             title: r.title, body: r.body || "", score: r.score,
         })));
+        rankedListMeta.push({ source: "fts", queryType: "original", query });
     }
     // Step 3: Route searches by query type
     //
@@ -2310,17 +2433,18 @@ export async function hybridQuery(store, query, options) {
                     file: r.filepath, displayPath: r.displayPath,
                     title: r.title, body: r.body || "", score: r.score,
                 })));
+                rankedListMeta.push({ source: "fts", queryType: "lex", query: q.text });
             }
         }
     }
     // 3b: Collect all texts that need vector search (original query + vec/hyde expansions)
     if (hasVectors) {
         const vecQueries = [
-            { text: query, isOriginal: true },
+            { text: query, queryType: "original" },
         ];
         for (const q of expanded) {
             if (q.type === 'vec' || q.type === 'hyde') {
-                vecQueries.push({ text: q.text, isOriginal: false });
+                vecQueries.push({ text: q.text, queryType: q.type });
             }
         }
         // Batch embed all vector queries in a single call
@@ -2343,18 +2467,25 @@ export async function hybridQuery(store, query, options) {
                     file: r.filepath, displayPath: r.displayPath,
                     title: r.title, body: r.body || "", score: r.score,
                 })));
+                rankedListMeta.push({
+                    source: "vec",
+                    queryType: vecQueries[i].queryType,
+                    query: vecQueries[i].text,
+                });
             }
         }
     }
     // Step 4: RRF fusion — first 2 lists (original FTS + first vec) get 2x weight
     const weights = rankedLists.map((_, i) => i < 2 ? 2.0 : 1.0);
     const fused = reciprocalRankFusion(rankedLists, weights);
+    const rrfTraceByFile = explain ? buildRrfTrace(rankedLists, weights, rankedListMeta) : null;
     const candidates = fused.slice(0, candidateLimit);
     if (candidates.length === 0)
         return [];
     // Step 5: Chunk documents, pick best chunk per doc for reranking.
     // Reranking full bodies is O(tokens) — the critical perf lesson that motivated this refactor.
     const queryTerms = query.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+    const intentTerms = intent ? extractIntentTerms(intent) : [];
     const chunksToRerank = [];
     const docChunkMap = new Map();
     for (const cand of candidates) {
@@ -2362,11 +2493,16 @@ export async function hybridQuery(store, query, options) {
         if (chunks.length === 0)
             continue;
         // Pick chunk with most keyword overlap (fallback: first chunk)
+        // Intent terms contribute at INTENT_WEIGHT_CHUNK (0.5) relative to query terms (1.0)
         let bestIdx = 0;
         let bestScore = -1;
         for (let i = 0; i < chunks.length; i++) {
             const chunkLower = chunks[i].text.toLowerCase();
-            const score = queryTerms.reduce((acc, term) => acc + (chunkLower.includes(term) ? 1 : 0), 0);
+            let score = queryTerms.reduce((acc, term) => acc + (chunkLower.includes(term) ? 1 : 0), 0);
+            for (const term of intentTerms) {
+                if (chunkLower.includes(term))
+                    score += INTENT_WEIGHT_CHUNK;
+            }
             if (score > bestScore) {
                 bestScore = score;
                 bestIdx = i;
@@ -2378,7 +2514,7 @@ export async function hybridQuery(store, query, options) {
     // Step 6: Rerank chunks (NOT full bodies)
     hooks?.onRerankStart?.(chunksToRerank.length);
     const rerankStart = Date.now();
-    const reranked = await store.rerank(query, chunksToRerank);
+    const reranked = await store.rerank(query, chunksToRerank, undefined, intent);
     hooks?.onRerankDone?.(Date.now() - rerankStart);
     // Step 7: Blend RRF position score with reranker score
     // Position-aware weights: top retrieval results get more protection from reranker disagreement
@@ -2402,6 +2538,22 @@ export async function hybridQuery(store, query, options) {
         const bestIdx = chunkInfo?.bestIdx ?? 0;
         const bestChunk = chunkInfo?.chunks[bestIdx]?.text || candidate?.body || "";
         const bestChunkPos = chunkInfo?.chunks[bestIdx]?.pos || 0;
+        const trace = rrfTraceByFile?.get(r.file);
+        const explainData = explain ? {
+            ftsScores: trace?.contributions.filter(c => c.source === "fts").map(c => c.backendScore) ?? [],
+            vectorScores: trace?.contributions.filter(c => c.source === "vec").map(c => c.backendScore) ?? [],
+            rrf: {
+                rank: rrfRank,
+                positionScore: rrfScore,
+                weight: rrfWeight,
+                baseScore: trace?.baseScore ?? 0,
+                topRankBonus: trace?.topRankBonus ?? 0,
+                totalScore: trace?.totalScore ?? 0,
+                contributions: trace?.contributions ?? [],
+            },
+            rerankScore: r.score,
+            blendedScore,
+        } : undefined;
         return {
             file: r.file,
             displayPath: candidate?.displayPath || "",
@@ -2412,6 +2564,7 @@ export async function hybridQuery(store, query, options) {
             score: blendedScore,
             context: store.getContextForFile(r.file),
             docid: docidMap.get(r.file) || "",
+            ...(explainData ? { explain: explainData } : {}),
         };
     }).sort((a, b) => b.score - a.score);
     // Step 8: Dedup by file (safety net — prevents duplicate output)
@@ -2439,12 +2592,13 @@ export async function vectorSearchQuery(store, query, options) {
     const limit = options?.limit ?? 10;
     const minScore = options?.minScore ?? 0.3;
     const collection = options?.collection;
+    const intent = options?.intent;
     const hasVectors = !!store.db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
     if (!hasVectors)
         return [];
     // Expand query — filter to vec/hyde only (lex queries target FTS, not vector)
     const expandStart = Date.now();
-    const allExpanded = await store.expandQuery(query);
+    const allExpanded = await store.expandQuery(query, undefined, intent);
     const vecExpanded = allExpanded.filter(q => q.type !== 'lex');
     options?.hooks?.onExpand?.(query, vecExpanded, Date.now() - expandStart);
     // Run original + vec/hyde expanded through vector, sequentially — concurrent embed() hangs
@@ -2494,6 +2648,8 @@ export async function structuredSearch(store, searches, options) {
     const limit = options?.limit ?? 10;
     const minScore = options?.minScore ?? 0;
     const candidateLimit = options?.candidateLimit ?? RERANK_CANDIDATE_LIMIT;
+    const explain = options?.explain ?? false;
+    const intent = options?.intent;
     const hooks = options?.hooks;
     const collections = options?.collections;
     if (searches.length === 0)
@@ -2518,6 +2674,7 @@ export async function structuredSearch(store, searches, options) {
         }
     }
     const rankedLists = [];
+    const rankedListMeta = [];
     const docidMap = new Map(); // filepath -> docid
     const hasVectors = !!store.db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
     // Helper to run search across collections (or all if undefined)
@@ -2534,13 +2691,18 @@ export async function structuredSearch(store, searches, options) {
                         file: r.filepath, displayPath: r.displayPath,
                         title: r.title, body: r.body || "", score: r.score,
                     })));
+                    rankedListMeta.push({
+                        source: "fts",
+                        queryType: "lex",
+                        query: search.query,
+                    });
                 }
             }
         }
     }
     // Step 2: Batch embed and run vector searches for vec/hyde
     if (hasVectors) {
-        const vecSearches = searches.filter(s => s.type === 'vec' || s.type === 'hyde');
+        const vecSearches = searches.filter((s) => s.type === 'vec' || s.type === 'hyde');
         if (vecSearches.length > 0) {
             const llm = getDefaultLlamaCpp();
             const textsToEmbed = vecSearches.map(s => formatQueryForEmbedding(s.query));
@@ -2561,6 +2723,11 @@ export async function structuredSearch(store, searches, options) {
                             file: r.filepath, displayPath: r.displayPath,
                             title: r.title, body: r.body || "", score: r.score,
                         })));
+                        rankedListMeta.push({
+                            source: "vec",
+                            queryType: vecSearches[i].type,
+                            query: vecSearches[i].query,
+                        });
                     }
                 }
             }
@@ -2571,6 +2738,7 @@ export async function structuredSearch(store, searches, options) {
     // Step 3: RRF fusion — first list gets 2x weight (assume caller ordered by importance)
     const weights = rankedLists.map((_, i) => i === 0 ? 2.0 : 1.0);
     const fused = reciprocalRankFusion(rankedLists, weights);
+    const rrfTraceByFile = explain ? buildRrfTrace(rankedLists, weights, rankedListMeta) : null;
     const candidates = fused.slice(0, candidateLimit);
     if (candidates.length === 0)
         return [];
@@ -2581,6 +2749,7 @@ export async function structuredSearch(store, searches, options) {
         || searches.find(s => s.type === 'vec')?.query
         || searches[0]?.query || "";
     const queryTerms = primaryQuery.toLowerCase().split(/\s+/).filter(t => t.length > 2);
+    const intentTerms = intent ? extractIntentTerms(intent) : [];
     const chunksToRerank = [];
     const docChunkMap = new Map();
     for (const cand of candidates) {
@@ -2588,11 +2757,16 @@ export async function structuredSearch(store, searches, options) {
         if (chunks.length === 0)
             continue;
         // Pick chunk with most keyword overlap
+        // Intent terms contribute at INTENT_WEIGHT_CHUNK (0.5) relative to query terms (1.0)
         let bestIdx = 0;
         let bestScore = -1;
         for (let i = 0; i < chunks.length; i++) {
             const chunkLower = chunks[i].text.toLowerCase();
-            const score = queryTerms.reduce((acc, term) => acc + (chunkLower.includes(term) ? 1 : 0), 0);
+            let score = queryTerms.reduce((acc, term) => acc + (chunkLower.includes(term) ? 1 : 0), 0);
+            for (const term of intentTerms) {
+                if (chunkLower.includes(term))
+                    score += INTENT_WEIGHT_CHUNK;
+            }
             if (score > bestScore) {
                 bestScore = score;
                 bestIdx = i;
@@ -2604,7 +2778,7 @@ export async function structuredSearch(store, searches, options) {
     // Step 5: Rerank chunks
     hooks?.onRerankStart?.(chunksToRerank.length);
     const rerankStart2 = Date.now();
-    const reranked = await store.rerank(primaryQuery, chunksToRerank);
+    const reranked = await store.rerank(primaryQuery, chunksToRerank, undefined, intent);
     hooks?.onRerankDone?.(Date.now() - rerankStart2);
     // Step 6: Blend RRF position score with reranker score
     const candidateMap = new Map(candidates.map(c => [c.file, {
@@ -2627,6 +2801,22 @@ export async function structuredSearch(store, searches, options) {
         const bestIdx = chunkInfo?.bestIdx ?? 0;
         const bestChunk = chunkInfo?.chunks[bestIdx]?.text || candidate?.body || "";
         const bestChunkPos = chunkInfo?.chunks[bestIdx]?.pos || 0;
+        const trace = rrfTraceByFile?.get(r.file);
+        const explainData = explain ? {
+            ftsScores: trace?.contributions.filter(c => c.source === "fts").map(c => c.backendScore) ?? [],
+            vectorScores: trace?.contributions.filter(c => c.source === "vec").map(c => c.backendScore) ?? [],
+            rrf: {
+                rank: rrfRank,
+                positionScore: rrfScore,
+                weight: rrfWeight,
+                baseScore: trace?.baseScore ?? 0,
+                topRankBonus: trace?.topRankBonus ?? 0,
+                totalScore: trace?.totalScore ?? 0,
+                contributions: trace?.contributions ?? [],
+            },
+            rerankScore: r.score,
+            blendedScore,
+        } : undefined;
         return {
             file: r.file,
             displayPath: candidate?.displayPath || "",
@@ -2637,6 +2827,7 @@ export async function structuredSearch(store, searches, options) {
             score: blendedScore,
             context: store.getContextForFile(r.file),
             docid: docidMap.get(r.file) || "",
+            ...(explainData ? { explain: explainData } : {}),
         };
     }).sort((a, b) => b.score - a.score);
     // Step 7: Dedup by file

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tobilu/qmd",
-  "version": "1.1.1",
+  "version": "1.1.5",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
   "bin": {
@@ -39,7 +39,7 @@
     "@modelcontextprotocol/sdk": "^1.25.1",
     "better-sqlite3": "^11.0.0",
     "fast-glob": "^3.3.0",
-    "node-llama-cpp": "^3.14.5",
+    "node-llama-cpp": "^3.17.1",
     "picomatch": "^4.0.0",
     "sqlite-vec": "^0.1.7-alpha.2",
     "yaml": "^2.8.2",
@@ -48,8 +48,9 @@
   "optionalDependencies": {
     "sqlite-vec-darwin-arm64": "^0.1.7-alpha.2",
     "sqlite-vec-darwin-x64": "^0.1.7-alpha.2",
+    "sqlite-vec-linux-arm64": "^0.1.7-alpha.2",
     "sqlite-vec-linux-x64": "^0.1.7-alpha.2",
-    "sqlite-vec-win32-x64": "^0.1.7-alpha.2"
+    "sqlite-vec-windows-x64": "^0.1.7-alpha.2"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",