@gmickel/gno 0.17.0 → 0.18.0

package/README.md

@@ -32,7 +32,22 @@ GNO is a local knowledge engine that turns your documents into a searchable, con
 
 ---
 
-## What's New in v0.15
+## What's New in v0.18
+
+- **Intent Steering**: optional `intent` control for ambiguous queries across CLI, API, Web, and MCP query flows
+- **Rerank Controls**: `candidateLimit` lets you tune rerank cost vs. recall on slower or memory-constrained machines
+- **Stability**: query expansion now uses a bounded configurable context size (`models.expandContextSize`, default `2048`)
+- **Rerank Efficiency**: identical chunk texts are deduplicated before scoring and expanded back out deterministically
+
+### v0.17
+
+- **Structured Query Modes**: `term`, `intent`, and `hyde` controls across CLI, API, MCP, and Web
+- **Temporal Retrieval Upgrades**: `since`/`until`, date-range parsing, and recency sorting with frontmatter-date fallback
+- **Web Retrieval UX Polish**: richer advanced controls in Search and Ask (collection/date/category/author/tags + query modes)
+- **Metadata-Aware Retrieval**: ingestion now materializes document metadata/date fields for better filtering and ranking
+- **Migration Reliability**: SQLite-compatible migration path for existing indexes (including older SQLite engines)
+
+### v0.15
 
 - **HTTP Backends**: Offload embedding, reranking, and generation to remote GPU servers
 - Simple URI config: `http://host:port/path#modelname`
@@ -146,6 +161,7 @@ gno search "handleAuth"              # Find exact matches
 gno vsearch "error handling patterns" # Semantic similarity
 gno query "database optimization"    # Full pipeline
 gno query "meeting decisions" --since "last month" --category "meeting,notes" --author "gordon"
