@wei840222/qmd 2026.8.24 → 2026.8.28

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- **Disable HyDE Expansion Control**: Added `--no-hyde` CLI option for `qmd query` and `qmd vsearch`, `includeHyde` parameter to SDK (`store.search`, `store.expandQuery`) and MCP `query` tool, allowing users to disable generating hypothetical document embeddings during query expansion.
+
 ## [2026.8.23-1] - 2026-08-23
 
 ### Added

package/README.md

@@ -982,6 +982,7 @@ and `deep-search` (→ `query`).
 --index <name>     # Use named index
 --intent "<text>"  # Legacy CLI alias for rerank context (e.g. "web page load times")
 --no-rerank        # Skip LLM reranking (RRF scores only; faster on CPU)
+--no-hyde          # Disable HyDE in query expansion (only lex and vec expansions)
 -C, --candidate-limit <n>  # Max candidates to rerank (default: 40)
 --full-path        # Emit on-disk filesystem paths instead of qmd:// URIs
                    # (a result whose file has moved or been deleted since

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "1e728bc",
-  "builtAt": "2026-08-23T06:13:30.733Z"
+  "commit": "7cbc570",
+  "builtAt": "2026-08-28T11:16:06.495Z"
 }

package/dist/cli/qmd.js

@@ -2674,6 +2674,7 @@ async function vectorSearch(query, opts, _model = DEFAULT_EMBED_MODEL) {
             limit: opts.all ? 500 : (opts.limit || 10),
             minScore: opts.minScore || 0.3,
             expansionContext: opts.intent,
+            includeHyde: opts.includeHyde,
             hooks: {
                 onExpand: (original, expanded) => {
                     logExpansionTree(original, expanded);
@@ -2766,6 +2767,7 @@ async function querySearch(query, opts, _embedModel = DEFAULT_EMBED_MODEL, _rera
                 explain: !!opts.explain,
                 rerankContext: intent,
                 expansion: opts.expansion,
+                includeHyde: opts.includeHyde,
                 chunkStrategy: opts.chunkStrategy,
                 hooks: {
                     onExpansionDecision: (decision) => {
@@ -2884,6 +2886,7 @@ function parseCLI() {
             // Query options
             "candidate-limit": { type: "string", short: "C" },
             "no-rerank": { type: "boolean", default: false },
+            "no-hyde": { type: "boolean", default: false },
             expand: { type: "boolean", default: false },
             "no-gpu": { type: "boolean", default: false },
             intent: { type: "string" },
@@ -2960,6 +2963,7 @@ function parseCLI() {
         lineNumbers: !!values["line-numbers"],
         candidateLimit: values["candidate-limit"] ? parseInt(String(values["candidate-limit"]), 10) : undefined,
         skipRerank: !!values["no-rerank"],
+        includeHyde: !values["no-hyde"],
         explain: !!values.explain,
         intent: values.intent,
         expansion: values.expand ? "force" : "auto",
@@ -3459,6 +3463,7 @@ function showHelp() {
     console.log("  --chunk-strategy <auto|regex> - Chunking mode (default: regex; auto uses AST for code files)");
     console.log("  --timeout <minutes>          - Embed session cap in minutes (0 = no limit; default 30)");
     console.log("  --expand                    - Force query expansion (auto is the default; lex: skips)");
+    console.log("  --no-hyde                   - Disable HyDE (hypothetical document) in query expansion");
     console.log("");
     console.log("Embedding providers & disclosure:");
     console.log("  - Local embedding is the default. OpenAI requires explicit provider configuration and OPENAI_API_KEY.");

package/dist/hybrid-llm.d.ts

@@ -12,6 +12,7 @@ export declare class HybridLLM implements LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
     }): Promise<Queryable[]>;
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult>;
     dispose(): Promise<void>;

package/dist/index.d.ts

@@ -75,6 +75,8 @@ export interface SearchOptions {
     explain?: boolean;
     /** Query expansion policy (default: auto) */
     expansion?: ExpansionMode;
+    /** Whether to include HyDE (hypothetical document) in query expansion (default: true) */
+    includeHyde?: boolean;
     /** Optional progress/decision hooks for search orchestration */
     hooks?: SearchHooks;
     /** Chunk strategy: "auto" (default, uses AST for code files) or "regex" (legacy) */
@@ -100,6 +102,10 @@ export interface VectorSearchOptions {
 export interface ExpandQueryOptions {
     /** Additional context used only while generating query expansions. */
     expansionContext?: string;
+    /** Whether to include lexical (BM25) sub-queries (default: true) */
+    includeLexical?: boolean;
+    /** Whether to include HyDE (hypothetical document) sub-queries (default: true) */
+    includeHyde?: boolean;
 }
 /**
  * Options for creating a QMD store.

package/dist/index.js

@@ -231,6 +231,7 @@ export async function createStore(options) {
                 expansionContext: opts.expansionContext,
                 rerankContext: opts.rerankContext,
                 expansion: opts.expansion,
+                includeHyde: opts.includeHyde,
                 hooks: opts.hooks,
                 candidateLimit: opts.candidateLimit,
                 skipRerank,
@@ -242,7 +243,10 @@ export async function createStore(options) {
             const provider = internal.embeddingProvider;
             return internal.searchVec(q, provider?.model ?? internal.llm?.embedModelName ?? DEFAULT_EMBED_MODEL_URI, opts?.limit, opts?.collection);
         },
-        expandQuery: async (q, opts) => internal.expandQuery(q, undefined, opts?.expansionContext),
+        expandQuery: async (q, opts) => internal.expandQuery(q, undefined, opts?.expansionContext, {
+            includeLexical: opts?.includeLexical,
+            includeHyde: opts?.includeHyde,
+        }),
         get: async (pathOrDocid, opts) => internal.findDocument(pathOrDocid, opts),
         getDocumentBody: async (pathOrDocid, opts) => {
             const result = internal.findDocument(pathOrDocid, { includeBody: false });

package/dist/llm.d.ts

@@ -137,6 +137,7 @@ export interface ILLMSession {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
     }): Promise<Queryable[]>;
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions): Promise<RerankResult>;
     /** Whether this session is still valid (not released or aborted) */
@@ -236,6 +237,7 @@ export interface LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
     }): Promise<Queryable[]>;
     /**
      * Rerank documents by relevance to a query
@@ -465,6 +467,7 @@ export declare class LlamaCpp implements LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
     }): Promise<Queryable[]>;
     private static readonly RERANK_TEMPLATE_OVERHEAD;
     private static readonly RERANK_TARGET_DOCS_PER_CONTEXT;

package/dist/llm.js

@@ -1245,6 +1245,7 @@ export class LlamaCpp {
         const llama = await this.ensureLlama();
         await this.ensureGenerateModel();
         const includeLexical = options.includeLexical ?? true;
+        const includeHyde = options.includeHyde ?? true;
         const context = options.context;
         // Keep the caller-provided expansion context separate from the query. It
         // may clarify ambiguous terms, but it is untrusted data rather than an
@@ -1259,11 +1260,18 @@ export class LlamaCpp {
         let genContext;
         let sequence;
         try {
+            const allowedTypes = [];
+            if (includeLexical)
+                allowedTypes.push('"lex"');
+            allowedTypes.push('"vec"');
+            if (includeHyde)
+                allowedTypes.push('"hyde"');
+            const typeRule = allowedTypes.join(' | ');
             const grammar = await llama.createGrammar({
                 grammar: `
         root ::= line+
         line ::= type ": " content "\\n"
-        type ::= "lex" | "vec" | "hyde"
+        type ::= ${typeRule}
         content ::= [^\\n]+
       `
             });
@@ -1304,21 +1312,27 @@ export class LlamaCpp {
                 const type = line.slice(0, colonIdx).trim();
                 if (type !== 'lex' && type !== 'vec' && type !== 'hyde')
                     return null;
+                if (type === 'lex' && !includeLexical)
+                    return null;
+                if (type === 'hyde' && !includeHyde)
+                    return null;
                 const text = line.slice(colonIdx + 1).trim();
                 if (!hasQueryTerm(text))
                     return null;
                 return { type: type, text };
             }).filter((q) => q !== null);
-            // Filter out lex entries if not requested
-            const filtered = includeLexical ? queryables : queryables.filter(q => q.type !== 'lex');
+            // Filter out unwanted types if any slipped through
+            const filtered = queryables
+                .filter(q => (includeLexical || q.type !== 'lex'))
+                .filter(q => (includeHyde || q.type !== 'hyde'));
             if (filtered.length > 0)
                 return filtered;
             const fallback = [
-                { type: 'hyde', text: `Information about ${query}` },
-                { type: 'lex', text: query },
+                ...(includeHyde ? [{ type: 'hyde', text: `Information about ${query}` }] : []),
+                ...(includeLexical ? [{ type: 'lex', text: query }] : []),
                 { type: 'vec', text: query },
             ];
-            return includeLexical ? fallback : fallback.filter(q => q.type !== 'lex');
+            return fallback;
         }
         catch (error) {
             console.error("Structured query expansion failed:", error);

package/dist/mcp/server.js

@@ -255,8 +255,9 @@ Context-aware lex (C++ performance, not sports):
             rerankContext: z.string().optional().describe("Additional context used only to rerank results and select snippets/chunks."),
             rerank: z.boolean().optional().default(true).describe("Rerank results using LLM (default: true). Set to false for faster results on CPU-only machines."),
             explain: z.boolean().optional().default(false).describe("Include retrieval traces and the shared query-expansion decision or typed expansion error"),
+            includeHyde: z.boolean().optional().default(true).describe("Whether to include HyDE (hypothetical document) in query expansion (default: true)"),
         }),
-    }, track(async ({ query, searches, expansion, limit, minScore, candidateLimit, collections, expansionContext, rerankContext, rerank, explain }) => {
+    }, track(async ({ query, searches, expansion, includeHyde, limit, minScore, candidateLimit, collections, expansionContext, rerankContext, rerank, explain }) => {
         // Require exactly one of `query` (plain text with an expansion policy) or `searches` (typed sub-queries).
         if (!query && (!searches || searches.length === 0)) {
             return {
@@ -292,6 +293,7 @@ Context-aware lex (C++ performance, not sports):
                 rerankContext,
                 explain,
                 expansion: query ? expansion : undefined,
+                includeHyde,
                 hooks: explain && query ? {
                     onExpansionDecision: decision => { expansionDecision = decision; },
                     onExpansionError: event => { expansionError = event; },

package/dist/remote-llm.d.ts

@@ -38,6 +38,7 @@ export declare class RemoteLLM implements LLM {
     expandQuery(query: string, options?: {
         context?: string;
         includeLexical?: boolean;
+        includeHyde?: boolean;
         timeZone?: string;
     }): Promise<Queryable[]>;
     rerank(query: string, documents: RerankDocument[], options?: RerankOptions | string | (RerankOptions & {

package/dist/remote-llm.js

@@ -127,18 +127,29 @@ export class RemoteLLM {
             throw new Error("Remote expansion is not configured or circuit is broken.");
         }
         const includeLexical = options?.includeLexical !== false;
+        const includeHyde = options?.includeHyde !== false;
         const lexicalOutput = includeLexical ? "lex: keyword-focused search phrase\n" : "";
         const lexicalRule = includeLexical
             ? "- lex: preserve precise terms and add only useful synonyms or related keywords; do not write a complete question.\n"
             : "";
         const lexicalExample = includeLexical ? "lex: database connection pool timeout exhaustion\n" : "";
+        const hydeOutput = includeHyde ? "hyde: concise hypothetical answer-style passage\n" : "";
+        const hydeRule = includeHyde
+            ? "- hyde: write a concise hypothetical passage describing plausible answer content, describing general concepts without inventing specific fake facts.\n"
+            : "";
+        const hydeExample = includeHyde ? "hyde: Database connection pool timeout troubleshooting may examine pool limits, active connections, query latency, and connection handling.\n" : "";
+        const requestedBackends = [
+            includeLexical ? "lex" : null,
+            "vec",
+            includeHyde ? "hyde" : null,
+        ].filter(Boolean).join(", ");
         const systemPrompt = `<role>
 You are a specialized assistant for hybrid document-search query expansion.
 You expand search queries to enhance retrieval recall with analytical precision while preserving user intent and constraints.
 </role>
 
 <instructions>
-1. Proactively generate one high-quality variation for each requested backend (lex, vec, hyde) whenever the query has clear intent.
+1. Proactively generate one high-quality variation for each requested backend (${requestedBackends}) whenever the query has clear intent.
 2. Preserve query constraints and avoid inventing unmentioned facts.
 3. Return only the requested prefix lines.
 </instructions>
@@ -150,15 +161,13 @@ You expand search queries to enhance retrieval recall with analytical precision
 - Keep the query's primary language and script, while preserving exact identifiers, product names, API names, abbreviations, and established domain terms from the query or context.
 ${lexicalRule}- vec: state the search intent as a clear natural-language phrase or question.
 - For space-separated or keyword-list queries, synthesize the scattered terms into a coherent, natural-language phrase or question for vec.
-- hyde: write a concise hypothetical passage describing plausible answer content, describing general concepts without inventing specific fake facts.
-- For very short or identifier-only queries, retain exact terms without inventing unprovided constraints.
+${hydeRule}- For very short or identifier-only queries, retain exact terms without inventing unprovided constraints.
 </constraints>
 
 <output_format>
 Output only prefix lines. Do not include preambles, explanations, markdown, or code fences.
 ${lexicalOutput}vec: natural-language semantic search phrase or question
-hyde: concise hypothetical answer-style passage
-Generate at most one line of each listed type.
+${hydeOutput}Generate at most one line of each listed type.
 </output_format>
 
 <example>
@@ -173,8 +182,7 @@ database pool timeout
 </task>
 
 ${lexicalExample}vec: Why is the database connection pool timing out under load?
-hyde: Database connection pool timeout troubleshooting may examine pool limits, active connections, query latency, and connection handling.
-</example>`;
+${hydeExample}</example>`;
         const currentTime = getFormattedLocalTime(new Date(), options?.timeZone ?? this.timeZone);
         const additionalContext = options?.context
             ? `Additional context:\n${escapePromptXml(options.context)}`
@@ -224,7 +232,11 @@ Return only the prefix lines specified in the output format.
                 const match = /^(lex|vec|hyde)\s*:\s*(.+)$/i.exec(line.trim());
                 if (match && match[1] && match[2]) {
                     const type = match[1].toLowerCase();
-                    if ((type !== "lex" || options?.includeLexical !== false) && !seenTypes.has(type)) {
+                    if (type === "lex" && !includeLexical)
+                        continue;
+                    if (type === "hyde" && !includeHyde)
+                        continue;
+                    if (!seenTypes.has(type)) {
                         seenTypes.add(type);
                         results.push({ type, text: match[2].trim() });
                     }

package/dist/store.d.ts

@@ -132,6 +132,8 @@ export type ExpandedQuery = {
 };
 export type QueryExpansionOptions = {
     requireResult?: boolean;
+    includeLexical?: boolean;
+    includeHyde?: boolean;
 };
 export declare function homedir(): string;
 /**
@@ -313,7 +315,7 @@ export type Store = {
     searchVec: (query: string, model: string, limit?: number, collectionFilter?: CollectionFilter, session?: ILLMSession, precomputedEmbedding?: number[]) => Promise<SearchResult[]>;
     expandQuery: (query: string, model?: string, expansionContext?: string, options?: QueryExpansionOptions) => Promise<ExpandedQuery[]>;
     /** Drop the cached expansion for a query so the next call regenerates. */
-    invalidateExpansionCache: (query: string, expansionContext?: string) => void;
+    invalidateExpansionCache: (query: string, expansionContext?: string, options?: QueryExpansionOptions) => void;
     rerank: (query: string, documents: {
         file: string;
         text: string;
@@ -634,6 +636,8 @@ export type CacheKeyBody = {
     chunk?: string;
     file?: string;
     expansionContext?: string;
+    noHyde?: boolean;
+    noLex?: boolean;
 };
 export declare function getCacheKey(url: string, body: CacheKeyBody): string;
 export declare function getCachedResult(db: Database, cacheKey: string): string | null;
@@ -968,7 +972,10 @@ export declare function expandQuery(query: string, model: string | undefined, db
  * expansion's sub-queries all came back empty — left in place, the dud entry
  * would replay the same misses on every warm repeat of the query.
  */
-export declare function deleteExpansionCacheEntry(db: Database, query: string, model?: string, expansionContext?: string): void;
+export declare function deleteExpansionCacheEntry(db: Database, query: string, model?: string, expansionContext?: string, options?: {
+    includeLexical?: boolean;
+    includeHyde?: boolean;
+}): void;
 export declare function rerank(query: string, documents: {
     file: string;
     text: string;
@@ -1106,6 +1113,7 @@ export interface HybridQueryOptions {
     /** Additional context used for reranking and snippet/chunk selection. */
     rerankContext?: string;
     expansion?: ExpansionMode;
+    includeHyde?: boolean;
     skipRerank?: boolean;
     chunkStrategy?: ChunkStrategy;
     hooks?: SearchHooks;
@@ -1159,6 +1167,8 @@ export interface VectorSearchOptions {
     minScore?: number;
     /** Additional context used only while generating query expansions. */
     expansionContext?: string;
+    /** Whether to include HyDE (hypothetical document) in query expansion (default: true) */
+    includeHyde?: boolean;
     hooks?: Pick<SearchHooks, 'onExpand'>;
 }
 export interface VectorSearchResult {

package/dist/store.js

@@ -2690,7 +2690,7 @@ export function createStore(dbPath, options = {}) {
         searchVec: (query, model, limit, collectionFilter, session, precomputedEmbedding) => searchVec(db, query, model, limit, collectionFilter, session, precomputedEmbedding, store.embeddingProvider, store.authorizeRemoteRequest, store.llm),
         // Query expansion & reranking
         expandQuery: (query, model, expansionContext, options) => expandQuery(query, model ?? store.localLlm?.generateModelName ?? store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL, db, expansionContext, store.llm, options),
-        invalidateExpansionCache: (query, expansionContext) => deleteExpansionCacheEntry(db, query, store.localLlm?.generateModelName ?? store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL, expansionContext),
+        invalidateExpansionCache: (query, expansionContext, options) => deleteExpansionCacheEntry(db, query, store.localLlm?.generateModelName ?? store.llm?.generateModelName ?? DEFAULT_QUERY_MODEL, expansionContext, options),
         rerank: (query, documents, model, rerankContext) => {
             const llm = getLlm(store);
             return rerank(query, documents, model ?? store.localLlm?.rerankModelName ?? llm?.rerankModelName ?? DEFAULT_RERANK_MODEL, db, rerankContext, store.llm ?? llm);
@@ -4670,8 +4670,16 @@ export function insertEmbedding(db, hash, seq, pos, embedding, model, embeddedAt
 // Query expansion
 // =============================================================================
 export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, expansionContext, llmOverride, options) {
+    const includeLexical = options?.includeLexical ?? true;
+    const includeHyde = options?.includeHyde ?? true;
     // Check cache first — stored as JSON preserving types
-    const cacheKey = getCacheKey("expandQuery", { query, model, ...(expansionContext && { expansionContext }) });
+    const cacheKey = getCacheKey("expandQuery", {
+        query,
+        model,
+        ...(expansionContext && { expansionContext }),
+        ...(!includeHyde && { noHyde: true }),
+        ...(!includeLexical && { noLex: true }),
+    });
     const cached = getCachedResult(db, cacheKey);
     if (cached) {
         try {
@@ -4693,7 +4701,11 @@ export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, expans
     }
     const llm = llmOverride ?? getDefaultLlamaCpp();
     // Note: LlamaCpp uses hardcoded model, model parameter is ignored
-    const results = await llm.expandQuery(query, { context: expansionContext });
+    const results = await llm.expandQuery(query, {
+        context: expansionContext,
+        includeLexical,
+        includeHyde,
+    });
     // Map Queryable[] → ExpandedQuery[] (same shape, decoupled from llm.ts internals).
     // Filter out entries that duplicate the original query text.
     const expanded = results
@@ -4712,8 +4724,14 @@ export async function expandQuery(query, model = DEFAULT_QUERY_MODEL, db, expans
  * expansion's sub-queries all came back empty — left in place, the dud entry
  * would replay the same misses on every warm repeat of the query.
  */
-export function deleteExpansionCacheEntry(db, query, model = DEFAULT_QUERY_MODEL, expansionContext) {
-    const cacheKey = getCacheKey("expandQuery", { query, model, ...(expansionContext && { expansionContext }) });
+export function deleteExpansionCacheEntry(db, query, model = DEFAULT_QUERY_MODEL, expansionContext, options) {
+    const cacheKey = getCacheKey("expandQuery", {
+        query,
+        model,
+        ...(expansionContext && { expansionContext }),
+        ...(options?.includeHyde === false && { noHyde: true }),
+        ...(options?.includeLexical === false && { noLex: true }),
+    });
     db.prepare(`DELETE FROM llm_cache WHERE hash = ?`).run(cacheKey);
 }
 // =============================================================================
@@ -5491,6 +5509,7 @@ export async function hybridQuery(store, query, options) {
     if (hasStrongSignal)
         hooks?.onStrongSignal?.(topScore);
     // Step 2: Expand query (or skip if strong signal)
+    const includeHyde = options?.includeHyde ?? true;
     if (expansionDecision.action === "expand")
         hooks?.onExpandStart?.();
     const expandStart = Date.now();
@@ -5500,6 +5519,7 @@ export async function hybridQuery(store, query, options) {
             ? []
             : await store.expandQuery(query, undefined, expansionContext, {
                 requireResult: expansionDecision.reason === "explicit-force",
+                includeHyde,
             });
     }
     catch (error) {
@@ -5590,7 +5610,7 @@ export async function hybridQuery(store, query, options) {
         const runnable = expanded.filter(q => q.type === "lex" || hasVectors);
         const expansionContributed = rankedListMeta.some(m => m.queryType !== "original");
         if (runnable.length > 0 && !expansionContributed) {
-            store.invalidateExpansionCache(query, expansionContext);
+            store.invalidateExpansionCache(query, expansionContext, { includeHyde });
         }
     }
     // Step 4: RRF fusion — original-query FTS and vector lists get 2x weight;
@@ -5767,11 +5787,14 @@ export async function vectorSearchQuery(store, query, options) {
     const minScore = options?.minScore ?? 0.3;
     const collection = options?.collection;
     const expansionContext = options?.expansionContext;
+    const includeHyde = options?.includeHyde ?? true;
     if (!hasSearchableVectorIndex(store))
         return [];
     // Expand query — filter to vec/hyde only (lex queries target FTS, not vector)
     const expandStart = Date.now();
-    const allExpanded = await store.expandQuery(query, undefined, expansionContext);
+    const allExpanded = await store.expandQuery(query, undefined, expansionContext, {
+        includeHyde,
+    });
     const vecExpanded = allExpanded.filter(q => q.type !== 'lex');
     options?.hooks?.onExpand?.(query, vecExpanded, Date.now() - expandStart);
     const embedModel = store.embeddingProvider?.model ?? getLlm(store).embedModelName;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wei840222/qmd",
-  "version": "2026.8.24",
+  "version": "2026.8.28",
   "packageManager": "pnpm@11.15.1",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",

package/skills/qmd/SKILL.md

@@ -230,6 +230,8 @@ Query types:
 - `vec` — vector semantic search. Best for natural-language concepts.
 - `hyde` — vector search using a hypothetical answer/document passage.
 
+When invoking `query` with a plain `query` string instead of explicit `searches`, you can set `includeHyde: false` (to omit HyDE passage generation) and `expansion: "auto" | "force" | "skip"`.
+
 ## Query craft
 
 Good QMD searches mix three things:

package/skills/qmd/references/query-syntax.md

@@ -30,6 +30,7 @@ newline        = "\n" ;
 
 A query is either a single policy query or a multi-line query document:
 - **`auto` (Default)**: CJK queries and strong lexical matches automatically bypass model expansion. Other plain queries expand into `lex`, `vec`, and `hyde` variants.
+- **`--no-hyde`**: Disables HyDE (hypothetical document) in query expansion, generating only `lex` and `vec` variants (faster, avoids hallucinated passage drift).
 - **`expand:` / `--expand` (`force`)**: Explicitly forces expansion even if bypass heuristics apply.
 - **`lex:` (`skip`)**: Explicitly disables expansion and performs direct BM25 search.
 
@@ -37,6 +38,9 @@ A query is either a single policy query or a multi-line query document:
 # Automatic policy:
 qmd query "how does authentication work"
 
+# Disable HyDE during expansion:
+qmd query --no-hyde "how does authentication work"
+
 # Force expansion:
 qmd query "expand: how does authentication work"
 # or: qmd query --expand "資料庫同步"
@@ -81,6 +85,8 @@ A 50–100 word hypothetical answer passage representing what the target documen
 hyde: The rate limiter uses a sliding window counter algorithm with a 60-second window. When a client exceeds 100 requests per minute, subsequent requests return 429 Too Many Requests.
 ```
 
+When relying on query expansion, HyDE generation can be excluded using `--no-hyde` (CLI) or `"includeHyde": false` (MCP/SDK).
+
 ## Multi-Line Structured Queries
 
 Combine multiple sub-query types for optimal retrieval. The first sub-query receives **2x weight** during Reciprocal Rank Fusion:
@@ -150,8 +156,9 @@ When calling the `qmd` MCP server's `query` tool, provide a structured `searches
 
 ```json
 {
-  "query": "CAP theorem consistency",
+  "query": "authentication flow",
   "expansion": "auto",
+  "includeHyde": false,
   "explain": true,
   "collections": ["docs"]
 }