@tobilu/qmd 1.1.2 → 1.1.6

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 ## [Unreleased]
 
+## [1.1.6] - 2026-03-09
+
+QMD can now be used as a library. `import { createStore } from '@tobilu/qmd'`
+gives you the full search and indexing API — hybrid query, BM25, structured
+search, collection/context management — without shelling out to the CLI.
+
+### Changes
+
+- **SDK / library mode**: `createStore({ dbPath, config })` returns a
+  `QMDStore` with `query()`, `search()`, `structuredSearch()`, `get()`,
+  `multiGet()`, and collection/context management methods. Supports inline
+  config (no files needed) or a YAML config path.
+- **Package exports**: `package.json` now declares `main`, `types`, and
+  `exports` so bundlers and TypeScript resolve `@tobilu/qmd` correctly.
+
+## [1.1.5] - 2026-03-07
+
+Ambiguous queries like "performance" now produce dramatically better results
+when the caller knows what they mean. The new `intent` parameter steers all
+five pipeline stages — expansion, strong-signal bypass, chunk selection,
+reranking, and snippet extraction — without searching on its own. Design and
+original implementation by Ilya Grigorik (@vyalamar) in #180.
+
+### Changes
+
+- **Intent parameter**: optional `intent` string disambiguates queries across
+  the entire search pipeline. Available via CLI (`--intent` flag or `intent:`
+  line in query documents), MCP (`intent` field on the query tool), and
+  programmatic API. Adapted from PR #180 (thanks @vyalamar).
+- **Query expansion**: when intent is provided, the expansion LLM prompt
+  includes `Query intent: {intent}`, matching the finetune training data
+  format for better-aligned expansions.
+- **Reranking**: intent is prepended to the rerank query so Qwen3-Reranker
+  scores with domain context.
+- **Chunk selection**: intent terms scored at 0.5× weight alongside query
+  terms (1.0×) when selecting the best chunk per document for reranking.
+- **Snippet extraction**: intent terms scored at 0.3× weight to nudge
+  snippets toward intent-relevant lines without overriding query anchoring.
+- **Strong-signal bypass disabled with intent**: when intent is provided, the
+  BM25 strong-signal shortcut is skipped — the obvious keyword match may not
+  be what the caller wants.
+- **MCP instructions**: callers are now guided to provide `intent` on every
+  search call for disambiguation.
+- **Query document syntax**: `intent:` recognized as a line type. At most one
+  per document, cannot appear alone. Grammar updated in `docs/SYNTAX.md`.
+
 ## [1.1.2] - 2026-03-07
 
 13 community PRs merged. GPU initialization replaced with node-llama-cpp's

package/README.md

@@ -137,6 +137,81 @@ LLM models stay loaded in VRAM across requests. Embedding/reranking contexts are
 
 Point any MCP client at `http://localhost:8181/mcp` to connect.
 
