sift-light 1.0.0 → 1.0.2

package/src/mcp-server.mjs

@@ -7,7 +7,7 @@ import { URL as URL2 } from "node:url";
 // package.json
 var package_default = {
   name: "sift-light",
-  version: "1.0.0",
+  version: "1.0.2",
   description: "Context-efficient local search for files, documents, notes and logs across Pi, OMP and MCP clients",
   keywords: [
     "ai-agent",
@@ -292,7 +292,33 @@ function analysisExtraGroups(counts, termCounts, items) {
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function compactSemanticMetadata(details, analysis) {
+  const counts = analysis.counts;
+  const stats = analysis.stats;
+  const judge = analysis.semanticJudge;
+  const coverage = analysis.coverage;
+  return [
+    ...counts || stats ? [
+      `Search: ${String(counts?.filesAdmitted ?? stats?.filesAdmitted ?? 0)} files, ${String(stats?.passagesRanked ?? counts?.passagesQueued ?? 0)} passages; ${String(stats?.elapsedMs ?? 0)} ms; peak inference RSS ${String(stats?.inferencePeakRssBytes ?? 0)} bytes; cache ${String(stats?.conceptCacheHits ?? 0)} hits/${String(stats?.conceptCacheMisses ?? 0)} misses.`
+    ] : [],
+    ...coverage ? [
+      `Coverage: ${Object.entries(coverage).map(([name, status]) => `${name}=${status}`).join(", ")}.`
+    ] : [],
+    ...analysis.scope ? [`Scope: ${analysis.scope.path}; ignore=${analysis.scope.ignorePolicy}.`] : [],
+    ...analysis.sourceGeneration ? [
+      `Source: ${analysis.sourceGeneration.verification}; ${String(analysis.sourceGeneration.filesUnavailable)} unavailable.`
+    ] : [],
+    ...judge ? [
+      `Semantic judge: ${judge.status}; ${String(judge.judgedCandidates)}/${String(judge.candidatesConsidered)} judged, ${String(judge.candidatesUnjudged)} unjudged; batches ${String(judge.batchesCompleted)}/${String(judge.batchesAttempted)} completed; classes ${JSON.stringify(judge.classificationCounts)}${judge.reason ? `; ${judge.reason}` : ""}.`
+    ] : [],
+    ...details.operation ? [`Operation: ${details.operation.state}; id=${details.operation.id}.`] : [],
+    ...analysis.reasons.map((reason) => `[${reason}]`),
+    ...details.redactionApplied ? ["[Display redaction applied.]"] : []
+  ];
+}
 function compactMetadata(details, analysis) {
+  if (analysis.kind === "concept" || analysis.kind === "hybrid")
+    return compactSemanticMetadata(details, analysis);
   return [
     ...analysis.statistics ? formatStatistics(analysis.statistics) : [],
     analysis.counts ? `Counts: ${JSON.stringify(analysis.counts)}` : undefined,
@@ -320,7 +346,7 @@ function compactRows(analysis) {
       rows.push(JSON.stringify(item.path));
       previousPath = item.path;
     }
-    const label = analysis.kind === "outline" && analysis.modelOutput ? item.label : "metadata";
+    const label = analysis.kind === "outline" && analysis.modelOutput || analysis.kind === "files" ? item.label : "metadata";
     const semanticJudge = item.details?.semanticJudge;
     const judgment = isRecord(semanticJudge) && typeof semanticJudge.classification === "string" && typeof semanticJudge.probability === "number" && typeof semanticJudge.model === "string" ? ` Jev: ${semanticJudge.classification}; probability=${String(semanticJudge.probability)};${typeof semanticJudge.confidence === "number" ? ` confidence=${String(semanticJudge.confidence)};` : ""} model=${JSON.stringify(semanticJudge.model)}.` : "";
     rows.push(`#${String(item.index)} L${String(item.line)} ${label}${judgment}`);
@@ -360,6 +386,7 @@ function compactMcpModelText(result) {
   const inspect = compactInspectInstruction(analysis);
   const nextRequest = distinctNextRequest(result.details, analysis);
   const compact = [
+    ...(result.details.requestNotes ?? []).map((note) => `[Request note: ${note}]`),
     header,
     ...compactMetadata(result.details, analysis),
     ...compactRows(analysis),
@@ -391,7 +418,7 @@ var MAX_ANALYSIS_STORAGE_BYTES = 32 * 1024 * 1024;
 var ANALYSIS_METADATA_RESERVE_BYTES = 64 * 1024;
 var MAX_ANALYSIS_REASONS = 64;
 var MAX_ANALYSIS_REASON_BYTES = 4 * 1024;
-var MIN_ANY_OF_TERMS = 2;
+var MIN_ANY_OF_TERMS = 1;
 var MAX_ANY_OF_TERMS = 8;
 var MAX_ANY_OF_TOTAL_TERMS = 64;
 var MAX_LITERAL_TERM_BYTES = 256;
@@ -411,6 +438,7 @@ var ESTIMATED_CHARACTERS_PER_TOKEN = 4;
 var DEFAULT_SUMMARY_FILE_LIMIT = 30;
 var MAX_SELECTED_PATHS = 20;
 var MAX_INSPECT_TARGETS = 5;
+var MAX_INSPECT_REQUEST_TARGETS = 20;
 var MAX_DISPLAYED_OCCURRENCES = 20;
 var MAX_STORED_MATCHES = 50000;
 var MAX_STORED_OCCURRENCES = 200000;
@@ -432,6 +460,7 @@ var PRIVATE_KEY = /-----BEGIN ([^-\r\n]*PRIVATE KEY)-----[\s\S]*?-----END \1----
 var SENSITIVE_NAME = String.raw`(?:(?:[A-Za-z][A-Za-z0-9]*[_-])*(?:password|passwd|secret|token|api[_-]?key|access[_-]?(?:key|token)|secret[_-]?access[_-]?key|private[_-]?key|service[_-]?key)(?:[_-][A-Za-z0-9]+)*)`;
 var SENSITIVE_ASSIGNMENT = new RegExp(String.raw`((?<![A-Za-z0-9_-])(?:["']?${SENSITIVE_NAME}["']?)\s*[:=]\s*)("[^"\r\n]*"|'[^'\r\n]*'|[^\s,;}\r\n]+)`, "gi");
 var SENSITIVE_TOKEN = /\b(?:sk|ghp|xox[baprs])[-_][A-Za-z0-9][A-Za-z0-9_-]{7,}\b/g;
+var CODE_EXPRESSION = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*\s*[([]/u;
 var TYPE_ONLY_VALUES = new Set([
   "boolean",
   "number",
@@ -451,10 +480,11 @@ function redactString(value) {
   });
   redacted = redacted.replace(SENSITIVE_ASSIGNMENT, (match, prefix, rawValue) => {
     const unquoted = rawValue.replace(/^["']|["']$/g, "").toLowerCase();
-    if (TYPE_ONLY_VALUES.has(unquoted))
+    if (TYPE_ONLY_VALUES.has(unquoted) || CODE_EXPRESSION.test(rawValue))
       return match;
     count += 1;
-    return `${prefix}"[REDACTED]"`;
+    const quote = rawValue.startsWith('"') || rawValue.startsWith("'") ? rawValue[0] : "";
+    return `${prefix}${quote}[REDACTED]${quote}`;
   });
   redacted = redacted.replace(SENSITIVE_TOKEN, () => {
     count += 1;
@@ -712,6 +742,15 @@ var PYTHON_LANGUAGE_CAPABILITIES = [
     evidence: "syntax",
     availability: "implemented",
     load: "lazy"
+  },
+  {
+    id: "python-lexical.roles",
+    name: "roles",
+    provider: "bounded Python lexical role scanner",
+    providerKind: "builtin",
+    evidence: "syntax",
+    availability: "implemented",
+    load: "lazy"
   }
 ];
 var DEFAULT_LANGUAGE_CAPABILITIES = [
@@ -839,7 +878,17 @@ var MODE_FIELDS_BY_MODE = {
   auto: ordinaryFields,
   summary: ordinaryFields,
   matches: ordinaryFields,
-  inspect: [...commonFields, "path", "line", "cursor", "matchIndex", "matchIndices", "targets"],
+  inspect: [
+    ...commonFields,
+    "path",
+    "paths",
+    "line",
+    "cursor",
+    "matchIndex",
+    "matchIndices",
+    "targets",
+    "scope"
+  ],
   outline: [...commonFields, "path", "line", "symbol", "cursor", "matchIndex", "maxFilesToParse"],
   imports: [
     ...commonFields,
@@ -859,7 +908,16 @@ var MODE_FIELDS_BY_MODE = {
     "matchIndex",
     "maxFilesToParse"
   ],
-  files: [...commonFields, "query", ...sourceFilters, "modifiedAfter", "modifiedBefore"],
+  files: [
+    ...commonFields,
+    "query",
+    ...sourceFilters,
+    "ignorePolicy",
+    "limit",
+    "scope",
+    "modifiedAfter",
+    "modifiedBefore"
+  ],
   structure: [...commonFields, "pattern", ...sourceFilters, "maxFilesToParse"],
   concept: [...commonFields, "query", ...sourceFilters, "maxFilesToParse"],
   hybrid: [...commonFields, "query", ...sourceFilters, "conceptLimit", "maxFilesToParse"],
@@ -868,9 +926,7 @@ var MODE_FIELDS_BY_MODE = {
   await: ["mode", "operationId"],
   cancel: ["mode", "operationId"]
 };
-var SAFE_DROP_FIELDS = {
-  files: ["scope"]
-};
+var SAFE_DROP_FIELDS = {};
 var SUPPORTED_OUTLINE_EXTENSIONS = new Set(DEFAULT_LANGUAGE_CAPABILITIES.flatMap((descriptor) => descriptor.capabilities.some((capability) => capability.name === "outline") ? descriptor.extensions : []));
 function modeFields(mode) {
   return MODE_FIELDS_BY_MODE[mode];
@@ -899,8 +955,8 @@ var REQUEST_FIELD_GUIDANCE = {
   allOf: "allOf is case-sensitive exact-literal AND; omit pattern, anyOf, literal, ignoreCase, roles",
   context: "context is an output-context budget and is never silently dropped",
   limit: "limit is an output/page budget and is never silently dropped",
-  scope: "scope applies to ordinary content search; mode=files rejects this field because its scope is fixed strict, and only redundant strict may be removed",
-  ignorePolicy: "respect keeps repository ignore rules; include searches ignored files but always excludes .git internals and protected paths",
+  scope: "scope applies to ordinary content search; mode=files is always strict, so it accepts only the redundant scope=strict",
+  ignorePolicy: "respect keeps repository ignore rules and discloses ignored files; include also searches or lists ignored files but always excludes .git internals and protected paths",
   patterns: "audit accepts named exact-literal patterns and returns one closure receipt",
   maxFilesToParse: "concept/hybrid automatically batch the requested scope; this optional field sets an advanced hard file ceiling"
 };
@@ -996,15 +1052,26 @@ function schemaError(input, field, reason) {
     recovery: { action: "manual", reason }
   }, `${field} is invalid: ${reason}`);
 }
+function plainFilePatternRecovery(mode, input, invalid) {
+  return mode === "files" && invalid.includes("pattern") && input.query === undefined && typeof input.pattern === "string" && input.pattern.trim().length > 0 && input.pattern.length <= 256 && input.pattern.isWellFormed() && !/[\\^$.*+?()[\]{}|\r\n\0]/u.test(input.pattern);
+}
+function matchAllFilePatternRecovery(mode, input, invalid) {
+  return mode === "files" && invalid.includes("pattern") && input.query === undefined && typeof input.pattern === "string" && /^(?:\.\*|\.\+|\*+)$/u.test(input.pattern.trim());
+}
 function safeNextRequest(input, mode, invalid) {
   if (input.redact === true && containsSensitiveText(input))
     return;
   const safe = new Set(SAFE_DROP_FIELDS[mode] ?? []);
+  const plainFilePattern = plainFilePatternRecovery(mode, input, invalid);
+  if (plainFilePattern || matchAllFilePatternRecovery(mode, input, invalid))
+    safe.add("pattern");
   if (invalid.some((field) => !safe.has(field)))
     return;
   const next = { ...input };
   for (const field of invalid)
     delete next[field];
+  if (plainFilePattern)
+    next.query = input.pattern;
   if (selectorIssuesFor(next, mode).length > 0)
     return;
   try {
@@ -1033,20 +1100,26 @@ function fieldsError(input, mode, invalid, selectorIssues = []) {
     });
   const visibleFields = visibleInvalid.map((field) => boundedField(field)).join(", ");
   const reason = omitted > 0 ? `mode=${mode} does not accept ${visibleFields} and ${String(omitted)} additional field(s)` : `mode=${mode} does not accept ${visibleFields}`;
-  const flatRule = `Fields are flat: pass them at the top level, not inside a per-mode object. mode=${mode} accepts: ${modeFields(mode).join(", ")}.`;
+  const nestedModeObject = invalid.includes(mode);
+  const flatRule = nestedModeObject ? `Fields are flat: pass them at the top level, not inside a per-mode object. mode=${mode} accepts: ${modeFields(mode).join(", ")}.` : "";
+  const filesPatternRule = mode === "files" && invalid.includes("pattern") ? "For filename or path discovery, put the literal name text in query; pattern is a content-search regex, so check any regex syntax before copying it." : "";
   return new RequestContractError({
     code: "E_MODE_FIELDS",
     mode,
     issues,
     recovery: nextRequest ? {
       action: "retry",
-      reason: `Remove only ${visibleFields} and copy the exact nextRequest; all other fields are preserved.`,
+      reason: plainFilePatternRecovery(mode, input, invalid) ? "For filename discovery, move the plain text from pattern to query and copy nextRequest; all filters are preserved." : matchAllFilePatternRecovery(mode, input, invalid) ? "A match-all pattern lists every file; omitting query does that, so copy nextRequest; all filters are preserved." : `Remove only ${visibleFields} and copy the exact nextRequest; all other fields are preserved.`,
       nextRequest
     } : {
       action: "manual",
-      reason: `${reason}; choose the mode explicitly or remove the fields yourself without changing the requested scope. ${flatRule}`
+      reason: [
+        reason,
+        filesPatternRule || "Choose the mode explicitly or remove unsupported fields without changing the requested scope.",
+        flatRule
+      ].filter(Boolean).join(" ")
     }
-  }, nextRequest ? `${reason}; retry the exact nextRequest without repeating the original query.` : `${reason}; no semantics-preserving automatic request is available. ${flatRule} Preserve valid path, filters, redact and cursor fields when choosing the next request.`);
+  }, nextRequest ? `${reason}; ${plainFilePatternRecovery(mode, input, invalid) ? "move plain filename text to query" : "retry the exact nextRequest"}.` : `${reason}; no semantics-preserving automatic request is available. ${filesPatternRule || flatRule || "Check the mode's accepted fields."}`);
 }
 function selectorIssuesFor(input, mode) {
   if ((mode === "auto" || mode === "summary" || mode === "matches") && typeof input.cursor === "string" && input.cursor.trim().length > 0 && !input.cursor.includes(".analysis")) {
@@ -1192,7 +1265,7 @@ function validateRequestContract(input) {
   const allowed = new Set(MODE_FIELDS_BY_MODE[mode]);
   if (mode === "inspect" && raw.sourceCursor !== undefined) {
     allowed.clear();
-    for (const field of ["mode", "sourceCursor", "redact"])
+    for (const field of ["mode", "sourceCursor", "redact", "path"])
       allowed.add(field);
   }
   if ((mode === "auto" || mode === "summary" || mode === "matches") && typeof raw.cursor === "string" && raw.cursor.includes(".analysis")) {
@@ -1282,25 +1355,23 @@ function modelErrorText(error) {
 function requestContractErrorText(error) {
   return requestContractProjection(error).text;
 }
-function projectRequestContract(projected, serialized, message) {
-  const prefix = `sift-light failed: request rejected [${projected.code}]: ${message}`;
+function projectRequestContract(projected, serialized) {
   const recovery = projected.recovery;
   const next = recovery.nextRequest ? `
 Copy the nested recovery.nextRequest object unchanged; do not repeat the original query.` : `
-Recovery action: ${recovery.action}. ${recovery.reason}`;
+Recovery action: ${recovery.action}.`;
   return `
-Error details: ${serialized}
-${prefix}${next}`;
+sift-light failed: request rejected [${projected.code}].
+Error details: ${serialized}${next}`;
 }
 function requestContractProjection(error) {
   const details = boundedRequestContractDetails(error.details);
   const serializedDetails = JSON.stringify(details);
-  const boundedMessage = error.message.toWellFormed().slice(0, 1024);
-  const result = projectRequestContract(details, serializedDetails, boundedMessage);
+  const result = projectRequestContract(details, serializedDetails);
   if (Buffer.byteLength(result) <= MAX_REQUEST_RECOVERY_BYTES)
     return { details, text: result };
   const compact = {
-    code: boundedMessage.length > 0 ? details.code : "E_REQUEST_CONTRACT_PAYLOAD",
+    code: details.code,
     ...details.mode ? { mode: details.mode } : {},
     issues: [
       {
@@ -1313,7 +1384,7 @@ function requestContractProjection(error) {
       reason: "Exact recovery was omitted; correct the request explicitly."
     }
   };
-  const compactText = projectRequestContract(compact, JSON.stringify(compact), "The request-contract error exceeded the bounded payload budget; correct the request explicitly.");
+  const compactText = projectRequestContract(compact, JSON.stringify(compact));
   return { details: compact, text: compactText };
 }
 
@@ -2819,7 +2890,7 @@ var CONCEPT_MODEL = "Xenova/multilingual-e5-small";
 var CONCEPT_REVISION = "761b726dd34fb83930e26aab4e9ac3899aa1fa78";
 var MAX_CONCEPT_CHARS = 1000;
 var CONCEPT_PASSAGE_OVERLAP_CHARS = 160;
-var CONCEPT_CACHE_VERSION = 1;
+var CONCEPT_CACHE_VERSION = 2;
 var CONCEPT_CACHE_MAX_BYTES = 512 * 1024 * 1024;
 var CONCEPT_TIMEOUT_MS = 10 * 60000;
 var MIN_CONCEPT_TIMEOUT_MS = 1000;
@@ -2910,7 +2981,7 @@ function normalizeRequest(input) {
     throw new SiftLightError("ignorePolicy must be respect or include");
   const pattern = input.pattern;
   if (pattern === undefined) {
-    throw new SiftLightError("pattern is required when cursor is not provided");
+    throw new SiftLightError('pattern is required when cursor is not provided; to list files use mode="files" (query optional), to read a known file use mode="inspect" with path');
   }
   const path = input.path?.replace(/^@/, "");
   return {
@@ -5142,6 +5213,11 @@ function scoreProfile(scores) {
     spread: top - min
   };
 }
+function conceptRankingScore(cosine, passageLength) {
+  const referenceLength = 500;
+  const maximumCorrection = 0.02;
+  return cosine - maximumCorrection * (1 - Math.sqrt(Math.min(passageLength / referenceLength, 1)));
+}
 function passage(document, start) {
   let end = Math.min(document.text.length, start + MAX_CONCEPT_CHARS);
   if (end < document.text.length) {
@@ -5400,6 +5476,7 @@ async function runConceptSearch(input, access, infer, onProgress, options = {})
       const similarity = inferred.scores[index];
       if (similarity === undefined)
         throw new Error("Missing concept similarity");
+      const rankingScore = conceptRankingScore(similarity, item.text.length);
       const evidence = rangeEvidence(item.document, item.range);
       return {
         path: item.document.path,
@@ -5412,7 +5489,8 @@ async function runConceptSearch(input, access, infer, onProgress, options = {})
           kind: "concept-candidate",
           certainty: "candidate",
           score: similarity,
-          rankingReason: "local multilingual E5 cosine similarity; relevance candidate, no binding or execution claim",
+          rankingScore,
+          rankingReason: "local multilingual E5 cosine similarity with bounded short-passage rank correction; relevance candidate, no binding or execution claim",
           model: CONCEPT_MODEL,
           revision: CONCEPT_REVISION,
           tokenTruncated: false,
@@ -5421,7 +5499,7 @@ async function runConceptSearch(input, access, infer, onProgress, options = {})
         }
       };
     });
-    const ranked = [...result.items, ...batchItems].toSorted((a, b) => Number(b.details?.score) - Number(a.details?.score) || a.path.localeCompare(b.path) || a.line - b.line);
+    const ranked = [...result.items, ...batchItems].toSorted((a, b) => Number(b.details?.rankingScore) - Number(a.details?.rankingScore) || a.path.localeCompare(b.path) || a.line - b.line);
     if (ranked.length > MAX_ANALYSIS_RESULTS)
       retentionTruncated = true;
     result.items = ranked.slice(0, MAX_ANALYSIS_RESULTS);
@@ -5827,7 +5905,7 @@ function publicAnalysisItem(result, item, index, storedId, modelOutput) {
   return {
     path: item.path,
     line: item.line,
-    label: result.kind === "outline" && modelOutput ? item.label : publicAnalysisLabel(result),
+    label: result.kind === "outline" && modelOutput || result.kind === "files" ? item.label : publicAnalysisLabel(result),
     index: index + 1,
     ...inspect ? { inspect } : {},
     ...publicDetails ? { details: publicDetails } : {}
@@ -6038,7 +6116,8 @@ Inspect: ${JSON.stringify(inspect)}` : ""}`;
           break;
       }
     } else {
-      for (let index = offset;index < result.items.length && items.length < 30; index += 1) {
+      const pageSize = result.pageSize ?? 30;
+      for (let index = offset;index < result.items.length && items.length < pageSize; index += 1) {
         if (!appendItem(index))
           break;
       }
@@ -6152,6 +6231,8 @@ function resolveInspectionTarget(input, cwd, snapshots) {
   }
   if (!path)
     throw new SiftLightError("path is required when mode=inspect");
+  if (line === undefined && input.cursor === undefined)
+    line = 1;
   if (line === undefined || !Number.isSafeInteger(line) || line < 1) {
     throw new SiftLightError("line must be a positive integer when mode=inspect");
   }
@@ -7880,6 +7961,28 @@ async function filterPathsByModificationTime(cwd, paths, modifiedAfterMs, modifi
 // src/file-discovery.ts
 var graphemes = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 var FILE_QUERY_GLOB_WILDCARD = /[*?]/u;
+var FILE_QUERY_MATCH_ALL = /^(?:[*/]+|\.\*|\.\+|\*\.\*)$/u;
+var FILE_QUERY_REGEX_SYNTAX = /[()|^$\\+]/u;
+var IGNORED_MATCH_SAMPLES = 5;
+function normalizeFileQuery(query, hasGlob) {
+  const trimmed = query.trim();
+  if (FILE_QUERY_MATCH_ALL.test(trimmed))
+    return {
+      query: "",
+      note: `Query ${JSON.stringify(query)} was treated as listing every file under path; omit query for the same result.`
+    };
+  if (!FILE_QUERY_GLOB_WILDCARD.test(trimmed))
+    return { query };
+  if (!hasGlob && !FILE_QUERY_REGEX_SYNTAX.test(trimmed) && !/\s/u.test(trimmed)) {
+    const glob = trimmed.includes("/") ? trimmed : `**/${trimmed}`;
+    return {
+      query: "",
+      glob,
+      note: `Query ${JSON.stringify(query)} contains glob wildcards and was applied as glob ${JSON.stringify(glob)}; mode=files query otherwise matches filename text.`
+    };
+  }
+  throw new SiftLightError(`File query ${JSON.stringify(query)} uses wildcard or regex syntax; mode=files matches filename and path text, not patterns. Omit query to retain every file under path, use glob for one name pattern, or run one files request per name.`);
+}
 function subsequenceScore(text, query) {
   const characters = Array.from(graphemes.segment(text), (item) => item.segment);
   const queryCharacters = Array.from(graphemes.segment(query), (item) => item.segment);
@@ -7930,39 +8033,79 @@ function pathRelativeToDiscoveryRoot(cwd, root, path) {
   return scoped || platformBasename(absolutePath);
 }
 async function discoverFiles(input, cwd, signal) {
-  const query = input.query ?? "";
-  if (query.length > 256 || !query.isWellFormed() || /[\r\n\0]/.test(query))
+  const rawQuery = input.query ?? "";
+  if (rawQuery.length > 256 || !rawQuery.isWellFormed() || /[\r\n\0]/.test(rawQuery))
     throw new SiftLightError("File query must be well-formed single-line text of at most 256 characters");
-  if (FILE_QUERY_GLOB_WILDCARD.test(query))
-    throw new SiftLightError(`File query ${JSON.stringify(query)} uses glob wildcards; mode=files matches filename and path text, not glob patterns. Omit query to retain every file under path, or use glob to filter by name pattern.`);
-  const request = normalizeRequest({ ...input, pattern: "" });
+  const requestedGlobs = input.glob === undefined ? [] : Array.isArray(input.glob) ? input.glob : [input.glob];
+  const normalizedQuery = normalizeFileQuery(rawQuery, requestedGlobs.length > 0);
+  const query = normalizedQuery.query;
+  const request = normalizeRequest({
+    ...input,
+    pattern: "",
+    ...normalizedQuery.glob ? { glob: [...requestedGlobs, normalizedQuery.glob] } : {}
+  });
   const policy = new SearchPathPolicy(cwd);
   const discoveryRoot = request.path ?? ".";
   const scoringRoot = await policy.resolveSearchTarget(discoveryRoot);
-  const files = await listWorkspaceFiles(cwd, signal, {
+  const includeIgnored = request.ignorePolicy === "include";
+  const listOptions = {
     path: scoringRoot,
     glob: request.glob,
     exclude: request.exclude,
     hidden: request.hidden
+  };
+  const files = await listWorkspaceFiles(cwd, signal, {
+    ...listOptions,
+    ...includeIgnored ? { ignore: false, ignoreParents: false } : {}
   });
   const filtered = await filterPathsByModificationTime(cwd, files.paths, request.modifiedAfterMs, request.modifiedBeforeMs, signal);
+  const rank = (path) => scoreFilePath(pathRelativeToDiscoveryRoot(cwd, scoringRoot, path), query);
   const selected = filtered.paths.flatMap((path) => {
-    const rank = scoreFilePath(pathRelativeToDiscoveryRoot(cwd, scoringRoot, path), query);
-    return rank ? [{ path, ...rank }] : [];
+    const score = rank(path);
+    return score ? [{ path, ...score }] : [];
   }).toSorted((left, right) => right.score - left.score || left.path.localeCompare(right.path));
   for (let offset = 0;offset < selected.length; offset += 16) {
     await Promise.all(selected.slice(offset, offset + 16).map((item) => policy.assertExistingPath(item.path)));
     signal?.throwIfAborted();
   }
+  const reasons = new Set([...files.reasons, ...filtered.reasons]);
+  if (normalizedQuery.note)
+    reasons.add(normalizedQuery.note);
+  let ignoredFiles = 0;
+  let ignoredMatches = 0;
+  let ignoredComparisonPartial = false;
+  if (!includeIgnored) {
+    const everything = await listWorkspaceFiles(cwd, signal, {
+      ...listOptions,
+      ignore: false,
+      ignoreParents: false
+    });
+    ignoredComparisonPartial = everything.partial;
+    const admitted = new Set(files.paths);
+    const ignored = everything.paths.filter((path) => !admitted.has(path));
+    ignoredFiles = ignored.length;
+    const ignoredCandidates = ignored.flatMap((path) => {
+      const score = rank(path);
+      return score ? [{ path, ...score }] : [];
+    }).toSorted((left, right) => right.score - left.score || left.path.localeCompare(right.path));
+    ignoredMatches = ignoredCandidates.length;
+    if (ignoredFiles > 0) {
+      const samples = ignoredCandidates.slice(0, IGNORED_MATCH_SAMPLES).map((item) => `${JSON.stringify(item.path)} (${item.reason})`);
+      reasons.add(ignoredMatches > 0 ? `${String(ignoredFiles)} file(s) were excluded by ignore rules; ${String(ignoredMatches)} of them match this query${samples.length ? `, e.g. ${samples.join(", ")}` : ""}. Retry with ignorePolicy "include" to list them.` : `${String(ignoredFiles)} file(s) were excluded by ignore rules; none of them match this query.`);
+    }
+    if (ignoredComparisonPartial)
+      reasons.add("Ignored-file comparison was incomplete; the ignored-file count is a lower bound");
+  }
+  const enumerationPartial = files.partial || filtered.partial;
   return {
     kind: "files",
     unit: "files",
-    partial: files.partial || filtered.partial,
-    reasons: [...new Set([...files.reasons, ...filtered.reasons])],
+    partial: enumerationPartial,
+    reasons: [...reasons],
     items: selected.map((item) => ({
       path: item.path,
       line: 1,
-      label: `File candidate (${item.reason})`,
+      label: `File candidate (score ${String(item.score)}: ${item.reason})`,
       details: {
         kind: "file",
         score: item.score,
@@ -7970,8 +8113,13 @@ async function discoverFiles(input, cwd, signal) {
         inspect: { mode: "inspect", path: item.path, line: 1 }
       }
     })),
-    coverage: { fileEnumeration: files.partial || filtered.partial ? "partial" : "complete" },
-    stats: { filesEnumerated: files.paths.length },
+    coverage: {
+      fileEnumeration: enumerationPartial ? "partial" : ignoredFiles > 0 || ignoredComparisonPartial ? "policy-filtered" : "complete"
+    },
+    stats: {
+      filesEnumerated: files.paths.length,
+      ...includeIgnored ? {} : { ignoredFiles, ignoredMatches }
+    },
     scope: {
       path: request.path ?? ".",
       requestedPath: request.path ?? ".",
@@ -7984,7 +8132,8 @@ async function discoverFiles(input, cwd, signal) {
       ...request.modifiedAfterMs !== undefined ? { modifiedAfterMs: request.modifiedAfterMs } : {},
       ...request.modifiedBeforeMs !== undefined ? { modifiedBeforeMs: request.modifiedBeforeMs } : {}
     },
-    redact: input.redact ?? false
+    redact: input.redact ?? false,
+    ...input.limit !== undefined ? { pageSize: request.pageSize } : {}
   };
 }
 
@@ -8225,7 +8374,19 @@ async function prepare(target, access, structure) {
   let range = target.range;
   let details = { status: "no-symbol" };
   const language = syntaxLanguage(document.path);
-  if (document.utf8 && language && language !== "go") {
+  if (target.range && target.structure) {
+    document.checkRange(target.range);
+    const lines = {
+      startLine: document.lineAt(target.range.start),
+      endLine: document.lineAt(Math.max(target.range.start, target.range.end - 1))
+    };
+    range = document.lineRange(lines.startLine, lines.endLine);
+    details = {
+      ...target.structure,
+      range: lines,
+      ...target.structure.symbol ? { symbol: { ...target.structure.symbol, range: lines } } : {}
+    };
+  } else if (document.utf8 && language && language !== "go") {
     const syntax = await access.syntax(document);
     details = {
       status: syntax.status === "ok" ? "no-symbol" : syntax.status === "unsupported" ? "provider-unavailable" : "parse-error",
@@ -8277,7 +8438,7 @@ async function prepare(target, access, structure) {
     details = { status: "provider-unavailable", ...language ? { language } : {} };
   }
   range ??= document.lineRange(Math.max(1, target.line - 10), Math.min(document.lineStarts.length, target.line + 10));
-  const boundary = target.range ? "requested-range" : details.status === "available" && details.range ? "syntax" : "line-window";
+  const boundary = target.range ? target.structure ? "syntax" : "requested-range" : details.status === "available" && details.range ? "syntax" : "line-window";
   document.checkRange(range);
   return { target, document, range, structure: details, boundary, focus };
 }
@@ -8636,8 +8797,10 @@ ${preview.text}`);
     }
   };
 }
-async function continueSource(cursor, access, continuations) {
+async function continueSource(cursor, access, continuations, expectedPath) {
   const state = continuations.resolve(cursor);
+  if (expectedPath !== undefined && resolve18(access.cwd, expectedPath.replace(/^@/, "")) !== resolve18(access.cwd, state.source.path))
+    throw new SiftLightError(`sourceCursor continues ${JSON.stringify(state.source.path)}, not ${JSON.stringify(expectedPath)}; copy the returned nextRequest exactly`);
   const document = await access.load(state.source.path, state.source);
   const page = sourcePage(document, state.remaining, MAX_RESULT_BYTES - 1400);
   const next = continuations.advance(cursor, page.fragment);
@@ -9514,9 +9677,378 @@ function parsePythonOutline(document) {
   });
 }
 
+// src/python-roles.ts
+var KEYWORDS = new Set([
+  "and",
+  "as",
+  "assert",
+  "async",
+  "await",
+  "case",
+  "del",
+  "elif",
+  "else",
+  "except",
+  "for",
+  "from",
+  "global",
+  "if",
+  "import",
+  "in",
+  "is",
+  "lambda",
+  "match",
+  "nonlocal",
+  "not",
+  "or",
+  "raise",
+  "return",
+  "while",
+  "with",
+  "yield"
+]);
+var STRING_PREFIX = /^(?:[rRbBuUfF]|[rR][bBfF]|[bBfF][rR])?$/u;
+var IDENTIFIER_START = /[\p{ID_Start}_]/u;
+var IDENTIFIER_PART = /[\p{ID_Continue}]/u;
+function lex(text) {
+  const comments = [];
+  const strings = [];
+  const code = new Uint8Array(text.length).fill(1);
+  const mark = (start, end) => {
+    code.fill(0, start, end);
+  };
+  let index = 0;
+  while (index < text.length) {
+    const character = text[index];
+    if (character === "#") {
+      const newline = text.indexOf(`
+`, index);
+      const end = newline < 0 ? text.length : newline;
+      comments.push({ start: index, end });
+      mark(index, end);
+      index = end;
+      continue;
+    }
+    if (character !== "'" && character !== '"') {
+      index += 1;
+      continue;
+    }
+    let prefixStart = index;
+    while (prefixStart > 0 && /[rRbBuUfF]/u.test(text[prefixStart - 1] ?? ""))
+      prefixStart -= 1;
+    const prefix = text.slice(prefixStart, index);
+    const beforePrefix = text[prefixStart - 1] ?? "";
+    const start = STRING_PREFIX.test(prefix) && !IDENTIFIER_PART.test(beforePrefix) ? prefixStart : index;
+    const triple = text.slice(index, index + 3) === character.repeat(3);
+    const delimiter = triple ? character.repeat(3) : character;
+    let cursor = index + delimiter.length;
+    let end = text.length;
+    while (cursor < text.length) {
+      const current = text[cursor];
+      if (current === "\\") {
+        cursor += 2;
+        continue;
+      }
+      if (!triple && current === `
+`) {
+        end = cursor;
+        break;
+      }
+      if (text.startsWith(delimiter, cursor)) {
+        end = cursor + delimiter.length;
+        break;
+      }
+      cursor += 1;
+    }
+    strings.push({ start, end });
+    mark(start, end);
+    index = end;
+  }
+  return { comments, strings, code };
+}
+function codeRanges(code) {
+  const ranges = [];
+  let start = -1;
+  for (let index = 0;index <= code.length; index += 1) {
+    const inCode = index < code.length && code[index] === 1;
+    if (inCode && start < 0)
+      start = index;
+    else if (!inCode && start >= 0) {
+      ranges.push({ start, end: index });
+      start = -1;
+    }
+  }
+  return ranges;
+}
+function identifierEnd(text, start) {
+  let end = start;
+  while (end < text.length && IDENTIFIER_PART.test(text[end] ?? ""))
+    end += 1;
+  return end;
+}
+function skipSpaces(text, index, code) {
+  let cursor = index;
+  while (cursor < text.length && code[cursor] === 1 && /[ \t]/u.test(text[cursor] ?? ""))
+    cursor += 1;
+  return cursor;
+}
+function statementEnd(text, start, code) {
+  let depth = 0;
+  for (let index = start;index < text.length; index += 1) {
+    if (code[index] !== 1)
+      continue;
+    const character = text[index];
+    if (character === "(" || character === "[" || character === "{")
+      depth += 1;
+    else if (character === ")" || character === "]" || character === "}")
+      depth = Math.max(0, depth - 1);
+    else if (character === "\\" && text[index + 1] === `
+`)
+      index += 1;
+    else if (character === `
+` && depth === 0)
+      return index;
+  }
+  return text.length;
+}
+function pythonRoleAnalysis(document) {
+  const text = document.text;
+  const { comments, strings, code } = lex(text);
+  const roles = [];
+  const push = (start, end, role, certainty, subkind) => {
+    if (start < end)
+      roles.push({ start, end, role, certainty, node: 0, ...subkind ? { subkind } : {} });
+  };
+  for (const span of comments)
+    push(span.start, span.end, "comment", "syntax");
+  for (const span of strings)
+    push(span.start, span.end, "string", "syntax");
+  for (const span of codeRanges(code))
+    push(span.start, span.end, "code", "syntax");
+  let index = 0;
+  let lineStart = true;
+  while (index < text.length) {
+    const character = text[index] ?? "";
+    if (character === `
+`) {
+      lineStart = true;
+      index += 1;
+      continue;
+    }
+    if (code[index] !== 1 || !IDENTIFIER_START.test(character)) {
+      if (!/[ \t]/u.test(character))
+        lineStart = false;
+      index += 1;
+      continue;
+    }
+    const previous = text[index - 1] ?? "";
+    if (IDENTIFIER_PART.test(previous)) {
+      index += 1;
+      continue;
+    }
+    const end = identifierEnd(text, index);
+    const word = text.slice(index, end);
+    const atStatementStart = lineStart;
+    lineStart = false;
+    if (atStatementStart && (word === "import" || word === "from")) {
+      const statement = statementEnd(text, index, code);
+      const body = text.slice(index, statement);
+      if (word === "import" || /\bimport\b/u.test(body)) {
+        push(index, statement, "import", "syntax", word === "from" ? "from-import" : "import");
+        index = statement;
+        continue;
+      }
+    }
+    if (word === "def" || word === "class") {
+      const nameStart = skipSpaces(text, end, code);
+      if (IDENTIFIER_START.test(text[nameStart] ?? "")) {
+        const nameEnd = identifierEnd(text, nameStart);
+        push(nameStart, nameEnd, "declaration", "syntax", word === "def" ? "function" : "class");
+        index = nameEnd;
+        continue;
+      }
+    }
+    let chainEnd = end;
+    while (text[chainEnd] === "." && IDENTIFIER_START.test(text[chainEnd + 1] ?? "")) {
+      chainEnd = identifierEnd(text, chainEnd + 1);
+    }
+    const open = skipSpaces(text, chainEnd, code);
+    const lastSegment = text.slice(text.lastIndexOf(".", chainEnd - 1) + 1, chainEnd);
+    const before = text.slice(Math.max(0, index - 4), index);
+    if (text[open] === "(" && code[open] === 1 && !KEYWORDS.has(word) && !KEYWORDS.has(lastSegment) && !/\bdef\s+$|\bclass\s+$/u.test(before)) {
+      push(index, open + 1, "call", "candidate", "lexical-call");
+    }
+    index = chainEnd;
+  }
+  roles.sort((a, b) => a.start - b.start || a.end - b.end || a.role.localeCompare(b.role));
+  return {
+    status: "ok",
+    nodes: [],
+    children: [],
+    symbols: [],
+    roles,
+    diagnostics: [],
+    limited: false
+  };
+}
+
 // src/hybrid-search.ts
 import { resolve as resolve20 } from "node:path";
 
+// src/config-reader.ts
+import { readFile as readFile2 } from "node:fs/promises";
+var SIFT_LIGHT_CONFIG_ENV = "SIFT_LIGHT_CONFIG";
+var SEMANTIC_JUDGE_API_KEY_ENVS = ["TYPESAFE_API_KEY", "SIFT_LIGHT_JEV_API_KEY"];
+var DEFAULT_SEMANTIC_JUDGE_CONFIG = {
+  enabled: false,
+  provider: "jev",
+  endpoint: "https://api.typesafe.ai/v1/systemone",
+  apiKeyEnv: SEMANTIC_JUDGE_API_KEY_ENVS[0],
+  model: "jev-latest",
+  timeoutMs: 120000,
+  maxCandidates: 20,
+  maxRetries: 2
+};
+var DEFAULT_SIFT_LIGHT_CONFIG = {
+  locale: "en",
+  enforceSearch: "hard",
+  vectorSearchEnabled: false,
+  semanticJudge: DEFAULT_SEMANTIC_JUDGE_CONFIG
+};
+function hasErrorCode(error, codes) {
+  return error instanceof Error && "code" in error && codes.includes(String(error.code));
+}
+function isMissingFile(error) {
+  return hasErrorCode(error, ["ENOENT"]);
+}
+function isRawSiftLightConfig(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRawSemanticJudgeConfig(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function boundedInteger2(value, fallback, minimum, maximum, field) {
+  const candidate = value ?? fallback;
+  if (typeof candidate !== "number" || !Number.isSafeInteger(candidate) || candidate < minimum || candidate > maximum) {
+    throw new Error(`Invalid sift-light ${field}: expected an integer from ${String(minimum)} through ${String(maximum)}`);
+  }
+  return candidate;
+}
+function parseSemanticJudge(value, path) {
+  if (value === undefined)
+    return { ...DEFAULT_SEMANTIC_JUDGE_CONFIG };
+  if (!isRawSemanticJudgeConfig(value)) {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge must be an object`);
+  }
+  const unknown = Object.keys(value).filter((key) => ![
+    "enabled",
+    "provider",
+    "endpoint",
+    "apiKeyEnv",
+    "model",
+    "timeoutMs",
+    "maxCandidates",
+    "maxRetries"
+  ].includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`Invalid sift-light config at ${path}: unsupported semanticJudge fields; accepted fields are enabled, provider, endpoint, apiKeyEnv, model, timeoutMs, maxCandidates and maxRetries`);
+  }
+  const enabled = value.enabled ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.enabled;
+  if (typeof enabled !== "boolean") {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.enabled must be a boolean`);
+  }
+  const provider = value.provider ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.provider;
+  if (provider !== "jev") {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.provider must be "jev"`);
+  }
+  const endpoint = value.endpoint ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.endpoint;
+  if (typeof endpoint !== "string" || endpoint.length === 0 || endpoint.length > 2048) {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.endpoint must be a nonempty URL`);
+  }
+  let parsedEndpoint;
+  try {
+    parsedEndpoint = new URL(endpoint);
+  } catch (error) {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.endpoint must be a URL`, {
+      cause: error
+    });
+  }
+  const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
+  const secureEndpoint = parsedEndpoint.protocol === "https:" || parsedEndpoint.protocol === "http:" && loopbackHosts.has(parsedEndpoint.hostname);
+  if (!secureEndpoint || parsedEndpoint.username || parsedEndpoint.password) {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.endpoint must use HTTPS, except that HTTP is allowed for localhost loopback development; URL credentials are not allowed`);
+  }
+  const apiKeyEnv = value.apiKeyEnv ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.apiKeyEnv;
+  if (typeof apiKeyEnv !== "string" || !/^[A-Z][A-Z0-9_]{0,127}$/u.test(apiKeyEnv)) {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.apiKeyEnv must be an uppercase environment variable name`);
+  }
+  const model = value.model ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.model;
+  if (typeof model !== "string" || model.length === 0 || model.length > 128 || /[\r\n\0]/u.test(model)) {
+    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.model must be bounded single-line text`);
+  }
+  return {
+    enabled,
+    provider,
+    endpoint,
+    apiKeyEnv,
+    model,
+    timeoutMs: boundedInteger2(value.timeoutMs, DEFAULT_SEMANTIC_JUDGE_CONFIG.timeoutMs, 1000, 1200000, `config at ${path}: semanticJudge.timeoutMs`),
+    maxCandidates: boundedInteger2(value.maxCandidates, DEFAULT_SEMANTIC_JUDGE_CONFIG.maxCandidates, 1, 20, `config at ${path}: semanticJudge.maxCandidates`),
+    maxRetries: boundedInteger2(value.maxRetries, DEFAULT_SEMANTIC_JUDGE_CONFIG.maxRetries, 0, 5, `config at ${path}: semanticJudge.maxRetries`)
+  };
+}
+function parseConfig(value, path) {
+  if (!isRawSiftLightConfig(value)) {
+    throw new Error(`Invalid sift-light config at ${path}: expected a JSON object`);
+  }
+  const unknown = Object.keys(value).filter((key) => !["locale", "enforceSearch", "vectorSearchEnabled", "semanticJudge"].includes(key));
+  if (unknown.length > 0) {
+    throw new Error(`Invalid sift-light config at ${path}: unsupported configuration fields; only locale, enforceSearch, vectorSearchEnabled and semanticJudge are accepted`);
+  }
+  const { locale, enforceSearch, vectorSearchEnabled } = value;
+  if (locale !== undefined && locale !== "en" && locale !== "zh-CN") {
+    throw new Error(`Invalid sift-light config at ${path}: locale must be "en" or "zh-CN"`);
+  }
+  if (vectorSearchEnabled !== undefined && typeof vectorSearchEnabled !== "boolean") {
+    throw new Error(`Invalid sift-light config at ${path}: vectorSearchEnabled must be a boolean`);
+  }
+  const enforcement = normalizeSearchEnforcement(enforceSearch, `config at ${path}`);
+  return {
+    locale: locale ?? DEFAULT_SIFT_LIGHT_CONFIG.locale,
+    enforceSearch: enforcement,
+    vectorSearchEnabled: vectorSearchEnabled ?? DEFAULT_SIFT_LIGHT_CONFIG.vectorSearchEnabled ?? false,
+    semanticJudge: parseSemanticJudge(value.semanticJudge, path)
+  };
+}
+function normalizeSearchEnforcement(value, source) {
+  if (value === undefined || value === "hard")
+    return "hard";
+  if (value === "prefer")
+    return "prefer";
+  if (value === "off")
+    return "off";
+  throw new Error(`Invalid sift-light ${source}: enforceSearch must be "hard", "prefer", or "off"`);
+}
+async function readSiftLightConfigFile(path, options = {}) {
+  try {
+    const content = await readFile2(path, "utf8");
+    return parseConfig(JSON.parse(content), path);
+  } catch (error) {
+    if (isMissingFile(error)) {
+      if (options.missing === "error") {
+        throw new Error(`sift-light config was not found at ${path}; create it or unset ${SIFT_LIGHT_CONFIG_ENV}`, { cause: error });
+      }
+      return { ...DEFAULT_SIFT_LIGHT_CONFIG };
+    }
+    if (error instanceof SyntaxError) {
+      throw new Error(`Invalid sift-light config at ${path}: ${error.message}`, {
+        cause: error
+      });
+    }
+    throw error;
+  }
+}
+
 // src/semantic-judge-batches.ts
 var MAX_SEMANTIC_JUDGE_BATCH_CANDIDATES = 8;
 var MAX_SEMANTIC_JUDGE_REQUEST_BYTES = 64 * 1024;
@@ -9664,7 +10196,7 @@ function requestBody(query, candidates, model) {
   for (const candidate of candidates) {
     questions[candidate.id] = {
       type: "choice",
-      instructions: "Classify the candidate by what it actually does for the requested behavior. Judge the code excerpt, not just matching words.",
+      instructions: `Classify only candidate ${candidate.id} in state.candidates for state.query. Judge that candidate's excerpt by its actual behavior, not by matching words or the other candidates.`,
       criteria: {
         "implementation-candidate": "The excerpt appears to implement the requested behavior or its core decision/side effect.",
         "caller-candidate": "The excerpt invokes or wires an implementation but does not implement the behavior itself.",
@@ -9827,6 +10359,10 @@ function createSemanticJudgeIntegration(config, environment = process.env, fetch
   }
   return { config, runner: createJevRunner(config, key, fetcher) };
 }
+function createConfiguredSemanticJudgeIntegration(config, environment = process.env) {
+  const judge = config.semanticJudge ?? DEFAULT_SEMANTIC_JUDGE_CONFIG;
+  return config.vectorSearchEnabled === true ? createSemanticJudgeIntegration(judge, environment) : createDisabledSemanticJudgeIntegration(judge);
+}
 function baseDetails(config) {
   return {
     enabled: config.enabled,
@@ -10133,6 +10669,9 @@ async function combineHybridSearch(scan, execution, access, conceptLimit, query,
   const deduplicationCoverage = scan.snapshotComplete && literal.sourceCoverage === "complete" && conceptSourceCoverage === "complete" ? "complete" : "partial";
   const partial = !scan.snapshotComplete || concept.partial || conceptCoverage === "skipped" || conceptSourceCoverage === "partial" || literal.sourceCoverage === "partial" || deduplicationCoverage === "partial" || judgedConcept.semanticJudge?.status === "failed" || judgedConcept.semanticJudge?.status === "partial";
   const selectionReason = conceptCandidatesOmitted ? `Hybrid concept limit retained the top ${String(selectedConcept.length)} of ${String(eligibleConcept.length)} non-overlapping semantic candidates` : undefined;
+  const firstScore = Number(eligibleConcept[0]?.details?.rankingScore ?? eligibleConcept[0]?.details?.score);
+  const secondScore = Number(eligibleConcept[1]?.details?.rankingScore ?? eligibleConcept[1]?.details?.score);
+  const closeRanking = Number.isFinite(firstScore) && Number.isFinite(secondScore) && firstScore - secondScore < 0.01;
   return {
     kind: "hybrid",
     unit: "evidence-items",
@@ -10144,6 +10683,9 @@ async function combineHybridSearch(scan, execution, access, conceptLimit, query,
       ...literal.reasons,
       ...execution.sourceGeneration.reasons,
       ...selectionReason ? [selectionReason] : [],
+      ...closeRanking ? [
+        "Semantic ranks are close; verify the leading candidates with source inspection or literal terms."
+      ] : [],
       ...judgedConcept.semanticJudge?.reason ? [judgedConcept.semanticJudge.reason] : []
     ],
     filesRead: (concept.filesRead ?? 0) + access.filesRead,
@@ -10297,6 +10839,69 @@ import { realpath as realpath6 } from "node:fs/promises";
 function isEvidenceRequest(input) {
   return input.mode === "concept" || input.mode === "hybrid" || input.mode === "structure" || input.mode === "files" || input.mode === "inspect" || input.mode === "outline" || input.mode === "imports" || input.mode === "tests" || input.mode === "validate" || input.sourceCursor !== undefined || input.anyOf !== undefined || input.allOf !== undefined || input.within !== undefined || input.roles !== undefined || input.changes !== undefined || input.symbol !== undefined || input.conceptLimit !== undefined || (input.cursor?.includes(".analysis") ?? false);
 }
+function pageInspectRequest(input) {
+  if (input.scope === "expand")
+    throw new SiftLightError("mode=inspect reads exact locations; scope=expand does not apply (omit scope)");
+  const { scope: _scope, paths, ...rest } = input;
+  let request = rest;
+  if (paths !== undefined) {
+    if (input.cursor !== undefined || input.targets !== undefined || input.matchIndices !== undefined || input.path !== undefined || input.line !== undefined || input.matchIndex !== undefined)
+      throw new SiftLightError("mode=inspect paths opens files from line 1 and cannot be combined with cursor, targets, matchIndices, path, line or matchIndex");
+    request = { ...rest, targets: paths.map((path) => ({ path, line: 1 })) };
+  }
+  const redact = input.redact ? { redact: true } : {};
+  const requested = request.targets?.length ?? request.matchIndices?.length ?? 0;
+  if (requested > MAX_INSPECT_REQUEST_TARGETS)
+    throw new SiftLightError(`mode=inspect accepts at most ${String(MAX_INSPECT_REQUEST_TARGETS)} targets per request; ${String(MAX_INSPECT_TARGETS)} are inspected per response`);
+  if (request.targets && request.targets.length > MAX_INSPECT_TARGETS)
+    return {
+      current: { ...request, targets: request.targets.slice(0, MAX_INSPECT_TARGETS) },
+      remaining: {
+        mode: "inspect",
+        targets: request.targets.slice(MAX_INSPECT_TARGETS),
+        ...redact
+      }
+    };
+  if (request.matchIndices && request.matchIndices.length > MAX_INSPECT_TARGETS)
+    return {
+      current: { ...request, matchIndices: request.matchIndices.slice(0, MAX_INSPECT_TARGETS) },
+      remaining: {
+        mode: "inspect",
+        ...request.cursor !== undefined ? { cursor: request.cursor } : {},
+        matchIndices: request.matchIndices.slice(MAX_INSPECT_TARGETS),
+        ...redact
+      }
+    };
+  return { current: request };
+}
+function withRemainingInspection(result, remaining) {
+  const count = remaining.targets?.length ?? remaining.matchIndices?.length ?? 0;
+  return {
+    text: `${result.text}
+
+[${String(count)} more target(s) were not inspected; one response inspects ${String(MAX_INSPECT_TARGETS)}.]
+Next request: ${JSON.stringify(remaining)}`,
+    details: {
+      ...result.details,
+      status: "partial",
+      snapshotComplete: false,
+      nextRequest: remaining
+    }
+  };
+}
+function analysisItemStructure(item) {
+  const details = item.details ?? {};
+  const language = typeof details.language === "string" ? details.language : undefined;
+  const name = typeof details.name === "string" ? details.name : undefined;
+  const scope = Array.isArray(details.scope) ? details.scope.filter((entry) => typeof entry === "string") : typeof details.scope === "string" ? [details.scope] : [];
+  const kind = details.kind === "function" ? "function" : item.label.split(" ", 1)[0] ?? "symbol";
+  return {
+    status: "available",
+    provider: language === "python" ? "python-outline" : "tree-sitter",
+    ...language ? { language } : {},
+    ...name ? { symbol: { name, kind, scope, range: { startLine: item.line, endLine: item.line } } } : {}
+  };
+}
 function maxFilesToParse(value, defaultValue = MAX_STRUCTURE_FILES) {
   const candidate = value ?? defaultValue;
   if (!Number.isSafeInteger(candidate) || candidate < 1 || candidate > MAX_CONFIGURABLE_STRUCTURE_FILES) {
@@ -10312,8 +10917,8 @@ function validateTerms(input) {
     }
     return;
   }
-  if (!Array.isArray(terms) || terms.length < 2 || terms.length > 3 || terms.some((term) => typeof term !== "string" || !term.trim() || /[\r\n\0]/.test(term)) || new Set(terms).size !== terms.length)
-    throw new SiftLightError("allOf requires 2–3 distinct, nonempty, single-line literal terms");
+  if (!Array.isArray(terms) || terms.length < 1 || terms.length > 3 || terms.some((term) => typeof term !== "string" || !term.trim() || /[\r\n\0]/.test(term)) || new Set(terms).size !== terms.length)
+    throw new SiftLightError("allOf requires 1–3 distinct, nonempty, single-line literal terms");
   if (input.pattern !== undefined || input.roles !== undefined || input.literal !== undefined || input.ignoreCase !== undefined || input.wholeWord !== undefined)
     throw new SiftLightError("allOf is an explicit case-sensitive literal conjunction; omit pattern, roles, literal and ignoreCase");
   if (input.within !== undefined && input.within !== "file" && input.within !== "function")
@@ -10511,11 +11116,13 @@ class EvidenceService {
         throw new CursorError("A nonempty sourceCursor is required");
       if (input.mode !== "inspect")
         throw new SiftLightError("sourceCursor requires mode=inspect");
-      return continueSource(input.sourceCursor, access, this.#continuations);
+      return continueSource(input.sourceCursor, access, this.#continuations, input.path);
     }
     if (input.mode === "inspect") {
-      const targets = this.#inspectionTargets(input, cwd);
-      return targets.some((target) => target.range !== undefined) ? inspectDocumentsMetadata(targets, access, this.#structure) : inspectDocuments(targets, access, this.#continuations, this.#structure);
+      const { current, remaining } = pageInspectRequest(input);
+      const targets = this.#inspectionTargets(current, cwd);
+      const result = await inspectDocuments(targets, access, this.#continuations, this.#structure);
+      return remaining ? withRemainingInspection(result, remaining) : result;
     }
     if (input.mode === "concept") {
       const execution = await this.#conceptSearch(input, access, options.onProgress);
@@ -10604,7 +11211,7 @@ class EvidenceService {
       if (input.pattern !== undefined || input.allOf !== undefined || input.within !== undefined || input.roles !== undefined || input.literal !== undefined || input.ignoreCase !== undefined || input.wholeWord !== undefined)
         throw new SiftLightError("anyOf is an explicit case-sensitive literal union; omit pattern, allOf, within, roles, literal and ignoreCase");
       if (input.mode !== undefined && input.mode !== "auto" && input.mode !== "matches")
-        throw new SiftLightError("anyOf mode must be omitted, auto, or matches");
+        throw new SiftLightError("anyOf mode must be omitted, auto, matches or summary");
       const chunks = Array.from({ length: Math.ceil(anyOf.length / MAX_ANY_OF_TERMS) }, (_, index) => anyOf.slice(index * MAX_ANY_OF_TERMS, (index + 1) * MAX_ANY_OF_TERMS));
       const { path: _inputPath, ...unscopedInput } = input;
       let chunkAccess = access;
@@ -10742,9 +11349,10 @@ class EvidenceService {
           if (item)
             result.items.push(item);
         } else if (terms || input.roles) {
-          if (syntaxLanguage(file.document.path))
+          const pythonRoles = !terms && /\.py$/iu.test(file.document.path);
+          if (pythonRoles || syntaxLanguage(file.document.path))
             syntaxCapableFiles += 1;
-          const syntax = await access.syntax(file.document);
+          const syntax = pythonRoles ? pythonRoleAnalysis(file.document) : await access.syntax(file.document);
           const classified = terms ? findFunctionConjunctions(file.document, syntax, terms, input.changes?.scope === "lines" ? file.changedRanges : undefined) : filterRoleOccurrences(file.document, syntax, file.occurrences, input.roles ?? []);
           result.items.push(...classified.items);
           result.partial ||= classified.partial;
@@ -10821,12 +11429,12 @@ class EvidenceService {
       const item = this.#analyses.item(input.cursor, input.matchIndex);
       if (!item.source || !item.range)
         throw new CursorError("This analysis item has no verified source range");
-      const metadataOnly = item.details?.kind === "symbol" || item.details?.kind === "function";
+      const bounded = item.details?.kind === "symbol" || item.details?.kind === "function";
       return {
         path: item.path,
         line: item.line,
         reference: item.source,
-        ...metadataOnly ? { range: item.range } : { absoluteFocus: item.range.start }
+        ...bounded ? { range: item.range, structure: analysisItemStructure(item) } : { absoluteFocus: item.range.start }
       };
     }
     return {
@@ -11035,8 +11643,31 @@ import { resolve as resolve24 } from "node:path";
 // src/discovery-errors.ts
 var DISCOVERY_MODE_REQUIRED_ERROR = 'query requires an explicit discovery mode: use mode=files for filename/path discovery or mode=concept for semantic discovery; for example {"mode":"files","query":"<filename-or-path>"}';
 
+// src/request-aliases.ts
+var MODE_ALIASES = ["anyOf", "allOf"];
+function normalizeRequestAliases(request) {
+  const notes = [];
+  const { mode, ...rest } = request;
+  let input = rest;
+  if (mode === "anyOf" || mode === "allOf") {
+    if (request[mode] === undefined)
+      throw new SiftLightError(`mode=${mode} is not a mode; pass ${mode}:[...terms] and omit mode`);
+    notes.push(`mode="${mode}" is not a mode; the ${mode} field alone selects this search.`);
+  } else if (mode === "summary" && request.anyOf !== undefined) {
+    notes.push("anyOf returns one analysis page whose header already carries per-file statistics; mode=summary was served by that page.");
+  } else if (mode !== undefined) {
+    input = { ...rest, mode };
+  }
+  if (input.sourceCursor !== undefined && input.line !== undefined) {
+    const { line: _line, ...withoutLine } = input;
+    input = withoutLine;
+    notes.push("line is ignored with sourceCursor; the continuation selects its own source range.");
+  }
+  return { input, notes };
+}
+
 // src/format.ts
-import { readFile as readFile2 } from "node:fs/promises";
+import { readFile as readFile3 } from "node:fs/promises";
 var RESULT_METADATA_RESERVE_BYTES = 1024;
 var RESULT_METADATA_RESERVE_CHARACTERS = 512;
 
@@ -11170,7 +11801,7 @@ async function loadContextLines(match, expectedRevision, cache, signal) {
       cache.set(match.absolutePath, changed);
       return changed;
     }
-    const content = await readFile2(match.absolutePath, { encoding: "utf8", signal });
+    const content = await readFile3(match.absolutePath, { encoding: "utf8", signal });
     const afterRevision = await getSourceRevision(match.absolutePath);
     if (!afterRevision || !sameSourceRevision(expectedRevision, afterRevision)) {
       const changed = { status: "changed" };
@@ -12388,6 +13019,16 @@ class LanguageCapabilityCatalog {
 }
 
 // src/service.ts
+function withRequestNotes(result, notes) {
+  if (notes.length === 0)
+    return result;
+  return {
+    text: `${notes.map((note) => `[Request note: ${note}]`).join(`
+`)}
+${result.text}`,
+    details: { ...result.details, requestNotes: [...notes] }
+  };
+}
 function filterList(value) {
   return value === undefined ? [] : Array.isArray(value) ? [...value] : [value];
 }
@@ -12601,6 +13242,7 @@ class SiftLightService {
   #runRipgrep;
   #snapshots;
   #summaryFileLimit;
+  #vectorSearchEnabled;
   #capabilities = new LanguageCapabilityCatalog;
   #evidence;
   #lifecycle = new AbortController;
@@ -12611,12 +13253,20 @@ class SiftLightService {
     this.#runRipgrep = options.runRipgrep;
     this.#snapshots = options.snapshots ?? new SnapshotStore;
     this.#summaryFileLimit = options.summaryFileLimit ?? DEFAULT_SUMMARY_FILE_LIMIT;
+    this.#vectorSearchEnabled = options.vectorSearchEnabled ?? options.conceptSearch !== undefined;
     this.#operations = new OperationLifecycle({ deadlineMs: resolveConceptTimeoutMs() });
     this.#evidence = new EvidenceService(this.#runRipgrep, this.#snapshots, options.structure, options.conceptSearch, options.semanticJudge);
   }
-  async search(input, cwd, signal, options = {}) {
+  async search(request, cwd, signal, options = {}) {
+    const { input, notes } = normalizeRequestAliases(request);
+    return withRequestNotes(await this.#searchNormalized(input, cwd, signal, options), notes);
+  }
+  async#searchNormalized(input, cwd, signal, options) {
     validateRawSearchInput(input);
     validateRequestContract(input);
+    if (!this.#vectorSearchEnabled && (input.mode === "concept" || input.mode === "hybrid")) {
+      throw new SiftLightError(`${input.mode} search is disabled; set vectorSearchEnabled to true in sift-light.json and restart the host`);
+    }
     let request;
     if (input.mode === "await" || input.mode === "cancel") {
       request = this.#operationCommand(input, cwd, signal);
@@ -13015,160 +13665,11 @@ ${page.body}${rangeNote}${contextNote}${missingSelectionNote}
   }
 }
 
-// src/config-reader.ts
-import { readFile as readFile3 } from "node:fs/promises";
-var SIFT_LIGHT_CONFIG_ENV = "SIFT_LIGHT_CONFIG";
-var SEMANTIC_JUDGE_API_KEY_ENVS = ["TYPESAFE_API_KEY", "SIFT_LIGHT_JEV_API_KEY"];
-var DEFAULT_SEMANTIC_JUDGE_CONFIG = {
-  enabled: false,
-  provider: "jev",
-  endpoint: "https://api.typesafe.ai/v1/systemone",
-  apiKeyEnv: SEMANTIC_JUDGE_API_KEY_ENVS[0],
-  model: "jev-latest",
-  timeoutMs: 120000,
-  maxCandidates: 20,
-  maxRetries: 2
-};
-var DEFAULT_SIFT_LIGHT_CONFIG = {
-  locale: "en",
-  enforceSearch: "hard",
-  semanticJudge: DEFAULT_SEMANTIC_JUDGE_CONFIG
-};
-function hasErrorCode(error, codes) {
-  return error instanceof Error && "code" in error && codes.includes(String(error.code));
-}
-function isMissingFile(error) {
-  return hasErrorCode(error, ["ENOENT"]);
-}
-function isRawSiftLightConfig(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isRawSemanticJudgeConfig(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function boundedInteger2(value, fallback, minimum, maximum, field) {
-  const candidate = value ?? fallback;
-  if (typeof candidate !== "number" || !Number.isSafeInteger(candidate) || candidate < minimum || candidate > maximum) {
-    throw new Error(`Invalid sift-light ${field}: expected an integer from ${String(minimum)} through ${String(maximum)}`);
-  }
-  return candidate;
-}
-function parseSemanticJudge(value, path) {
-  if (value === undefined)
-    return { ...DEFAULT_SEMANTIC_JUDGE_CONFIG };
-  if (!isRawSemanticJudgeConfig(value)) {
-    throw new Error(`Invalid sift-light config at ${path}: semanticJudge must be an object`);
-  }
-  const unknown = Object.keys(value).filter((key) => ![
-    "enabled",
-    "provider",
-    "endpoint",
-    "apiKeyEnv",
-    "model",
-    "timeoutMs",
-    "maxCandidates",
-    "maxRetries"
-  ].includes(key));
-  if (unknown.length > 0) {
-    throw new Error(`Invalid sift-light config at ${path}: unsupported semanticJudge fields; accepted fields are enabled, provider, endpoint, apiKeyEnv, model, timeoutMs, maxCandidates and maxRetries`);
-  }
-  const enabled = value.enabled ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.enabled;
-  if (typeof enabled !== "boolean") {
-    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.enabled must be a boolean`);
-  }
-  const provider = value.provider ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.provider;
-  if (provider !== "jev") {
-    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.provider must be "jev"`);
-  }
-  const endpoint = value.endpoint ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.endpoint;
-  if (typeof endpoint !== "string" || endpoint.length === 0 || endpoint.length > 2048) {
-    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.endpoint must be a nonempty URL`);
-  }
-  let parsedEndpoint;
-  try {
-    parsedEndpoint = new URL(endpoint);
-  } catch (error) {
-    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.endpoint must be a URL`, {
-      cause: error
-    });
-  }
-  const loopbackHosts = new Set(["localhost", "127.0.0.1", "[::1]"]);
-  const secureEndpoint = parsedEndpoint.protocol === "https:" || parsedEndpoint.protocol === "http:" && loopbackHosts.has(parsedEndpoint.hostname);
-  if (!secureEndpoint || parsedEndpoint.username || parsedEndpoint.password) {
-    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.endpoint must use HTTPS, except that HTTP is allowed for localhost loopback development; URL credentials are not allowed`);
-  }
-  const apiKeyEnv = value.apiKeyEnv ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.apiKeyEnv;
-  if (typeof apiKeyEnv !== "string" || !/^[A-Z][A-Z0-9_]{0,127}$/u.test(apiKeyEnv)) {
-    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.apiKeyEnv must be an uppercase environment variable name`);
-  }
-  const model = value.model ?? DEFAULT_SEMANTIC_JUDGE_CONFIG.model;
-  if (typeof model !== "string" || model.length === 0 || model.length > 128 || /[\r\n\0]/u.test(model)) {
-    throw new Error(`Invalid sift-light config at ${path}: semanticJudge.model must be bounded single-line text`);
-  }
-  return {
-    enabled,
-    provider,
-    endpoint,
-    apiKeyEnv,
-    model,
-    timeoutMs: boundedInteger2(value.timeoutMs, DEFAULT_SEMANTIC_JUDGE_CONFIG.timeoutMs, 1000, 1200000, `config at ${path}: semanticJudge.timeoutMs`),
-    maxCandidates: boundedInteger2(value.maxCandidates, DEFAULT_SEMANTIC_JUDGE_CONFIG.maxCandidates, 1, 20, `config at ${path}: semanticJudge.maxCandidates`),
-    maxRetries: boundedInteger2(value.maxRetries, DEFAULT_SEMANTIC_JUDGE_CONFIG.maxRetries, 0, 5, `config at ${path}: semanticJudge.maxRetries`)
-  };
-}
-function parseConfig(value, path) {
-  if (!isRawSiftLightConfig(value)) {
-    throw new Error(`Invalid sift-light config at ${path}: expected a JSON object`);
-  }
-  const unknown = Object.keys(value).filter((key) => !["locale", "enforceSearch", "semanticJudge"].includes(key));
-  if (unknown.length > 0) {
-    throw new Error(`Invalid sift-light config at ${path}: unsupported configuration fields; only locale, enforceSearch and semanticJudge are accepted`);
-  }
-  const { locale, enforceSearch } = value;
-  if (locale !== undefined && locale !== "en" && locale !== "zh-CN") {
-    throw new Error(`Invalid sift-light config at ${path}: locale must be "en" or "zh-CN"`);
-  }
-  const enforcement = normalizeSearchEnforcement(enforceSearch, `config at ${path}`);
-  return {
-    locale: locale ?? DEFAULT_SIFT_LIGHT_CONFIG.locale,
-    enforceSearch: enforcement,
-    semanticJudge: parseSemanticJudge(value.semanticJudge, path)
-  };
-}
-function normalizeSearchEnforcement(value, source) {
-  if (value === undefined || value === "hard")
-    return "hard";
-  if (value === "prefer")
-    return "prefer";
-  if (value === "off")
-    return "off";
-  throw new Error(`Invalid sift-light ${source}: enforceSearch must be "hard", "prefer", or "off"`);
-}
-async function readSiftLightConfigFile(path, options = {}) {
-  try {
-    const content = await readFile3(path, "utf8");
-    return parseConfig(JSON.parse(content), path);
-  } catch (error) {
-    if (isMissingFile(error)) {
-      if (options.missing === "error") {
-        throw new Error(`sift-light config was not found at ${path}; create it or unset ${SIFT_LIGHT_CONFIG_ENV}`, { cause: error });
-      }
-      return { ...DEFAULT_SIFT_LIGHT_CONFIG };
-    }
-    if (error instanceof SyntaxError) {
-      throw new Error(`Invalid sift-light config at ${path}: ${error.message}`, {
-        cause: error
-      });
-    }
-    throw error;
-  }
-}
-
 // src/prompt-guidelines.ts
 var SOURCE_OUTPUT_GUIDANCE = "Auto/summary text may include bounded source excerpts; ordinary matches text is metadata-only. Inspect may return bounded source windows covering an entire small file. Analysis text may include semantic passages; structured details may retain excerpts, names and signatures. Follow output limits, coverage and continuations.";
 function siftLightPromptGuidelines(structuredOutput = true) {
   return [
-    `Use sift-light for read-only content search. ${SOURCE_OUTPUT_GUIDANCE} Omit mode and limit for automatic detail/summary selection; use mode="matches" for ordinary match metadata.`,
+    `Use sift-light for read-only content search. ${SOURCE_OUTPUT_GUIDANCE} For routine development searches, start with fast exact content, filename or applicable structural modes when the request has a usable name, symbol, error text or other literal clue. Omitted mode is ordinary exact search and never loads the local embedding model. Vector search is disabled by default; concept/hybrid require vectorSearchEnabled:true in sift-light.json and an installed model. They can take tens of seconds on an uncached scope, so select them only when semantic recall is needed. Omit mode and limit for automatic detail/summary selection; use mode="matches" for ordinary match metadata.`,
     `An omitted path searches the project cwd. Use scope:"strict" for a question restricted to one path; otherwise, if an explicit subpath has zero matches, ordinary and content-analysis searches retry from cwd and return project-wide counts with an expansion notice. Explicit absolute paths and .. traversal can search outside cwd, except protected external system areas and .git internals. Git changes mode remains cwd-scoped.`,
     `Search output includes counts, categories, ranked paths, coverage and continuation metadata. Source excerpts may contain the searched text. Use mode="inspect" or the host read capability when exact source is required for an edit or verification.`,
     `Use file and directory distributions to choose evidence. Reuse the visible cursor with path or paths for match metadata; mode="summary" pages the remaining file statistics. Match counts are not relevance scores.`,
@@ -13177,7 +13678,7 @@ function siftLightPromptGuidelines(structuredOutput = true) {
     `Use anyOf:["term1","term2"] when every exact occurrence of 2-64 literals is needed in one version-bound result. It is case-sensitive, reports anonymized condition counts, and runs requests above eight terms as bounded parallel chunks. Large condition inventories have separate continuation pages; copy those requests to retrieve the complete counts.`,
     `For a changed-code question, add changes:{base:"HEAD",scope:"lines",side:"new"}; omit target for the working tree, use side:"old" for deleted-side statistics. Copy returned continuation requests to preserve source versions.`,
     `Use mode:"capabilities" when the language or requested operation is unclear to get a compact lazy inventory. Use mode:"outline" with a concrete source file path for symbol counts and locations, mode:"imports" for static relationships, and mode:"tests" for related-test candidates. Their text pages summarize metadata; structured details can retain source evidence.`,
-    `Use mode:"files" plus query for unknown filenames and fuzzy paths. Multi-word filename queries require each word literally in the path; business concepts belong in hybrid/concept. Use wholeWord:true for a single-pattern whole-word search. exclude contains file globs, not content negation.`,
+    `Use mode:"files" plus query for unknown filenames and fuzzy paths. Multi-word filename queries require each word literally in the path; use hybrid/concept only for business concepts that cannot be located by a literal clue. Use wholeWord:true for a single-pattern whole-word search. exclude contains file globs, not content negation.`,
     `Use mode:"structure" only for JS/TS/TSX/Go, with a required nonempty ast-grep pattern such as "compare($X, $X)" or "send()" for code shapes across whitespace; the text page reports structural counts and locations; structured details can retain matched source evidence.`,
     `Use mode:"concept" plus a natural-language query when names are unknown. It runs a pinned local multilingual model only after explicit installation; no search downloads weights or sends code to a remote model. Results expose candidate counts, score statistics, paths and the bounded ranked passage behind each candidate. Similarity scores identify candidates, not correctness.`,
     `Use mode:"hybrid" plus query when wording may differ from the source. It reports exact and semantic counts separately, removes overlap, and retains one pageable evidence snapshot. conceptLimit changes only the semantic candidate count; retained candidates keep their bounded source passages.`,
@@ -13188,9 +13689,9 @@ function siftLightPromptGuidelines(structuredOutput = true) {
 }
 function siftLightModelGuidelines() {
   return [
-    `Search with pattern and optional path. ${SOURCE_OUTPUT_GUIDANCE} Omit mode/limit for automatic detail/summary selection. Compact model analysis pages may defer source excerpts to inspect.`,
-    `Use ranked paths and condition counts to choose evidence. Cursor continuation pages the retained snapshot; summary file selection returns ordinary match metadata. Use mode="inspect" when an edit requires exact source.`,
-    `Modes: capabilities for language prerequisites; files+query for filenames; anyOf/allOf for literal condition statistics; outline/imports/tests for structural and relationship summaries; structure for AST match statistics; concept/hybrid for semantic candidate statistics. Similarity and static links are not proof.`,
+    `Search with pattern and optional path. ${SOURCE_OUTPUT_GUIDANCE} Default search is exact and model-free. concept/hybrid require vectorSearchEnabled:true in sift-light.json plus an installed model; uncached runs may take tens of seconds. Omit mode/limit for auto pages.`,
+    `Use ranked paths and counts; Cursor continuation pages retained results. Use mode="inspect" for exact source before editing.`,
+    `Modes: files+query for filenames; anyOf/allOf for literals; outline/imports/tests for static code; structure for AST; concept/hybrid for semantic candidates. Similarity is not proof.`,
     `On rejection keep the strongest applicable mode and apply the stated repair once. Do not repeat the rejected request or include its error. Only explicit capability-unavailable permits a visibly partial alternative.`
   ];
 }
@@ -13213,12 +13714,12 @@ function stringEnum(values, options) {
     ...options?.description ? { description: options.description } : {}
   });
 }
-var SIFT_LIGHT_DESCRIPTION = `Search and navigate code with bounded, verifiable evidence. Ordinary pattern searches use auto detail/summary; pattern is regex by default and literal=true matches source text exactly. A path selects an existing exact file or root; use mode=files with query to discover an unknown name. scope=strict prevents zero-result path expansion and wholeWord requires word boundaries. mode=capabilities returns a compact names-only project language inventory and the modes available for each detected language; capability providers are loaded only when the requested analysis runs. It never starts a parser, compiler, model or language server. mode=concept accepts a natural-language query, path and source filters; mode=hybrid uses one natural-language query for exact and local concept evidence, ranks exact evidence first, and retains a bounded semantic supplement. An explicitly enabled semantic judge may classify hybrid candidates, but it is disabled by default and never turns classification into a runtime proof. Slow concept/hybrid requests return status=waiting or running with operationId, progress, and an exact nextRequest using mode=await; copy that request unchanged to continue the same computation. Await expiry never downgrades evidence to literal-only or partial, and final results remain stable for the operation retention window. mode=cancel explicitly stops one operation. allOf and anyOf are explicit literal variants and cannot be mixed with pattern/literal; limit and context are output intent and are never silently dropped. modifiedAfter/modifiedBefore filter worktree files by inclusive/exclusive modification-time bounds in Unix milliseconds. structure requires a nonempty AST pattern and JS/TS/TSX/Go sources; lang is not a field. Outline uses a concrete source file path (not a directory) or retained cursor+matchIndex and follows declared syntax capabilities. imports/tests return bounded static module and related-test candidates without proving runtime execution. validate checks saved source evidence against its recorded origin. Partial coverage stays explicit. ${REQUEST_USAGE_GUIDANCE}`;
-var SIFT_LIGHT_MODEL_DESCRIPTION = `Bounded local evidence search. ${MODEL_USAGE_GUIDANCE}. Copy cursors; analysis is evidence, not proof.`;
+var SIFT_LIGHT_DESCRIPTION = `Search and navigate code with bounded, verifiable evidence. Routine searches should use exact content, filenames or applicable structural modes first. Omitted mode is ordinary exact search and does not load the embedding model; concept/hybrid require vectorSearchEnabled:true in sift-light.json plus an installed model and may take tens of seconds on an uncached scope. Ordinary pattern searches use auto detail/summary; pattern is regex by default and literal=true matches source text exactly. A path selects an existing exact file or root; use mode=files with query to discover an unknown name. scope=strict prevents zero-result path expansion and wholeWord requires word boundaries. mode=capabilities returns a compact names-only project language inventory and the modes available for each detected language; capability providers are loaded only when the requested analysis runs. It never starts a parser, compiler, model or language server. mode=concept accepts a natural-language query, path and source filters; mode=hybrid uses one natural-language query for exact and local concept evidence, ranks exact evidence first, and retains a bounded semantic supplement. An explicitly enabled semantic judge may classify hybrid candidates, but it is disabled by default and never turns classification into a runtime proof. Slow concept/hybrid requests return status=waiting or running with operationId, progress, and an exact nextRequest using mode=await; copy that request unchanged to continue the same computation. Await expiry never downgrades evidence to literal-only or partial, and final results remain stable for the operation retention window. mode=cancel explicitly stops one operation. allOf and anyOf are explicit literal variants and cannot be mixed with pattern/literal; limit and context are output intent and are never silently dropped. modifiedAfter/modifiedBefore filter worktree files by inclusive/exclusive modification-time bounds in Unix milliseconds. structure requires a nonempty AST pattern and JS/TS/TSX/Go sources; lang is not a field. Outline uses a concrete source file path (not a directory) or retained cursor+matchIndex and follows declared syntax capabilities. imports/tests return bounded static module and related-test candidates without proving runtime execution. validate checks saved source evidence against its recorded origin. Partial coverage stays explicit. ${REQUEST_USAGE_GUIDANCE}`;
+var SIFT_LIGHT_MODEL_DESCRIPTION = `Bounded local evidence search. Default exact search is model-free; concept/hybrid require vectorSearchEnabled:true in sift-light.json and a model. ${MODEL_USAGE_GUIDANCE}. Copy cursors; analysis is evidence, not proof.`;
 var siftLightSchema = Type.Object({
   query: Type.Optional(Type.String({
     maxLength: 256,
-    description: `${fieldGuidance("query")}. Hybrid uses the same query as exact literal text and as the local concept query. Discovery modes preserve their requested path. Concept and hybrid require an explicitly installed local model. A semantic judge is optional and remains disabled unless the active configuration explicitly enables it.`
+    description: `${fieldGuidance("query")}. Hybrid uses the same query as exact literal text and as the local concept query. Discovery modes preserve their requested path. Concept and hybrid require vectorSearchEnabled:true in sift-light.json and an explicitly installed local model. A semantic judge is optional and remains disabled unless the active configuration explicitly enables it.`
   })),
   scope: Type.Optional(stringEnum(["strict", "expand"], {
     description: `${fieldGuidance("scope")}; expand (default) retries ordinary content search from project cwd. Applies to ordinary, multi-term and role searches.`
@@ -13232,9 +13733,9 @@ var siftLightSchema = Type.Object({
     description: `${fieldGuidance("anyOf")}. ${String(MIN_ANY_OF_TERMS)}-${String(MAX_ANY_OF_TOTAL_TERMS)} distinct case-sensitive single-line terms, at most ${String(MAX_LITERAL_TERM_BYTES)} UTF-8 bytes each. Requests above ${String(MAX_ANY_OF_TERMS)} terms are split into version-checked chunks and merged. Returns every retained occurrence attributed to its term.`
   })),
   allOf: Type.Optional(Type.Array(Type.String({ maxLength: MAX_PATH_CHARACTERS }), {
-    minItems: 2,
+    minItems: 1,
     maxItems: 3,
-    description: `${fieldGuidance("allOf")}. 2-3 distinct terms must occur in one file (default) or one function.`
+    description: `${fieldGuidance("allOf")}. 1-3 distinct terms must occur in one file (default) or one function; one term lists the files or functions containing it.`
   })),
   within: Type.Optional(stringEnum(["file", "function"], {
     description: "Only valid with allOf; omit for ordinary single-pattern searches. function requires JS/TS/TSX and counts only that implementation's own code, excluding nested callbacks, strings/comments/types. Not proof of a shared execution path."
@@ -13251,7 +13752,7 @@ var siftLightSchema = Type.Object({
     "unknown"
   ]), {
     minItems: 1,
-    description: "Filter each single-pattern occurrence by syntax role (JS/TS/TSX/Go). Roles may be candidates, especially Go call/conversion ambiguity. Cannot combine with allOf."
+    description: "Filter each single-pattern occurrence by syntax role (JS/TS/TSX/Go parsed; Python lexical: comment, string, code, declaration, import, call candidates). Roles may be candidates, especially Go call/conversion and Python calls. Cannot combine with allOf."
   })),
   changes: Type.Optional(Type.Object({
     base: Type.Optional(Type.String({
@@ -13284,7 +13785,7 @@ var siftLightSchema = Type.Object({
   paths: Type.Optional(Type.Array(Type.String(), {
     minItems: 1,
     maxItems: MAX_SELECTED_PATHS,
-    description: "Exact retained files to select together from a cursor. A new search accepts one path; split multiple roots into separate requests."
+    description: "Exact retained files to select together from a cursor. A new search accepts one path; split multiple roots into separate requests. With mode=inspect and no cursor, opens each file from line 1 (same as targets with line 1)."
   })),
   glob: Type.Optional(Type.Union([
     Type.String({ maxLength: MAX_PATH_CHARACTERS }),
@@ -13308,7 +13809,7 @@ var siftLightSchema = Type.Object({
   })),
   hidden: Type.Optional(Type.Boolean({ description: "Search hidden files (default true; .git is always excluded)." })),
   ignorePolicy: Type.Optional(stringEnum(["respect", "include"], {
-    description: "respect (default) honors ignore rules and reports policy-filtered coverage when files are omitted. include searches ignored files while still excluding .git internals and protected paths."
+    description: "respect (default) honors ignore rules and reports policy-filtered coverage when files are omitted, including mode=files. include searches or lists ignored files while still excluding .git internals and protected paths."
   })),
   patterns: Type.Optional(Type.Array(Type.Object({
     id: Type.String({ minLength: 1, maxLength: 64 }),
@@ -13353,29 +13854,29 @@ var siftLightSchema = Type.Object({
   limit: Type.Optional(Type.Integer({
     minimum: 1,
     maximum: MAX_PAGE_SIZE,
-    description: `${fieldGuidance("limit")}. Ordinary search only: explicit detail-page match limit (max 100). Normally omit to preserve automatic summarization; analysis and inspect modes reject it.`
+    description: `${fieldGuidance("limit")}. Ordinary search: explicit detail-page match limit (max 100); mode=files: files per page (default 30). Normally omit to preserve automatic summarization; other analysis and inspect modes reject it.`
   })),
-  mode: Type.Optional(stringEnum(SIFT_LIGHT_MODES, {
-    description: `Ordinary search defaults to auto; summary/matches request explicit pages. capabilities returns a compact names-only project inventory and per-language supported modes without loading providers. files uses query, structure uses an AST pattern, concept uses a required natural-language query, and hybrid uses one query for exact literal plus concept evidence in a single snapshot. validate rechecks saved search or analysis sources against their recorded origin. await waits for an existing long-running concept or hybrid operation without restarting it; cancel explicitly cancels one and waits for owned cleanup. Copy the returned nextRequest exactly and do not repeat the original query. Waiting is an operation state, not evidence. Validation details report the requested scope, comparison target, coverage, and freshness as current, stale, or unknown; partial coverage is retained during validation. inspect/outline/imports/tests retain their documented location selectors. Syntax results are static evidence; concept and related-test results remain candidates. ${MODE_CONTRACT_DESCRIPTION}`
+  mode: Type.Optional(stringEnum([...SIFT_LIGHT_MODES, ...MODE_ALIASES], {
+    description: `Ordinary search defaults to auto; summary/matches request explicit pages. capabilities returns a compact names-only project inventory and per-language supported modes without loading providers. files uses query, structure uses an AST pattern, concept uses a required natural-language query, and hybrid uses one query for exact literal plus concept evidence in a single snapshot. validate rechecks saved search or analysis sources against their recorded origin. await waits for an existing long-running concept or hybrid operation without restarting it; cancel explicitly cancels one and waits for owned cleanup. Copy the returned nextRequest exactly and do not repeat the original query. Waiting is an operation state, not evidence. Validation details report the requested scope, comparison target, coverage, and freshness as current, stale, or unknown; partial coverage is retained during validation. inspect/outline/imports/tests retain their documented location selectors. Syntax results are static evidence; concept and related-test results remain candidates. ${MODE_CONTRACT_DESCRIPTION} anyOf/allOf are field names, not modes; as mode values they are accepted aliases for omitting mode, disclosed in a request note.`
   })),
   line: Type.Optional(Type.Number({
-    description: "1-indexed source line for path inspection/navigation. Omit with matchIndex, matchIndices or targets."
+    description: "1-indexed source line for path inspection/navigation; path-only inspect starts at line 1. Omit with matchIndex, matchIndices or targets."
   })),
   matchIndex: Type.Optional(Type.Number({
     description: "1-based retained match index for cursor-scoped inspect; replaces path and line."
   })),
   matchIndices: Type.Optional(Type.Array(Type.Integer({ minimum: 1 }), {
     minItems: 1,
-    maxItems: MAX_INSPECT_TARGETS,
-    description: "Inspect up to five visible match numbers together using the same cursor; mutually exclusive with matchIndex, path, line and targets."
+    maxItems: MAX_INSPECT_REQUEST_TARGETS,
+    description: `Inspect visible match numbers together using the same cursor; mutually exclusive with matchIndex, path, line and targets. One response inspects ${String(MAX_INSPECT_TARGETS)}; the rest are returned as an exact nextRequest.`
   })),
   targets: Type.Optional(Type.Array(Type.Object({
     path: Type.String({ maxLength: MAX_PATH_CHARACTERS }),
     line: Type.Integer({ minimum: 1 })
   }), {
     minItems: 1,
-    maxItems: MAX_INSPECT_TARGETS,
-    description: "Inspect known path/line locations together without a cursor. The complete batch shares one 16 KiB response budget."
+    maxItems: MAX_INSPECT_REQUEST_TARGETS,
+    description: `Inspect known path/line locations together without a cursor. One response inspects ${String(MAX_INSPECT_TARGETS)} within a shared 16 KiB budget; the rest are returned as an exact nextRequest.`
   })),
   cursor: Type.Optional(Type.String({ description: "Opaque cursor from a previous stable search snapshot." })),
   operationId: Type.Optional(Type.String({
@@ -13421,11 +13922,12 @@ function siftLightTool(outputMode) {
     tool.outputSchema = SIFT_LIGHT_OUTPUT_SCHEMA;
   return tool;
 }
-function createDefaultSiftLightMcpService(semanticJudge) {
+function createDefaultSiftLightMcpService(semanticJudge, vectorSearchEnabled = false) {
   const resolvedSemanticJudge = semanticJudge ?? createDisabledSemanticJudgeIntegration(DEFAULT_SEMANTIC_JUDGE_CONFIG);
   return new SiftLightService({
     runRipgrep: createRipgrepRunner(),
     structure: createCtagsStructureProvider(),
+    vectorSearchEnabled,
     semanticJudge: resolvedSemanticJudge
   });
 }
@@ -13848,12 +14350,18 @@ function configuredPath(environment) {
   const value = environment[SIFT_LIGHT_CONFIG_ENV]?.trim();
   return value || undefined;
 }
-async function createMcpSemanticJudgeIntegration(environment = process.env) {
+async function createMcpSearchFeatures(environment = process.env) {
   const path = configuredPath(environment);
   if (!path)
-    return createDisabledSemanticJudgeIntegration(DEFAULT_SEMANTIC_JUDGE_CONFIG);
+    return {
+      semanticJudge: createDisabledSemanticJudgeIntegration(DEFAULT_SEMANTIC_JUDGE_CONFIG),
+      vectorSearchEnabled: DEFAULT_SIFT_LIGHT_CONFIG.vectorSearchEnabled === true
+    };
   const config = await readSiftLightConfigFile(path, { missing: "error" });
-  return createSemanticJudgeIntegration(config.semanticJudge ?? DEFAULT_SEMANTIC_JUDGE_CONFIG, environment);
+  return {
+    semanticJudge: createConfiguredSemanticJudgeIntegration(config, environment),
+    vectorSearchEnabled: config.vectorSearchEnabled === true
+  };
 }
 function mcpSemanticJudgeConfigSource(environment = process.env) {
   return configuredPath(environment) ? "explicit-config" : "not-configured";
@@ -13967,20 +14475,17 @@ function environmentInteger(name, fallback, minimum, maximum) {
 function allowedOrigins() {
   return (process.env.SIFT_LIGHT_MCP_ALLOWED_ORIGINS ?? "").split(",").map((origin) => origin.trim()).filter((origin) => origin.length > 0);
 }
-async function configuredSemanticJudge() {
-  return createMcpSemanticJudgeIntegration();
-}
 function logSemanticJudgeStatus(integration) {
   const status = integration.config.enabled ? "enabled" : "disabled";
   process.stderr.write(`sift-light MCP semantic judge: ${status}; source=${mcpSemanticJudgeConfigSource()}
 `);
 }
-async function runHttpServer(outputMode, semanticJudge) {
+async function runHttpServer(outputMode, semanticJudge, vectorSearchEnabled) {
   const running = await startSiftLightMcpServer({
     cwd: process.env.SIFT_LIGHT_MCP_CWD ?? process.cwd(),
     host: process.env.SIFT_LIGHT_MCP_HOST ?? DEFAULT_MCP_HOST,
     port: environmentInteger("SIFT_LIGHT_MCP_PORT", DEFAULT_MCP_PORT, 0, 65535),
-    createService: () => createDefaultSiftLightMcpService(semanticJudge),
+    createService: () => createDefaultSiftLightMcpService(semanticJudge, vectorSearchEnabled),
     maxSessions: environmentInteger("SIFT_LIGHT_MCP_MAX_SESSIONS", DEFAULT_MCP_MAX_SESSIONS, 1, Number.MAX_SAFE_INTEGER),
     sessionIdleTimeoutMs: environmentInteger("SIFT_LIGHT_MCP_SESSION_IDLE_MS", DEFAULT_MCP_SESSION_IDLE_TIMEOUT_MS, 1, Number.MAX_SAFE_INTEGER),
     allowedOrigins: allowedOrigins(),
@@ -14014,11 +14519,11 @@ async function runHttpServer(outputMode, semanticJudge) {
   process.once("SIGINT", shutdown);
   process.once("SIGTERM", shutdown);
 }
-async function runStdioServer(outputMode, semanticJudge) {
+async function runStdioServer(outputMode, semanticJudge, vectorSearchEnabled) {
   const running = await startSiftLightMcpStdioServer({
     cwd: process.env.SIFT_LIGHT_MCP_CWD ?? process.env.CLAUDE_PROJECT_DIR ?? process.cwd(),
     outputMode,
-    createService: () => createDefaultSiftLightMcpService(semanticJudge)
+    createService: () => createDefaultSiftLightMcpService(semanticJudge, vectorSearchEnabled)
   });
   process.stderr.write(`sift-light MCP serving one local client over stdio
 `);
@@ -14047,13 +14552,15 @@ async function main() {
     return;
   }
   const outputMode = parseSiftLightMcpOutputMode(process.env.SIFT_LIGHT_MCP_OUTPUT_MODE);
-  const semanticJudge = await configuredSemanticJudge();
+  const { semanticJudge, vectorSearchEnabled } = await createMcpSearchFeatures();
   logSemanticJudgeStatus(semanticJudge);
+  process.stderr.write(`sift-light MCP vector search: ${vectorSearchEnabled ? "enabled" : "disabled"}
+`);
   if (transport === "stdio") {
-    await runStdioServer(outputMode, semanticJudge);
+    await runStdioServer(outputMode, semanticJudge, vectorSearchEnabled);
     return;
   }
-  await runHttpServer(outputMode, semanticJudge);
+  await runHttpServer(outputMode, semanticJudge, vectorSearchEnabled);
 }
 try {
   await main();