+gno query "performance" --intent "web performance and latency"
 gno ask "what did we decide" --answer # AI synthesis
 ```
 
@@ -161,6 +177,8 @@ gno query "auth flow" --thorough
 
 # Structured retrieval intent
 gno query "auth flow" \
+  --intent "web authentication and token lifecycle" \
+  --candidate-limit 12 \
   --query-mode term:"jwt refresh token -oauth1" \
   --query-mode intent:"how refresh token rotation works" \
   --query-mode hyde:"Refresh tokens rotate on each use and previous tokens are revoked." \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmickel/gno",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "description": "Local semantic search for your documents. Index Markdown, PDF, and Office files with hybrid BM25 + vector search.",
   "keywords": [
     "embeddings",

package/src/cli/commands/ask.ts

@@ -192,6 +192,7 @@ export async function ask(
       limit,
       collection: options.collection,
       lang: options.lang,
+      intent: options.intent,
       since: options.since,
       until: options.until,
       categories: options.categories,
@@ -200,6 +201,7 @@ export async function ask(
       tagsAny: options.tagsAny,
       noExpand: options.noExpand,
       noRerank: options.noRerank,
+      candidateLimit: options.candidateLimit,
     });
 
     if (!searchResult.ok) {
@@ -258,6 +260,8 @@ export async function ask(
         expanded: searchResult.value.meta.expanded ?? false,
         reranked: searchResult.value.meta.reranked ?? false,
         vectorsUsed: searchResult.value.meta.vectorsUsed ?? false,
+        intent: searchResult.value.meta.intent,
+        candidateLimit: searchResult.value.meta.candidateLimit,
         answerGenerated,
         totalResults: results.length,
         answerContext,

package/src/cli/commands/models/use.ts

@@ -58,6 +58,7 @@ export async function modelsUse(
       presets: config.models?.presets ?? [],
       loadTimeout: config.models?.loadTimeout ?? 60_000,
       inferenceTimeout: config.models?.inferenceTimeout ?? 30_000,
+      expandContextSize: config.models?.expandContextSize ?? 2_048,
       warmModelTtl: config.models?.warmModelTtl ?? 300_000,
     },
   };

package/src/cli/program.ts

@@ -224,6 +224,7 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--category <values>", "require category match (comma-separated)")
     .option("--author <text>", "filter by author (case-insensitive contains)")
+    .option("--intent <text>", "disambiguating context for ambiguous queries")
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
     .option("--full", "include full content")
@@ -280,6 +281,7 @@ function wireSearchCommands(program: Command): void {
         until: cmdOpts.until as string | undefined,
         categories,
         author: cmdOpts.author as string | undefined,
+        intent: cmdOpts.intent as string | undefined,
         tagsAll,
         tagsAny,
         full: Boolean(cmdOpts.full),
@@ -329,6 +331,7 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--category <values>", "require category match (comma-separated)")
     .option("--author <text>", "filter by author (case-insensitive contains)")
+    .option("--intent <text>", "disambiguating context for ambiguous queries")
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
     .option("--full", "include full content")
@@ -385,6 +388,7 @@ function wireSearchCommands(program: Command): void {
         until: cmdOpts.until as string | undefined,
         categories,
         author: cmdOpts.author as string | undefined,
+        intent: cmdOpts.intent as string | undefined,
         tagsAll,
         tagsAny,
         full: Boolean(cmdOpts.full),
@@ -429,6 +433,7 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--category <values>", "require category match (comma-separated)")
     .option("--author <text>", "filter by author (case-insensitive contains)")
+    .option("--intent <text>", "disambiguating context for ambiguous queries")
     .option("--tags-all <tags>", "require ALL tags (comma-separated)")
     .option("--tags-any <tags>", "require ANY tag (comma-separated)")
     .option("--full", "include full content")
@@ -443,6 +448,7 @@ function wireSearchCommands(program: Command): void {
       (value: string, previous: string[] = []) => [...previous, value],
       []
     )
+    .option("-C, --candidate-limit <num>", "max candidates passed to reranking")
     .option("--explain", "include scoring explanation")
     .option("--json", "JSON output")
     .option("--md", "Markdown output")
@@ -495,6 +501,9 @@ function wireSearchCommands(program: Command): void {
       const limit = cmdOpts.limit
         ? parsePositiveInt("limit", cmdOpts.limit)
         : getDefaultLimit(format);
+      const candidateLimit = cmdOpts.candidateLimit
+        ? parsePositiveInt("candidate-limit", cmdOpts.candidateLimit)
+        : undefined;
       const categories = parseCsvValues(cmdOpts.category);
 
       // Determine expansion/rerank settings based on flags
@@ -531,12 +540,14 @@ function wireSearchCommands(program: Command): void {
         until: cmdOpts.until as string | undefined,
         categories,
         author: cmdOpts.author as string | undefined,
+        intent: cmdOpts.intent as string | undefined,
         tagsAll,
         tagsAny,
         full: Boolean(cmdOpts.full),
         lineNumbers: Boolean(cmdOpts.lineNumbers),
         noExpand,
         noRerank,
+        candidateLimit,
         queryModes,
         explain: Boolean(cmdOpts.explain),
         json: format === "json",
@@ -574,8 +585,10 @@ function wireSearchCommands(program: Command): void {
     )
     .option("--category <values>", "require category match (comma-separated)")
     .option("--author <text>", "filter by author (case-insensitive contains)")
+    .option("--intent <text>", "disambiguating context for ambiguous queries")
     .option("--fast", "skip expansion and reranking (fastest)")
     .option("--thorough", "enable query expansion (slower)")
+    .option("-C, --candidate-limit <num>", "max candidates passed to reranking")
     .option("--answer", "generate short grounded answer")
     .option("--no-answer", "force retrieval-only output")
     .option("--max-answer-tokens <num>", "max answer tokens")
@@ -594,6 +607,9 @@ function wireSearchCommands(program: Command): void {
       const limit = cmdOpts.limit
         ? parsePositiveInt("limit", cmdOpts.limit)
         : getDefaultLimit(format);
+      const candidateLimit = cmdOpts.candidateLimit
+        ? parsePositiveInt("candidate-limit", cmdOpts.candidateLimit)
+        : undefined;
 
       // Parse max-answer-tokens (optional, defaults to 512 in command impl)
       const maxAnswerTokens = cmdOpts.maxAnswerTokens
@@ -624,8 +640,10 @@ function wireSearchCommands(program: Command): void {
         until: cmdOpts.until as string | undefined,
         categories,
         author: cmdOpts.author as string | undefined,
+        intent: cmdOpts.intent as string | undefined,
         noExpand,
         noRerank,
+        candidateLimit,
         // Per spec: --answer defaults to false, --no-answer forces retrieval-only
         // Commander creates separate cmdOpts.noAnswer for --no-answer flag
         answer: Boolean(cmdOpts.answer),

package/src/config/types.ts

@@ -209,6 +209,8 @@ export const ModelConfigSchema = z.object({
   loadTimeout: z.number().default(60_000),
   /** Inference timeout in ms */
   inferenceTimeout: z.number().default(30_000),
+  /** Context size used for query expansion generation */
+  expandContextSize: z.number().int().min(256).default(2_048),
   /** Keep warm model TTL in ms (5 min) */
   warmModelTtl: z.number().default(300_000),
 });

package/src/llm/nodeLlamaCpp/generation.ts

@@ -56,7 +56,9 @@ export class NodeLlamaCppGeneration implements GenerationPort {
     }
 
     const llamaModel = model.value.model as LlamaModel;
-    const context = await llamaModel.createContext();
+    const context = await llamaModel.createContext(
+      params?.contextSize ? { contextSize: params.contextSize } : undefined
+    );
 
     try {
       // Import LlamaChatSession dynamically

package/src/llm/registry.ts

@@ -25,6 +25,7 @@ export function getModelConfig(config: Config): ModelConfig {
       : DEFAULT_MODEL_PRESETS,
     loadTimeout: config.models?.loadTimeout ?? 60_000,
     inferenceTimeout: config.models?.inferenceTimeout ?? 30_000,
+    expandContextSize: config.models?.expandContextSize ?? 2_048,
     warmModelTtl: config.models?.warmModelTtl ?? 300_000,
   };
 }

package/src/llm/types.ts

@@ -54,6 +54,8 @@ export interface GenParams {
   seed?: number;
   /** Max tokens to generate. Default: 256 */
   maxTokens?: number;
+  /** Optional context size override for the generation context */
+  contextSize?: number;
   /** Stop sequences */
   stop?: string[];
 }

package/src/mcp/tools/index.ts

@@ -56,6 +56,7 @@ const searchInputSchema = z.object({
   limit: z.number().int().min(1).max(100).default(5),
   minScore: z.number().min(0).max(1).optional(),
   lang: z.string().optional(),
+  intent: z.string().optional(),
   since: z.string().optional(),
   until: z.string().optional(),
   categories: z.array(z.string()).optional(),
@@ -105,6 +106,7 @@ const vsearchInputSchema = z.object({
   limit: z.number().int().min(1).max(100).default(5),
   minScore: z.number().min(0).max(1).optional(),
   lang: z.string().optional(),
+  intent: z.string().optional(),
   since: z.string().optional(),
   until: z.string().optional(),
   categories: z.array(z.string()).optional(),
@@ -124,6 +126,8 @@ export const queryInputSchema = z.object({
   limit: z.number().int().min(1).max(100).default(5),
   minScore: z.number().min(0).max(1).optional(),
   lang: z.string().optional(),
+  intent: z.string().optional(),
+  candidateLimit: z.number().int().min(1).max(100).optional(),
   since: z.string().optional(),
   until: z.string().optional(),
   categories: z.array(z.string()).optional(),

package/src/mcp/tools/query.ts

@@ -36,6 +36,8 @@ interface QueryInput {
   limit?: number;
   minScore?: number;
   lang?: string;
+  intent?: string;
+  candidateLimit?: number;
   since?: string;
   until?: string;
   categories?: string[];
@@ -247,6 +249,8 @@ export function handleQuery(
           minScore: args.minScore,
           collection: args.collection,
           queryLanguageHint: args.lang, // Affects expansion prompt, not retrieval
+          intent: args.intent,
+          candidateLimit: args.candidateLimit,
           since: args.since,
           until: args.until,
           categories: args.categories,

package/src/mcp/tools/search.ts

@@ -19,6 +19,7 @@ interface SearchInput {
   limit?: number;
   minScore?: number;
   lang?: string;
+  intent?: string;
   since?: string;
   until?: string;
   categories?: string[];
@@ -108,6 +109,7 @@ export function handleSearch(
         minScore: args.minScore,
         collection: args.collection,
         lang: args.lang,
+        intent: args.intent,
         since: args.since,
         until: args.until,
         categories: args.categories,

package/src/mcp/tools/vsearch.ts

@@ -28,6 +28,7 @@ interface VsearchInput {
   limit?: number;
   minScore?: number;
   lang?: string;
+  intent?: string;
   since?: string;
   until?: string;
   categories?: string[];
@@ -192,6 +193,7 @@ export function handleVsearch(
             limit: args.limit ?? 5,
             minScore: args.minScore,
             collection: args.collection,
+            intent: args.intent,
             since: args.since,
             until: args.until,
             categories: args.categories,

package/src/pipeline/expansion.ts

@@ -67,9 +67,16 @@ const STOPWORDS = new Set([
 export function generateCacheKey(
   modelUri: string,
   query: string,
-  lang: string
+  lang: string,
+  intent?: string
 ): string {
-  const data = [EXPANSION_PROMPT_VERSION, modelUri, query, lang].join("\0");
+  const data = [
+    EXPANSION_PROMPT_VERSION,
+    modelUri,
+    query,
+    lang,
+    intent?.trim() ?? "",
+  ].join("\0");
   return createHash("sha256").update(data).digest("hex");
 }
 
@@ -150,6 +157,24 @@ function getPromptTemplate(lang?: string): string {
   }
 }
 
+function buildPrompt(query: string, template: string, intent?: string): string {
+  const basePrompt = template.replace("{query}", query);
+  const trimmedIntent = intent?.trim();
+  if (!trimmedIntent) {
+    return basePrompt;
+  }
+
+  return basePrompt
+    .replace(
+      `Query: "${query}"\n`,
+      `Query: "${query}"\nQuery intent: "${trimmedIntent}"\n`
+    )
+    .replace(
+      `Anfrage: "${query}"\n`,
+      `Anfrage: "${query}"\nQuery intent: "${trimmedIntent}"\n`
+    );
+}
+
 interface QuerySignals {
   quotedPhrases: string[];
   negations: string[];
@@ -405,6 +430,10 @@ export interface ExpansionOptions {
   lang?: string;
   /** Timeout in milliseconds */
   timeout?: number;
+  /** Optional context that steers expansion for ambiguous queries */
+  intent?: string;
+  /** Optional bounded context size override for expansion generation */
+  contextSize?: number;
 }
 
 /**
@@ -420,7 +449,7 @@ export async function expandQuery(
 
   // Build prompt
   const template = getPromptTemplate(options.lang);
-  const prompt = template.replace("{query}", query);
+  const prompt = buildPrompt(query, template, options.intent);
 
   // Run with timeout (clear timer to avoid resource leak)
   let timeoutId: ReturnType<typeof setTimeout> | undefined;
@@ -434,6 +463,7 @@ export async function expandQuery(
         temperature: 0,
         seed: 42,
         maxTokens: 512,
+        contextSize: options.contextSize,
       }),
       timeoutPromise,
     ]);
@@ -486,7 +516,12 @@ export async function expandQueryCached(
   options: ExpansionOptions = {}
 ): Promise<StoreResult<ExpansionResult | null>> {
   const lang = options.lang ?? "auto";
-  const cacheKey = generateCacheKey(deps.genPort.modelUri, query, lang);
+  const cacheKey = generateCacheKey(
+    deps.genPort.modelUri,
+    query,
+    lang,
+    options.intent
+  );
 
   // Check cache
   const cached = await deps.getCache(cacheKey);

package/src/pipeline/hybrid.ts

@@ -35,6 +35,7 @@ import {
   explainVector,
 } from "./explain";
 import { type RankedInput, rrfFuse, toRankedInput } from "./fusion";
+import { selectBestChunkForSteering } from "./intent";
 import { detectQueryLanguage } from "./query-language";
 import {
   buildExpansionFromQueryModes,
@@ -329,16 +330,18 @@ export async function searchHybrid(
   }
 
   if (expansionStatus !== "provided" && shouldExpand) {
-    const hasStrongSignal = await checkBm25Strength(store, query, {
-      collection: options.collection,
-      lang: options.lang,
-      tagsAll: options.tagsAll,
-      tagsAny: options.tagsAny,
-      since: temporalRange.since,
-      until: temporalRange.until,
-      categories: options.categories,
-      author: options.author,
-    });
+    const hasStrongSignal = options.intent?.trim()
+      ? false
+      : await checkBm25Strength(store, query, {
+          collection: options.collection,
+          lang: options.lang,
+          tagsAll: options.tagsAll,
+          tagsAny: options.tagsAny,
+          since: temporalRange.since,
+          until: temporalRange.until,
+          categories: options.categories,
+          author: options.author,
+        });
 
     if (hasStrongSignal) {
       expansionStatus = "skipped_strong";
@@ -349,6 +352,8 @@ export async function searchHybrid(
         // Use queryLanguage for prompt selection, NOT options.lang (retrieval filter)
         lang: queryLanguage,
         timeout: pipelineConfig.expansionTimeout,
+        intent: options.intent,
+        contextSize: deps.config.models?.expandContextSize,
       });
       if (expandResult.ok) {
         expansion = expandResult.value;
@@ -496,13 +501,16 @@ export async function searchHybrid(
   // 4. Reranking
   // ─────────────────────────────────────────────────────────────────────────
   const rerankStartedAt = performance.now();
+  const candidateLimit =
+    options.candidateLimit ?? pipelineConfig.rerankCandidates;
   const rerankResult = await rerankCandidates(
     { rerankPort: options.noRerank ? null : rerankPort, store },
     query,
     fusedCandidates,
     {
-      maxCandidates: pipelineConfig.rerankCandidates,
+      maxCandidates: candidateLimit,
       blendingSchedule: pipelineConfig.blendingSchedule,
+      intent: options.intent,
     }
   );
   if (rerankResult.fallbackReason === "disabled") {
@@ -513,10 +521,7 @@ export async function searchHybrid(
   timings.rerankMs = performance.now() - rerankStartedAt;
 
   explainLines.push(
-    explainRerank(
-      !options.noRerank && rerankPort !== null,
-      pipelineConfig.rerankCandidates
-    )
+    explainRerank(!options.noRerank && rerankPort !== null, candidateLimit)
   );
 
   // ─────────────────────────────────────────────────────────────────────────
@@ -692,10 +697,23 @@ export async function searchHybrid(
     const collectionPath = collectionPaths.get(doc.collection);
 
     // For --full mode, fetch full mirror content
-    let snippet = chunk.text;
+    const snippetChunk =
+      options.full || !options.intent?.trim()
+        ? chunk
+        : (selectBestChunkForSteering(
+            chunksMap.get(candidate.mirrorHash) ?? [],
+            query,
+            options.intent,
+            {
+              preferredSeq: chunk.seq,
+              intentWeight: 0.3,
+            }
+          ) ?? chunk);
+
+    let snippet = snippetChunk.text;
     let snippetRange: { startLine: number; endLine: number } | undefined = {
-      startLine: chunk.startLine,
-      endLine: chunk.endLine,
+      startLine: snippetChunk.startLine,
+      endLine: snippetChunk.endLine,
     };
 
     if (options.full) {
@@ -791,12 +809,14 @@ export async function searchHybrid(
       reranked: rerankResult.reranked,
       vectorsUsed: vectorAvailable,
       totalResults: finalResults.length,
+      intent: options.intent,
       collection: options.collection,
       lang: options.lang,
       since: temporalRange.since,
       until: temporalRange.until,
       categories: options.categories,
       author: options.author,
+      candidateLimit,
       queryLanguage,
       queryModes: queryModeSummary,
       explain: explainData,

package/src/pipeline/intent.ts

@@ -0,0 +1,152 @@
+/**
+ * Intent-aware retrieval helpers.
+ *
+ * @module src/pipeline/intent
+ */
+
+import type { ChunkRow } from "../store/types";
+
+const TOKEN_PATTERN = /[A-Za-z0-9][A-Za-z0-9.+#/_-]*/g;
+
+const STOPWORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "for",
+  "from",
+  "how",
+  "in",
+  "is",
+  "it",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "this",
+  "to",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "why",
+  "with",
+]);
+
+const MATCH_ANCHOR_BONUS = 0.2;
+
+function dedupe(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function normalizeToken(token: string): string {
+  return token.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "").toLowerCase();
+}
+
+/**
+ * Extract meaningful steering terms from query/intent text.
+ * Keeps short domain tokens like API/SQL/LLM while dropping common stop words.
+ */
+export function extractSteeringTerms(text: string): string[] {
+  const matches = text.match(TOKEN_PATTERN) ?? [];
+  const terms: string[] = [];
+
+  for (const rawToken of matches) {
+    const token = normalizeToken(rawToken);
+    if (token.length < 2) {
+      continue;
+    }
+    if (STOPWORDS.has(token)) {
+      continue;
+    }
+    terms.push(token);
+  }
+
+  return dedupe(terms);
+}
+
+function scoreTextForTerms(text: string, terms: string[]): number {
+  if (terms.length === 0 || text.length === 0) {
+    return 0;
+  }
+
+  const haystack = text.toLowerCase();
+  let score = 0;
+
+  for (const term of terms) {
+    if (haystack.includes(term)) {
+      score += 1;
+    }
+  }
+
+  return score;
+}
+
+export interface ChunkSelectionOptions {
+  preferredSeq?: number | null;
+  intentWeight: number;
+}
+
+/**
+ * Choose the most query-relevant chunk in a document, with intent as a softer steer.
+ */
+export function selectBestChunkForSteering(
+  chunks: ChunkRow[],
+  query: string,
+  intent: string | undefined,
+  options: ChunkSelectionOptions
+): ChunkRow | null {
+  if (chunks.length === 0) {
+    return null;
+  }
+
+  const queryTerms = extractSteeringTerms(query);
+  const intentTerms = extractSteeringTerms(intent ?? "");
+  const preferredSeq = options.preferredSeq ?? null;
+  let bestChunk: ChunkRow | null = null;
+  let bestScore = Number.NEGATIVE_INFINITY;
+
+  for (const chunk of chunks) {
+    const queryScore = scoreTextForTerms(chunk.text, queryTerms);
+    const intentScore =
+      scoreTextForTerms(chunk.text, intentTerms) * options.intentWeight;
+    const preferredBonus =
+      preferredSeq !== null && chunk.seq === preferredSeq
+        ? MATCH_ANCHOR_BONUS
+        : 0;
+    const score = queryScore + intentScore + preferredBonus;
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestChunk = chunk;
+      continue;
+    }
+
+    if (score === bestScore && bestChunk && chunk.seq < bestChunk.seq) {
+      bestChunk = chunk;
+    }
+  }
+
+  return bestChunk ?? chunks[0] ?? null;
+}
+
+/**
+ * Build a rerank query that provides intent as context without becoming a search term.
+ */
+export function buildIntentAwareRerankQuery(
+  query: string,
+  intent?: string
+): string {
+  const trimmedIntent = intent?.trim();
+  if (!trimmedIntent) {
+    return query;
+  }
+
+  return `Intent: ${trimmedIntent}\nQuery: ${query}`;
+}

package/src/pipeline/rerank.ts

@@ -9,6 +9,10 @@ import type { RerankPort } from "../llm/types";
 import type { ChunkRow, StorePort } from "../store/types";
 import type { BlendingTier, FusionCandidate, RerankedCandidate } from "./types";
 
+import {
+  buildIntentAwareRerankQuery,
+  selectBestChunkForSteering,
+} from "./intent";
 import { DEFAULT_BLENDING_SCHEDULE } from "./types";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -20,6 +24,8 @@ export interface RerankOptions {
   maxCandidates?: number;
   /** Blending schedule */
   blendingSchedule?: BlendingTier[];
+  /** Optional disambiguating context for reranking */
+  intent?: string;
 }
 
 export interface RerankResult {
@@ -75,27 +81,6 @@ function blend(
 const MAX_CHUNK_CHARS = 4000;
 const PROTECT_BM25_TOP_RANK = 1;
 
-interface BestChunkInfo {
-  candidate: FusionCandidate;
-  seq: number;
-}
-
-/**
- * Extract best chunk per document for efficient reranking.
- */
-function selectBestChunks(
-  toRerank: FusionCandidate[]
-): Map<string, BestChunkInfo> {
-  const bestChunkPerDoc = new Map<string, BestChunkInfo>();
-  for (const c of toRerank) {
-    const existing = bestChunkPerDoc.get(c.mirrorHash);
-    if (!existing || c.fusionScore > existing.candidate.fusionScore) {
-      bestChunkPerDoc.set(c.mirrorHash, { candidate: c, seq: c.seq });
-    }
-  }
-  return bestChunkPerDoc;
-}
-
 function isProtectedLexicalTopHit(candidate: FusionCandidate): boolean {
   return (
     candidate.bm25Rank === PROTECT_BM25_TOP_RANK &&
@@ -108,31 +93,50 @@ function isProtectedLexicalTopHit(candidate: FusionCandidate): boolean {
  */
 async function fetchChunkTexts(
   store: StorePort,
-  bestChunkPerDoc: Map<string, BestChunkInfo>
+  toRerank: FusionCandidate[],
+  query: string,
+  intent: string | undefined
 ): Promise<{ texts: string[]; hashToIndex: Map<string, number> }> {
-  const uniqueHashes = [...bestChunkPerDoc.keys()];
+  const uniqueHashes = [
+    ...new Set(toRerank.map((candidate) => candidate.mirrorHash)),
+  ];
   const chunksBatchResult = await store.getChunksBatch(uniqueHashes);
   const chunksByHash: Map<string, ChunkRow[]> = chunksBatchResult.ok
     ? chunksBatchResult.value
     : new Map();
-  const chunkTexts = new Map<string, string>();
+  const preferredSeqByHash = new Map<string, number>();
+
+  for (const candidate of toRerank) {
+    const existingSeq = preferredSeqByHash.get(candidate.mirrorHash);
+    if (existingSeq !== undefined) {
+      const existingCandidate = toRerank.find(
+        (entry) =>
+          entry.mirrorHash === candidate.mirrorHash && entry.seq === existingSeq
+      );
+      if (
+        existingCandidate &&
+        existingCandidate.fusionScore >= candidate.fusionScore
+      ) {
+        continue;
+      }
+    }
+    preferredSeqByHash.set(candidate.mirrorHash, candidate.seq);
+  }
 
+  const chunkTexts = new Map<string, string>();
   for (const hash of uniqueHashes) {
-    const bestInfo = bestChunkPerDoc.get(hash);
     const chunks = chunksByHash.get(hash);
-
-    if (chunks && bestInfo) {
-      const chunk = chunks.find((c) => c.seq === bestInfo.seq);
-      const text = chunk?.text ?? "";
-      chunkTexts.set(
-        hash,
-        text.length > MAX_CHUNK_CHARS
-          ? `${text.slice(0, MAX_CHUNK_CHARS)}...`
-          : text
-      );
-    } else {
-      chunkTexts.set(hash, "");
-    }
+    const bestChunk = selectBestChunkForSteering(chunks ?? [], query, intent, {
+      preferredSeq: preferredSeqByHash.get(hash) ?? null,
+      intentWeight: 0.5,
+    });
+    const text = bestChunk?.text ?? "";
+    chunkTexts.set(
+      hash,
+      text.length > MAX_CHUNK_CHARS
+        ? `${text.slice(0, MAX_CHUNK_CHARS)}...`
+        : text
+    );
   }
 
   const hashToIndex = new Map<string, number>();
@@ -198,11 +202,40 @@ export async function rerankCandidates(
   const remaining = candidates.slice(maxCandidates);
 
   // Extract best chunk per document for efficient reranking
-  const bestChunkPerDoc = selectBestChunks(toRerank);
-  const { texts, hashToIndex } = await fetchChunkTexts(store, bestChunkPerDoc);
+  const { texts, hashToIndex } = await fetchChunkTexts(
+    store,
+    toRerank,
+    query,
+    options.intent
+  );
+
+  const uniqueTexts: string[] = [];
+  const docIndexToUniqueIndex = new Map<number, number>();
+  const uniqueIndexToDocIndices = new Map<number, number[]>();
+  const textToUniqueIndex = new Map<string, number>();
+
+  for (const [docIndex, text] of texts.entries()) {
+    const existingIndex = textToUniqueIndex.get(text);
+    if (existingIndex !== undefined) {
+      docIndexToUniqueIndex.set(docIndex, existingIndex);
+      const mapped = uniqueIndexToDocIndices.get(existingIndex) ?? [];
+      mapped.push(docIndex);
+      uniqueIndexToDocIndices.set(existingIndex, mapped);
+      continue;
+    }
+
+    const uniqueIndex = uniqueTexts.length;
+    uniqueTexts.push(text);
+    textToUniqueIndex.set(text, uniqueIndex);
+    docIndexToUniqueIndex.set(docIndex, uniqueIndex);
+    uniqueIndexToDocIndices.set(uniqueIndex, [docIndex]);
+  }
 
   // Run reranking on best chunks (much faster than full docs)
-  const rerankResult = await rerankPort.rerank(query, texts);
+  const rerankResult = await rerankPort.rerank(
+    buildIntentAwareRerankQuery(query, options.intent),
+    uniqueTexts
+  );
 
   if (!rerankResult.ok) {
     return {
@@ -217,9 +250,13 @@ export async function rerankCandidates(
   }
 
   // Normalize rerank scores using min-max
-  const scoreByDocIndex = new Map(
-    rerankResult.value.map((s) => [s.index, s.score])
-  );
+  const scoreByDocIndex = new Map<number, number>();
+  for (const score of rerankResult.value) {
+    const docIndices = uniqueIndexToDocIndices.get(score.index) ?? [];
+    for (const docIndex of docIndices) {
+      scoreByDocIndex.set(docIndex, score.score);
+    }
+  }
   const rerankScores = rerankResult.value.map((s) => s.score);
   const minRerank = Math.min(...rerankScores);
   const maxRerank = Math.max(...rerankScores);

package/src/pipeline/search.ts

@@ -17,6 +17,7 @@ import type {
 
 import { err, ok } from "../store/types";
 import { createChunkLookup } from "./chunk-lookup";
+import { selectBestChunkForSteering } from "./intent";
 import { detectQueryLanguage } from "./query-language";
 import {
   resolveRecencyTimestamp,
@@ -218,9 +219,23 @@ export async function searchBm25(
     seenUriSeq.add(uriSeqKey);
 
     // Get chunk via O(1) lookup
-    const chunk = fts.mirrorHash
+    const rawChunk = fts.mirrorHash
       ? (getChunk(fts.mirrorHash, fts.seq) ?? null)
       : null;
+    const chunk =
+      options.intent && fts.mirrorHash
+        ? (selectBestChunkForSteering(
+            chunksMapResult.ok
+              ? (chunksMapResult.value.get(fts.mirrorHash) ?? [])
+              : [],
+            query,
+            options.intent,
+            {
+              preferredSeq: rawChunk?.seq ?? fts.seq,
+              intentWeight: 0.3,
+            }
+          ) ?? rawChunk)
+        : rawChunk;
 
     // For --full, de-dupe by docid (keep best scoring chunk per doc)
     // Raw BM25: smaller (more negative) is better
@@ -293,6 +308,7 @@ export async function searchBm25(
       query,
       mode: "bm25",
       totalResults: Math.min(filteredResults.length, limit),
+      intent: options.intent,
       collection: options.collection,
       lang: options.lang,
       since: temporalRange.since,

package/src/pipeline/types.ts

@@ -62,6 +62,7 @@ export interface SearchMeta {
   reranked?: boolean;
   vectorsUsed?: boolean;
   totalResults: number;
+  intent?: string;
   collection?: string;
   lang?: string;
   /** Detected/overridden query language for prompt selection (typically BCP-47; may be user-provided via --lang) */
@@ -76,6 +77,8 @@ export interface SearchMeta {
   categories?: string[];
   /** Author filter applied */
   author?: string;
+  /** Rerank candidate limit used */
+  candidateLimit?: number;
   /** Explain data (when --explain is used) */
   explain?: {
     lines: ExplainLine[];
@@ -119,6 +122,8 @@ export interface SearchOptions {
   categories?: string[];
   /** Filter by author value */
   author?: string;
+  /** Optional disambiguating context that steers scoring/snippets, but is not searched directly */
+  intent?: string;
 }
 
 /** Structured query mode identifier */
@@ -145,6 +150,8 @@ export type HybridSearchOptions = SearchOptions & {
   noRerank?: boolean;
   /** Optional structured mode entries; when set, used as expansion inputs */
   queryModes?: QueryModeInput[];
+  /** Max candidates passed to reranking */
+  candidateLimit?: number;
   /** Enable explain output */
   explain?: boolean;
   /** Language hint for prompt selection (does NOT filter retrieval, only affects expansion prompts) */
@@ -308,6 +315,8 @@ export interface AskMeta {
   expanded: boolean;
   reranked: boolean;
   vectorsUsed: boolean;
+  intent?: string;
+  candidateLimit?: number;
   answerGenerated?: boolean;
   totalResults?: number;
   answerContext?: AnswerContextExplain;

package/src/pipeline/vsearch.ts

@@ -14,6 +14,7 @@ import type { SearchOptions, SearchResult, SearchResults } from "./types";
 import { err, ok } from "../store/types";
 import { createChunkLookup } from "./chunk-lookup";
 import { formatQueryForEmbedding } from "./contextual";
+import { selectBestChunkForSteering } from "./intent";
 import { detectQueryLanguage } from "./query-language";
 import {
   resolveRecencyTimestamp,
@@ -146,7 +147,18 @@ export async function searchVectorWithEmbedding(
     }
 
     // Get chunk via O(1) lookup
-    const chunk = getChunk(vec.mirrorHash, vec.seq);
+    const rawChunk = getChunk(vec.mirrorHash, vec.seq);
+    const chunk = options.intent
+      ? (selectBestChunkForSteering(
+          chunksMap.get(vec.mirrorHash) ?? [],
+          query,
+          options.intent,
+          {
+            preferredSeq: rawChunk?.seq ?? vec.seq,
+            intentWeight: 0.3,
+          }
+        ) ?? rawChunk)
+      : rawChunk;
     if (!chunk) {
       continue;
     }
@@ -288,6 +300,7 @@ export async function searchVectorWithEmbedding(
       mode: "vector",
       vectorsUsed: true,
       totalResults: finalResults.length,
+      intent: options.intent,
       collection: options.collection,
       lang: options.lang,
       since: temporalRange.since,

package/src/serve/public/lib/retrieval-filters.ts

@@ -9,6 +9,8 @@ export interface QueryModeEntry {
 
 export interface RetrievalFiltersState {
   collection: string;
+  intent: string;
+  candidateLimit: string;
   since: string;
   until: string;
   category: string;
@@ -121,6 +123,9 @@ export function parseFiltersFromSearch(
 
   return {
     collection: params.get("collection") ?? defaults.collection ?? "",
+    intent: params.get("intent") ?? defaults.intent ?? "",
+    candidateLimit:
+      params.get("candidateLimit") ?? defaults.candidateLimit ?? "",
     since: params.get("since") ?? defaults.since ?? "",
     until: params.get("until") ?? defaults.until ?? "",
     category: params.get("category") ?? defaults.category ?? "",
@@ -145,6 +150,8 @@ export function applyFiltersToUrl(
   };
 
   setOrDelete("collection", filters.collection);
+  setOrDelete("intent", filters.intent);
+  setOrDelete("candidateLimit", filters.candidateLimit);
   setOrDelete("since", filters.since);
   setOrDelete("until", filters.until);
   setOrDelete("category", filters.category);

package/src/serve/public/pages/Ask.tsx

@@ -164,6 +164,8 @@ export default function Ask({ navigate }: PageProps) {
 
   const [showAdvanced, setShowAdvanced] = useState(false);
   const [selectedCollection, setSelectedCollection] = useState("");
+  const [intent, setIntent] = useState("");
+  const [candidateLimit, setCandidateLimit] = useState("");
   const [since, setSince] = useState("");
   const [until, setUntil] = useState("");
   const [category, setCategory] = useState("");
@@ -242,6 +244,12 @@ export default function Ask({ navigate }: PageProps) {
       if (selectedCollection) {
         requestBody.collection = selectedCollection;
       }
+      if (intent.trim()) {
+        requestBody.intent = intent.trim();
+      }
+      if (candidateLimit.trim()) {
+        requestBody.candidateLimit = Number(candidateLimit);
+      }
       if (since) {
         requestBody.since = since;
       }
@@ -295,7 +303,9 @@ export default function Ask({ navigate }: PageProps) {
     },
     [
       author,
+      candidateLimit,
       category,
+      intent,
       query,
       selectedCollection,
       since,
@@ -315,6 +325,8 @@ export default function Ask({ navigate }: PageProps) {
 
   const clearFilters = () => {
     setSelectedCollection("");
+    setIntent("");
+    setCandidateLimit("");
     setSince("");
     setUntil("");
     setCategory("");
@@ -327,6 +339,8 @@ export default function Ask({ navigate }: PageProps) {
 
   const activeFilterPills = [
     selectedCollection ? `collection:${selectedCollection}` : null,
+    intent.trim() ? `intent:${intent.trim()}` : null,
+    candidateLimit.trim() ? `candidates:${candidateLimit.trim()}` : null,
     since ? `since:${since}` : null,
     until ? `until:${until}` : null,
     category.trim() ? `category:${category.trim()}` : null,
@@ -441,6 +455,17 @@ export default function Ask({ navigate }: PageProps) {
                       />
                     </div>
 
+                    <div className="md:col-span-2">
+                      <p className="mb-1 text-muted-foreground text-xs">
+                        Intent
+                      </p>
+                      <Input
+                        onChange={(e) => setIntent(e.target.value)}
+                        placeholder="Disambiguate ambiguous questions without searching on this text"
+                        value={intent}
+                      />
+                    </div>
+
                     <div>
                       <p className="mb-1 text-muted-foreground text-xs">
                         Category
@@ -475,6 +500,20 @@ export default function Ask({ navigate }: PageProps) {
                       </div>
                     </div>
 
+                    <div>
+                      <p className="mb-1 text-muted-foreground text-xs">
+                        Candidate limit
+                      </p>
+                      <Input
+                        inputMode="numeric"
+                        min="1"
+                        onChange={(e) => setCandidateLimit(e.target.value)}
+                        placeholder="20"
+                        type="number"
+                        value={candidateLimit}
+                      />
+                    </div>
+
                     <div className="md:col-span-2">
                       <p className="mb-1 text-muted-foreground text-xs">
                         Tags (comma separated)

package/src/serve/public/pages/Search.tsx

@@ -153,6 +153,8 @@ export default function Search({ navigate }: PageProps) {
   const [showAdvanced, setShowAdvanced] = useState(
     Boolean(
       initialFilters.collection ||
+      initialFilters.intent ||
+      initialFilters.candidateLimit ||
       initialFilters.since ||
       initialFilters.until ||
       initialFilters.category ||
@@ -166,6 +168,10 @@ export default function Search({ navigate }: PageProps) {
   const [selectedCollection, setSelectedCollection] = useState(
     initialFilters.collection
   );
+  const [intent, setIntent] = useState(initialFilters.intent);
+  const [candidateLimit, setCandidateLimit] = useState(
+    initialFilters.candidateLimit
+  );
   const [since, setSince] = useState(initialFilters.since);
   const [until, setUntil] = useState(initialFilters.until);
   const [category, setCategory] = useState(initialFilters.category);
@@ -179,13 +185,17 @@ export default function Search({ navigate }: PageProps) {
   const [showMobileTags, setShowMobileTags] = useState(false);
 
   const hybridAvailable = capabilities?.hybrid ?? false;
-  const forceHybridForModes = thoroughness === "fast" && queryModes.length > 0;
+  const forceHybridForModes =
+    thoroughness === "fast" &&
+    (queryModes.length > 0 || intent.trim().length > 0);
 
   // Sync URL as filter state changes.
   useEffect(() => {
     const url = new URL(window.location.href);
     applyFiltersToUrl(url, {
       collection: selectedCollection,
+      intent,
+      candidateLimit,
       since,
       until,
       category,
@@ -198,7 +208,9 @@ export default function Search({ navigate }: PageProps) {
   }, [
     activeTags,
     author,
+    candidateLimit,
     category,
+    intent,
     queryModes,
     selectedCollection,
     since,
@@ -283,7 +295,10 @@ export default function Search({ navigate }: PageProps) {
       setError(null);
       setSearched(true);
 
-      const useBm25 = thoroughness === "fast" && queryModes.length === 0;
+      const useBm25 =
+        thoroughness === "fast" &&
+        queryModes.length === 0 &&
+        intent.trim().length === 0;
       const endpoint = useBm25 ? "/api/search" : "/api/query";
       const body: Record<string, unknown> = {
         query,
@@ -293,6 +308,12 @@ export default function Search({ navigate }: PageProps) {
       if (selectedCollection) {
         body.collection = selectedCollection;
       }
+      if (intent.trim()) {
+        body.intent = intent.trim();
+      }
+      if (candidateLimit.trim()) {
+        body.candidateLimit = Number(candidateLimit);
+      }
       if (since) {
         body.since = since;
       }
@@ -350,7 +371,9 @@ export default function Search({ navigate }: PageProps) {
     [
       activeTags,
       author,
+      candidateLimit,
       category,
+      intent,
       query,
       queryModes,
       selectedCollection,
@@ -370,7 +393,9 @@ export default function Search({ navigate }: PageProps) {
   }, [
     activeTags,
     author,
+    candidateLimit,
     category,
+    intent,
     queryModes,
     selectedCollection,
     since,
@@ -387,6 +412,8 @@ export default function Search({ navigate }: PageProps) {
 
   const activeFilterPills = [
     selectedCollection ? `collection:${selectedCollection}` : null,
+    intent.trim() ? `intent:${intent.trim()}` : null,
+    candidateLimit.trim() ? `candidates:${candidateLimit.trim()}` : null,
     since ? `since:${since}` : null,
     until ? `until:${until}` : null,
     category.trim() ? `category:${category.trim()}` : null,
@@ -399,6 +426,8 @@ export default function Search({ navigate }: PageProps) {
 
   const clearAdvancedFilters = () => {
     setSelectedCollection("");
+    setIntent("");
+    setCandidateLimit("");
     setSince("");
     setUntil("");
     setCategory("");
@@ -551,6 +580,17 @@ export default function Search({ navigate }: PageProps) {
                           />
                         </div>
 
+                        <div className="md:col-span-2">
+                          <p className="mb-1 text-muted-foreground text-xs">
+                            Intent
+                          </p>
+                          <Input
+                            onChange={(e) => setIntent(e.target.value)}
+                            placeholder="Disambiguate ambiguous queries without searching on this text"
+                            value={intent}
+                          />
+                        </div>
+
                         <div>
                           <p className="mb-1 text-muted-foreground text-xs">
                             Category
@@ -584,6 +624,20 @@ export default function Search({ navigate }: PageProps) {
                             />
                           </div>
                         </div>
+
+                        <div>
+                          <p className="mb-1 text-muted-foreground text-xs">
+                            Candidate limit
+                          </p>
+                          <Input
+                            inputMode="numeric"
+                            min="1"
+                            onChange={(e) => setCandidateLimit(e.target.value)}
+                            placeholder="20"
+                            type="number"
+                            value={candidateLimit}
+                          />
+                        </div>
                       </div>
 
                       <div className="flex flex-wrap items-center gap-2">

package/src/serve/routes/api.ts

@@ -66,6 +66,7 @@ export interface SearchRequestBody {
   limit?: number;
   minScore?: number;
   collection?: string;
+  intent?: string;
   since?: string;
   until?: string;
   /** Comma-separated category filters */
@@ -83,6 +84,8 @@ export interface QueryRequestBody {
   minScore?: number;
   collection?: string;
   lang?: string;
+  intent?: string;
+  candidateLimit?: number;
   since?: string;
   until?: string;
   /** Comma-separated category filters */
@@ -102,6 +105,8 @@ export interface AskRequestBody {
   limit?: number;
   collection?: string;
   lang?: string;
+  intent?: string;
+  candidateLimit?: number;
   since?: string;
   until?: string;
   /** Comma-separated category filters */
@@ -1093,6 +1098,9 @@ export async function handleSearch(
   if (body.until !== undefined && typeof body.until !== "string") {
     return errorResponse("VALIDATION", "until must be a string");
   }
+  if (body.intent !== undefined && typeof body.intent !== "string") {
+    return errorResponse("VALIDATION", "intent must be a string");
+  }
   if (body.category !== undefined && typeof body.category !== "string") {
     return errorResponse(
       "VALIDATION",
@@ -1139,6 +1147,7 @@ export async function handleSearch(
     limit: Math.min(body.limit || 10, 50),
     minScore: body.minScore,
     collection: body.collection,
+    intent: body.intent?.trim() || undefined,
     tagsAll,
     tagsAny,
     since: body.since,
@@ -1208,6 +1217,18 @@ export async function handleQuery(
   if (body.until !== undefined && typeof body.until !== "string") {
     return errorResponse("VALIDATION", "until must be a string");
   }
+  if (body.intent !== undefined && typeof body.intent !== "string") {
+    return errorResponse("VALIDATION", "intent must be a string");
+  }
+  if (
+    body.candidateLimit !== undefined &&
+    (typeof body.candidateLimit !== "number" || body.candidateLimit < 1)
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "candidateLimit must be a positive integer"
+    );
+  }
   if (body.category !== undefined && typeof body.category !== "string") {
     return errorResponse(
       "VALIDATION",
@@ -1314,6 +1335,11 @@ export async function handleQuery(
       minScore: body.minScore,
       collection: body.collection,
       lang: body.lang,
+      intent: body.intent?.trim() || undefined,
+      candidateLimit:
+        body.candidateLimit !== undefined
+          ? Math.min(body.candidateLimit, 100)
+          : undefined,
       queryModes,
       noExpand: body.noExpand,
       noRerank: body.noRerank,
@@ -1377,6 +1403,18 @@ export async function handleAsk(
   if (body.until !== undefined && typeof body.until !== "string") {
     return errorResponse("VALIDATION", "until must be a string");
   }
+  if (body.intent !== undefined && typeof body.intent !== "string") {
+    return errorResponse("VALIDATION", "intent must be a string");
+  }
+  if (
+    body.candidateLimit !== undefined &&
+    (typeof body.candidateLimit !== "number" || body.candidateLimit < 1)
+  ) {
+    return errorResponse(
+      "VALIDATION",
+      "candidateLimit must be a positive integer"
+    );
+  }
   if (body.category !== undefined && typeof body.category !== "string") {
     return errorResponse(
       "VALIDATION",
@@ -1431,8 +1469,13 @@ export async function handleAsk(
       limit,
       collection: body.collection,
       lang: body.lang,
+      intent: body.intent?.trim() || undefined,
       noExpand: body.noExpand,
       noRerank: body.noRerank,
+      candidateLimit:
+        body.candidateLimit !== undefined
+          ? Math.min(body.candidateLimit, 100)
+          : undefined,
       tagsAll,
       tagsAny,
       since: body.since,
@@ -1483,6 +1526,8 @@ export async function handleAsk(
       expanded: searchResult.value.meta.expanded ?? false,
       reranked: searchResult.value.meta.reranked ?? false,
       vectorsUsed: searchResult.value.meta.vectorsUsed ?? false,
+      intent: searchResult.value.meta.intent,
+      candidateLimit: searchResult.value.meta.candidateLimit,
       answerGenerated,
       totalResults: results.length,
       answerContext,