+### SDK / Library Usage
+
+Use QMD as a library in your own Node.js or Bun applications:
+
+```sh
+npm install @tobilu/qmd
+```
+
+```typescript
+import { createStore } from '@tobilu/qmd'
+
+// Create a store with inline config (no config file needed)
+const store = createStore({
+  dbPath: './my-index.sqlite',
+  config: {
+    collections: {
+      docs: { path: '/path/to/docs', pattern: '**/*.md' },
+      notes: { path: '/path/to/notes', pattern: '**/*.md' },
+    },
+  },
+})
+
+// Or reference a YAML config file
+const store2 = createStore({
+  dbPath: './my-index.sqlite',
+  configPath: './qmd.yml',
+})
+```
+
+**Search & retrieval:**
+
+```typescript
+// Hybrid search: BM25 + vector + query expansion + LLM reranking (best quality)
+const results = await store.query("authentication flow", { limit: 5 })
+
+// Fast BM25 keyword search (no LLM, synchronous)
+const keywords = store.search("auth middleware", { limit: 10 })
+
+// Structured search with pre-expanded queries (for LLM callers)
+const structured = await store.structuredSearch([
+  { type: 'lex', query: 'authentication' },
+  { type: 'vec', query: 'how users log in' },
+], { limit: 5 })
+
+// Get a document by path or docid
+const doc = store.get("docs/readme.md")
+const byId = store.get("#abc123")
+
+// Get multiple documents by glob
+const { docs, errors } = store.multiGet("docs/**/*.md")
+```
+
+**Collection & context management:**
+
+```typescript
+// Add a collection
+store.addCollection("myapp", { path: "/src/myapp", pattern: "**/*.ts" })
+
+// Add context (improves search relevance)
+store.addContext("myapp", "/auth", "Authentication and session management")
+store.setGlobalContext("Internal engineering documentation")
+
+// List everything
+store.listCollections()
+store.listContexts()
+```
+
+**Lifecycle:**
+
+```typescript
+store.close()
+```
+
+The SDK requires explicit `dbPath` and config — no defaults are assumed. This makes it safe to embed in any application without side effects.
+
 ## Architecture
 
 ```

package/dist/collections.d.ts

@@ -34,18 +34,32 @@ export interface CollectionConfig {
 export interface NamedCollection extends Collection {
     name: string;
 }
+/**
+ * Set the config source for SDK mode.
+ * - File path: load/save from a specific YAML file
+ * - Inline config: use an in-memory CollectionConfig (saveConfig updates in place, no file I/O)
+ * - undefined: reset to default file-based config
+ */
+export declare function setConfigSource(source?: {
+    configPath?: string;
+    config?: CollectionConfig;
+}): void;
 /**
  * Set the current index name for config file lookup
  * Config file will be ~/.config/qmd/{indexName}.yml
  */
 export declare function setConfigIndexName(name: string): void;
 /**
- * Load configuration from ~/.config/qmd/index.yml
+ * Load configuration from the configured source.
+ * - Inline config: returns the in-memory object directly
+ * - File-based: reads from YAML file (default ~/.config/qmd/index.yml)
  * Returns empty config if file doesn't exist
  */
 export declare function loadConfig(): CollectionConfig;
 /**
- * Save configuration to ~/.config/qmd/index.yml
+ * Save configuration to the configured source.
+ * - Inline config: updates the in-memory object (no file I/O)
+ * - File-based: writes to YAML file (default ~/.config/qmd/index.yml)
  */
 export declare function saveConfig(config: CollectionConfig): void;
 /**

package/dist/collections.js

@@ -5,7 +5,7 @@
  * Collections define which directories to index and their associated contexts.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { join } from "path";
+import { join, dirname } from "path";
 import { homedir } from "os";
 import YAML from "yaml";
 // ============================================================================
@@ -13,6 +13,33 @@ import YAML from "yaml";
 // ============================================================================
 // Current index name (default: "index")
 let currentIndexName = "index";
+// SDK mode: optional in-memory config or custom config path
+let configSource = { type: 'file' };
+/**
+ * Set the config source for SDK mode.
+ * - File path: load/save from a specific YAML file
+ * - Inline config: use an in-memory CollectionConfig (saveConfig updates in place, no file I/O)
+ * - undefined: reset to default file-based config
+ */
+export function setConfigSource(source) {
+    if (!source) {
+        configSource = { type: 'file' };
+        return;
+    }
+    if (source.config) {
+        // Ensure collections object exists
+        if (!source.config.collections) {
+            source.config.collections = {};
+        }
+        configSource = { type: 'inline', config: source.config };
+    }
+    else if (source.configPath) {
+        configSource = { type: 'file', path: source.configPath };
+    }
+    else {
+        configSource = { type: 'file' };
+    }
+}
 /**
  * Set the current index name for config file lookup
  * Config file will be ~/.config/qmd/{indexName}.yml
@@ -57,11 +84,18 @@ function ensureConfigDir() {
 // Core functions
 // ============================================================================
 /**
- * Load configuration from ~/.config/qmd/index.yml
+ * Load configuration from the configured source.
+ * - Inline config: returns the in-memory object directly
+ * - File-based: reads from YAML file (default ~/.config/qmd/index.yml)
  * Returns empty config if file doesn't exist
  */
 export function loadConfig() {
-    const configPath = getConfigFilePath();
+    // SDK inline config mode
+    if (configSource.type === 'inline') {
+        return configSource.config;
+    }
+    // File-based config (SDK custom path or default)
+    const configPath = configSource.path || getConfigFilePath();
     if (!existsSync(configPath)) {
         return { collections: {} };
     }
@@ -79,11 +113,21 @@ export function loadConfig() {
     }
 }
 /**
- * Save configuration to ~/.config/qmd/index.yml
+ * Save configuration to the configured source.
+ * - Inline config: updates the in-memory object (no file I/O)
+ * - File-based: writes to YAML file (default ~/.config/qmd/index.yml)
  */
 export function saveConfig(config) {
-    ensureConfigDir();
-    const configPath = getConfigFilePath();
+    // SDK inline config mode: update in place, no file I/O
+    if (configSource.type === 'inline') {
+        configSource.config = config;
+        return;
+    }
+    const configPath = configSource.path || getConfigFilePath();
+    const configDir = dirname(configPath);
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
     try {
         const yaml = YAML.stringify(config, {
             indent: 2,
@@ -318,13 +362,18 @@ export function findContextForPath(collectionName, filePath) {
  * Get the config file path (useful for error messages)
  */
 export function getConfigPath() {
-    return getConfigFilePath();
+    if (configSource.type === 'inline')
+        return '<inline>';
+    return configSource.path || getConfigFilePath();
 }
 /**
  * Check if config file exists
  */
 export function configExists() {
-    return existsSync(getConfigFilePath());
+    if (configSource.type === 'inline')
+        return true;
+    const path = configSource.path || getConfigFilePath();
+    return existsSync(path);
 }
 /**
  * Validate a collection name

package/dist/formatter.d.ts

@@ -28,6 +28,7 @@ export type FormatOptions = {
     query?: string;
     useColor?: boolean;
     lineNumbers?: boolean;
+    intent?: string;
 };
 /**
  * Add line numbers to text content.

package/dist/formatter.js

@@ -55,7 +55,7 @@ export function searchResultsToJson(results, opts = {}) {
     const output = results.map(row => {
         const bodyStr = row.body || "";
         let body = opts.full ? bodyStr : undefined;
-        let snippet = !opts.full ? extractSnippet(bodyStr, query, 300, row.chunkPos).snippet : undefined;
+        let snippet = !opts.full ? extractSnippet(bodyStr, query, 300, row.chunkPos, undefined, opts.intent).snippet : undefined;
         if (opts.lineNumbers) {
             if (body)
                 body = addLineNumbers(body);
@@ -82,7 +82,7 @@ export function searchResultsToCsv(results, opts = {}) {
     const header = "docid,score,file,title,context,line,snippet";
     const rows = results.map(row => {
         const bodyStr = row.body || "";
-        const { line, snippet } = extractSnippet(bodyStr, query, 500, row.chunkPos);
+        const { line, snippet } = extractSnippet(bodyStr, query, 500, row.chunkPos, undefined, opts.intent);
         let content = opts.full ? bodyStr : snippet;
         if (opts.lineNumbers && content) {
             content = addLineNumbers(content);
@@ -121,7 +121,7 @@ export function searchResultsToMarkdown(results, opts = {}) {
             content = bodyStr;
         }
         else {
-            content = extractSnippet(bodyStr, query, 500, row.chunkPos).snippet;
+            content = extractSnippet(bodyStr, query, 500, row.chunkPos, undefined, opts.intent).snippet;
         }
         if (opts.lineNumbers) {
             content = addLineNumbers(content);
@@ -138,7 +138,7 @@ export function searchResultsToXml(results, opts = {}) {
     const items = results.map(row => {
         const titleAttr = row.title ? ` title="${escapeXml(row.title)}"` : "";
         const bodyStr = row.body || "";
-        let content = opts.full ? bodyStr : extractSnippet(bodyStr, query, 500, row.chunkPos).snippet;
+        let content = opts.full ? bodyStr : extractSnippet(bodyStr, query, 500, row.chunkPos, undefined, opts.intent).snippet;
         if (opts.lineNumbers) {
             content = addLineNumbers(content);
         }

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * QMD SDK - Library mode for programmatic access to QMD search and indexing.
+ *
+ * Usage:
+ *   import { createStore } from '@tobilu/qmd'
+ *
+ *   const store = createStore({
+ *     dbPath: './my-index.sqlite',
+ *     config: {
+ *       collections: {
+ *         docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *       }
+ *     }
+ *   })
+ *
+ *   const results = await store.query("how does auth work?")
+ *   store.close()
+ */
+import { type Store as InternalStore, type DocumentResult, type DocumentNotFound, type SearchResult, type HybridQueryResult, type HybridQueryOptions, type HybridQueryExplain, type StructuredSubSearch, type StructuredSearchOptions, type MultiGetResult, type IndexStatus, type IndexHealthInfo, type ExpandedQuery, type SearchHooks } from "./store.js";
+import { type Collection, type CollectionConfig, type NamedCollection, type ContextMap } from "./collections.js";
+export type { DocumentResult, DocumentNotFound, SearchResult, HybridQueryResult, HybridQueryOptions, HybridQueryExplain, StructuredSubSearch, StructuredSearchOptions, MultiGetResult, IndexStatus, IndexHealthInfo, ExpandedQuery, SearchHooks, Collection, CollectionConfig, NamedCollection, ContextMap, };
+/**
+ * Options for creating a QMD store.
+ * You must provide `dbPath` and either `configPath` (YAML file) or `config` (inline).
+ */
+export interface StoreOptions {
+    /** Path to the SQLite database file */
+    dbPath: string;
+    /** Path to a YAML config file (mutually exclusive with `config`) */
+    configPath?: string;
+    /** Inline collection config (mutually exclusive with `configPath`) */
+    config?: CollectionConfig;
+}
+/**
+ * The QMD SDK store — provides search, retrieval, collection management,
+ * context management, and indexing operations.
+ */
+export interface QMDStore {
+    /** The underlying internal store (for advanced use) */
+    readonly internal: InternalStore;
+    /** Path to the SQLite database */
+    readonly dbPath: string;
+    /** Hybrid search: BM25 + vector + query expansion + LLM reranking */
+    query(query: string, options?: HybridQueryOptions): Promise<HybridQueryResult[]>;
+    /** BM25 full-text keyword search (fast, no LLM) */
+    search(query: string, options?: {
+        limit?: number;
+        collection?: string;
+    }): SearchResult[];
+    /** Structured search with pre-expanded queries (for LLM callers) */
+    structuredSearch(searches: StructuredSubSearch[], options?: StructuredSearchOptions): Promise<HybridQueryResult[]>;
+    /** Get a single document by path or docid */
+    get(pathOrDocid: string, options?: {
+        includeBody?: boolean;
+    }): DocumentResult | DocumentNotFound;
+    /** Get multiple documents by glob pattern or comma-separated list */
+    multiGet(pattern: string, options?: {
+        includeBody?: boolean;
+        maxBytes?: number;
+    }): {
+        docs: MultiGetResult[];
+        errors: string[];
+    };
+    /** Add or update a collection */
+    addCollection(name: string, opts: {
+        path: string;
+        pattern?: string;
+        ignore?: string[];
+    }): void;
+    /** Remove a collection */
+    removeCollection(name: string): boolean;
+    /** Rename a collection */
+    renameCollection(oldName: string, newName: string): boolean;
+    /** List all collections with document stats */
+    listCollections(): {
+        name: string;
+        pwd: string;
+        glob_pattern: string;
+        doc_count: number;
+        active_count: number;
+        last_modified: string | null;
+    }[];
+    /** Add context for a path within a collection */
+    addContext(collectionName: string, pathPrefix: string, contextText: string): boolean;
+    /** Remove context from a collection path */
+    removeContext(collectionName: string, pathPrefix: string): boolean;
+    /** Set global context (applies to all collections) */
+    setGlobalContext(context: string | undefined): void;
+    /** Get global context */
+    getGlobalContext(): string | undefined;
+    /** List all contexts across all collections */
+    listContexts(): Array<{
+        collection: string;
+        path: string;
+        context: string;
+    }>;
+    /** Get index status (document counts, collections, embedding state) */
+    getStatus(): IndexStatus;
+    /** Get index health info (stale embeddings, etc.) */
+    getIndexHealth(): IndexHealthInfo;
+    /** Close the database connection */
+    close(): void;
+}
+/**
+ * Create a QMD store for programmatic access to search and indexing.
+ *
+ * @example
+ * ```typescript
+ * // With a YAML config file
+ * const store = createStore({
+ *   dbPath: './index.sqlite',
+ *   configPath: './qmd.yml',
+ * })
+ *
+ * // With inline config (no files needed besides the DB)
+ * const store = createStore({
+ *   dbPath: './index.sqlite',
+ *   config: {
+ *     collections: {
+ *       docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *     }
+ *   }
+ * })
+ *
+ * const results = await store.query("authentication flow")
+ * store.close()
+ * ```
+ */
+export declare function createStore(options: StoreOptions): QMDStore;

package/dist/index.js

@@ -0,0 +1,95 @@
+/**
+ * QMD SDK - Library mode for programmatic access to QMD search and indexing.
+ *
+ * Usage:
+ *   import { createStore } from '@tobilu/qmd'
+ *
+ *   const store = createStore({
+ *     dbPath: './my-index.sqlite',
+ *     config: {
+ *       collections: {
+ *         docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *       }
+ *     }
+ *   })
+ *
+ *   const results = await store.query("how does auth work?")
+ *   store.close()
+ */
+import { createStore as createStoreInternal, hybridQuery, structuredSearch, listCollections as storeListCollections, } from "./store.js";
+import { setConfigSource, loadConfig, addCollection as collectionsAddCollection, removeCollection as collectionsRemoveCollection, renameCollection as collectionsRenameCollection, listCollections as collectionsListCollections, addContext as collectionsAddContext, removeContext as collectionsRemoveContext, setGlobalContext as collectionsSetGlobalContext, getGlobalContext as collectionsGetGlobalContext, listAllContexts as collectionsListAllContexts, } from "./collections.js";
+/**
+ * Create a QMD store for programmatic access to search and indexing.
+ *
+ * @example
+ * ```typescript
+ * // With a YAML config file
+ * const store = createStore({
+ *   dbPath: './index.sqlite',
+ *   configPath: './qmd.yml',
+ * })
+ *
+ * // With inline config (no files needed besides the DB)
+ * const store = createStore({
+ *   dbPath: './index.sqlite',
+ *   config: {
+ *     collections: {
+ *       docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *     }
+ *   }
+ * })
+ *
+ * const results = await store.query("authentication flow")
+ * store.close()
+ * ```
+ */
+export function createStore(options) {
+    if (!options.dbPath) {
+        throw new Error("dbPath is required");
+    }
+    if (!options.configPath && !options.config) {
+        throw new Error("Either configPath or config is required");
+    }
+    if (options.configPath && options.config) {
+        throw new Error("Provide either configPath or config, not both");
+    }
+    // Inject config source into collections module
+    setConfigSource({
+        configPath: options.configPath,
+        config: options.config,
+    });
+    // Create the internal store
+    const internal = createStoreInternal(options.dbPath);
+    const store = {
+        internal,
+        dbPath: internal.dbPath,
+        // Search & Retrieval
+        query: (q, opts) => hybridQuery(internal, q, opts),
+        search: (q, opts) => internal.searchFTS(q, opts?.limit, opts?.collection),
+        structuredSearch: (searches, opts) => structuredSearch(internal, searches, opts),
+        get: (pathOrDocid, opts) => internal.findDocument(pathOrDocid, opts),
+        multiGet: (pattern, opts) => internal.findDocuments(pattern, opts),
+        // Collection Management
+        addCollection: (name, opts) => {
+            collectionsAddCollection(name, opts.path, opts.pattern);
+        },
+        removeCollection: (name) => collectionsRemoveCollection(name),
+        renameCollection: (oldName, newName) => collectionsRenameCollection(oldName, newName),
+        listCollections: () => storeListCollections(internal.db),
+        // Context Management
+        addContext: (collectionName, pathPrefix, contextText) => collectionsAddContext(collectionName, pathPrefix, contextText),
+        removeContext: (collectionName, pathPrefix) => collectionsRemoveContext(collectionName, pathPrefix),
+        setGlobalContext: (context) => collectionsSetGlobalContext(context),
+        getGlobalContext: () => collectionsGetGlobalContext(),
+        listContexts: () => collectionsListAllContexts(),
+        // Index Health
+        getStatus: () => internal.getStatus(),
+        getIndexHealth: () => internal.getIndexHealth(),
+        // Lifecycle
+        close: () => {
+            internal.close();
+            setConfigSource(undefined); // Reset config source
+        },
+    };
+    return store;
+}

package/dist/llm.d.ts

@@ -330,6 +330,7 @@ export declare class LlamaCpp implements LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        intent?: string;
     }): Promise<Queryable[]>;
     private static readonly RERANK_TEMPLATE_OVERHEAD;
     private static readonly RERANK_TARGET_DOCS_PER_CONTEXT;

package/dist/llm.js

@@ -691,7 +691,10 @@ export class LlamaCpp {
         content ::= [^\\n]+
       `
         });
-        const prompt = `/no_think Expand this search query: ${query}`;
+        const intent = options.intent;
+        const prompt = intent
+            ? `/no_think Expand this search query: ${query}\nQuery intent: ${intent}`
+            : `/no_think Expand this search query: ${query}`;
         // Create a bounded context for expansion to prevent large default VRAM allocations.
         const genContext = await this.generateModel.createContext({
             contextSize: this.expandContextSize,

package/dist/mcp.js

@@ -84,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:");
@@ -236,8 +239,9 @@ Intent-aware lex (C++ performance, not sports):
             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, candidateLimit, collections }) => {
+    }, async ({ searches, limit, minScore, candidateLimit, collections, intent }) => {
         // Map to internal format
         const subSearches = searches.map(s => ({
             type: s.type,
@@ -250,13 +254,14 @@ Intent-aware lex (C++ performance, not sports):
             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,

package/dist/qmd.js

@@ -1567,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);
@@ -1600,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);
@@ -1659,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);
             }
@@ -1673,7 +1673,7 @@ function outputResults(results, query, opts) {
             const titleAttr = row.title ? ` title="${row.title.replace(/"/g, '"')}"` : "";
             const contextAttr = row.context ? ` context="${row.context.replace(/"/g, '"')}"` : "";
             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);
             }
@@ -1684,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);
@@ -1727,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,
@@ -1752,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) {
@@ -1764,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();
@@ -1781,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();
@@ -1840,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);
@@ -1877,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, ' ');
@@ -1899,6 +1909,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
                 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}`);
@@ -1925,6 +1936,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
                 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`);
@@ -1967,6 +1979,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
             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;
@@ -2026,6 +2039,7 @@ function parseCLI() {
             "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" },
@@ -2066,6 +2080,7 @@ function parseCLI() {
         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] || "",
@@ -2124,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 ;`,

package/dist/store.d.ts

@@ -202,11 +202,11 @@ export type Store = {
     toVirtualPath: (absolutePath: string) => string | null;
     searchFTS: (query: string, limit?: number, collectionName?: string) => SearchResult[];
     searchVec: (query: string, model: string, limit?: number, collectionName?: string, session?: ILLMSession, precomputedEmbedding?: number[]) => Promise<SearchResult[]>;
-    expandQuery: (query: string, model?: string) => Promise<ExpandedQuery[]>;
+    expandQuery: (query: string, model?: string, intent?: string) => Promise<ExpandedQuery[]>;
     rerank: (query: string, documents: {
         file: string;
         text: string;
-    }[], model?: string) => Promise<{
+    }[], model?: string, intent?: string) => Promise<{
         file: string;
         score: number;
     }[]>;
@@ -598,11 +598,11 @@ export declare function clearAllEmbeddings(db: Database): void;
  * The hash_seq key is formatted as "hash_seq" for the vectors_vec table.
  */
 export declare function insertEmbedding(db: Database, hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string): void;
-export declare function expandQuery(query: string, model: string | undefined, db: Database): Promise<ExpandedQuery[]>;
+export declare function expandQuery(query: string, model: string | undefined, db: Database, intent?: string): Promise<ExpandedQuery[]>;
 export declare function rerank(query: string, documents: {
     file: string;
     text: string;
-}[], model: string | undefined, db: Database): Promise<{
+}[], model: string | undefined, db: Database, intent?: string): Promise<{
     file: string;
     score: number;
 }[]>;
@@ -650,7 +650,17 @@ export type SnippetResult = {
     linesAfter: number;
     snippetLines: number;
 };
-export declare function extractSnippet(body: string, query: string, maxLen?: number, chunkPos?: number, chunkLen?: number): SnippetResult;
+/** Weight for intent terms relative to query terms (1.0) in snippet scoring */
+export declare const INTENT_WEIGHT_SNIPPET = 0.3;
+/** Weight for intent terms relative to query terms (1.0) in chunk selection */
+export declare const INTENT_WEIGHT_CHUNK = 0.5;
+/**
+ * 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 declare function extractIntentTerms(intent: string): string[];
+export declare function extractSnippet(body: string, query: string, maxLen?: number, chunkPos?: number, chunkLen?: number, intent?: string): SnippetResult;
 /**
  * Add line numbers to text content.
  * Each line becomes: "{lineNum}: {content}"
@@ -682,6 +692,7 @@ export interface HybridQueryOptions {
     minScore?: number;
     candidateLimit?: number;
     explain?: boolean;
+    intent?: string;
     hooks?: SearchHooks;
 }
 export interface HybridQueryResult {
@@ -719,6 +730,7 @@ export interface VectorSearchOptions {
     collection?: string;
     limit?: number;
     minScore?: number;
+    intent?: string;
     hooks?: Pick<SearchHooks, 'onExpand'>;
 }
 export interface VectorSearchResult {
@@ -758,7 +770,7 @@ export interface StructuredSearchOptions {
     minScore?: number;
     candidateLimit?: number;
     explain?: boolean;
-    /** Future: domain intent hint for routing/boosting */
+    /** Domain intent hint for disambiguation — steers reranking and chunk selection */
     intent?: string;
     hooks?: SearchHooks;
 }

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),
@@ -1798,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 {
@@ -1812,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
@@ -1826,7 +1826,9 @@ 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 uncachedDocsByChunk = new Map();
     // Check cache for each document
@@ -1835,7 +1837,7 @@ export async function rerank(query, documents, model = DEFAULT_RERANK_MODEL, db)
     // 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, model, chunk: doc.text });
+        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) {
@@ -1849,12 +1851,12 @@ export async function rerank(query, documents, model = DEFAULT_RERANK_MODEL, db)
     if (uncachedDocsByChunk.size > 0) {
         const llm = getDefaultLlamaCpp();
         const uncachedDocs = [...uncachedDocsByChunk.values()];
-        const rerankResult = await llm.rerank(query, uncachedDocs, { model });
+        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 chunk = textByFile.get(result.file) || "";
-            const cacheKey = getCacheKey("rerank", { query, model, chunk });
+            const cacheKey = getCacheKey("rerank", { query: rerankQuery, model, chunk });
             setCachedResult(db, cacheKey, result.score.toString());
             cachedResults.set(chunk, result.score);
         }
@@ -2254,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;
@@ -2271,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;
@@ -2291,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) + "...";
@@ -2340,17 +2381,21 @@ export async function hybridQuery(store, query, options) {
     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)
@@ -2360,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) {
@@ -2440,6 +2485,7 @@ export async function hybridQuery(store, query, options) {
     // 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) {
@@ -2447,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;
@@ -2463,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
@@ -2541,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
@@ -2597,6 +2649,7 @@ export async function structuredSearch(store, searches, options) {
     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)
@@ -2696,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) {
@@ -2703,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;
@@ -2719,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, {

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@tobilu/qmd",
-  "version": "1.1.2",
+  "version": "1.1.6",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "bin": {
     "qmd": "dist/qmd.js"
   },