sift-light 1.0.0 → 1.0.2

package/src/request-contract.ts

@@ -115,6 +115,38 @@ function schemaError(
   );
 }
 
+function plainFilePatternRecovery(
+  mode: SiftLightMode,
+  input: Record<string, unknown>,
+  invalid: readonly string[],
+): boolean {
+  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)
+  );
+}
+
+/** `pattern: ".*"` in files mode means "every file": the exact repair omits it. */
+function matchAllFilePatternRecovery(
+  mode: SiftLightMode,
+  input: Record<string, unknown>,
+  invalid: readonly string[],
+): boolean {
+  return (
+    mode === "files" &&
+    invalid.includes("pattern") &&
+    input.query === undefined &&
+    typeof input.pattern === "string" &&
+    /^(?:\.\*|\.\+|\*+)$/u.test(input.pattern.trim())
+  );
+}
+
 function safeNextRequest(
   input: Record<string, unknown>,
   mode: SiftLightMode,
@@ -122,9 +154,12 @@ function safeNextRequest(
 ): Record<string, unknown> | undefined {
   if (input.redact === true && containsSensitiveText(input)) return undefined;
   const safe = new Set<string>(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 undefined;
   const next: Record<string, unknown> = { ...input };
   for (const field of invalid) delete next[field];
+  if (plainFilePattern) next.query = input.pattern;
   if (selectorIssuesFor(next, mode).length > 0) return undefined;
   // A copied request must remain within the transport's bounded line budget.
   try {
@@ -165,7 +200,14 @@ function fieldsError(
   // the signature of arguments shaped as a per-mode object, which the flat
   // schema never advertises. Naming the accepted fields replaces an otherwise
   // puzzling rejection with the rule and the valid names.
-  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",
@@ -174,17 +216,28 @@ function fieldsError(
       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.`,
+      ? `${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."}`,
   );
 }
 
@@ -422,7 +475,8 @@ export function validateRequestContract(input: SiftLightInput): void {
   const allowed = new Set(MODE_FIELDS_BY_MODE[mode]);
   if (mode === "inspect" && raw.sourceCursor !== undefined) {
     allowed.clear();
-    for (const field of ["mode", "sourceCursor", "redact"] as const) allowed.add(field);
+    // path is checked against the continuation's own source; it cannot redirect it.
+    for (const field of ["mode", "sourceCursor", "redact", "path"] as const) allowed.add(field);
   }
   if (
     (mode === "auto" || mode === "summary" || mode === "matches") &&

package/src/request.ts

@@ -108,7 +108,9 @@ export function normalizeRequest(input: RawSearchInput): SearchRequest {
     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(/^@/, "");

package/src/runtime.ts

@@ -1,5 +1,5 @@
 import type { SiftLightLocale } from "./config.js";
-import type { SiftLightInput, SiftLightSearchOptions, SiftLightService } from "./service.js";
+import type { SiftLightRequest, SiftLightSearchOptions, SiftLightService } from "./service.js";
 import { type SessionSummarySnapshot, SessionSummary } from "./session-summary.js";
 import type { ContextBudget, SiftLightResult } from "./types.js";
 
@@ -12,7 +12,7 @@ export class SiftLightRuntime {
   }
 
   async search(
-    input: SiftLightInput,
+    input: SiftLightRequest,
     cwd: string,
     signal?: AbortSignal,
     contextBudget?: ContextBudget,

package/src/semantic-judge.ts

@@ -1,4 +1,8 @@
-import type { SemanticJudgeConfig } from "./config-reader.js";
+import {
+  DEFAULT_SEMANTIC_JUDGE_CONFIG,
+  type SemanticJudgeConfig,
+  type SiftLightConfig,
+} from "./config-reader.js";
 import {
   SEMANTIC_JUDGE_CLASSIFICATIONS,
   SEMANTIC_JUDGE_NON_PROOF_CLAIM,
@@ -134,8 +138,7 @@ function requestBody(
   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.",
@@ -374,6 +377,17 @@ export function createSemanticJudgeIntegration(
   }
   return { config, runner: createJevRunner(config, key, fetcher) };
 }
+
+export function createConfiguredSemanticJudgeIntegration(
+  config: SiftLightConfig,
+  environment: NodeJS.ProcessEnv = process.env,
+): SemanticJudgeIntegration {
+  const judge = config.semanticJudge ?? DEFAULT_SEMANTIC_JUDGE_CONFIG;
+  return config.vectorSearchEnabled === true
+    ? createSemanticJudgeIntegration(judge, environment)
+    : createDisabledSemanticJudgeIntegration(judge);
+}
+
 function baseDetails(config: SemanticJudgeConfig): SemanticJudgeDetails {
   return {
     enabled: config.enabled,

package/src/service.ts

@@ -7,6 +7,18 @@ import { resolve } from "node:path";
 import { CursorError, SiftLightError } from "./errors.js";
 import { DISCOVERY_MODE_REQUIRED_ERROR } from "./discovery-errors.js";
 import { validateRequestContract } from "./request-contract.js";
+import { normalizeRequestAliases, type SiftLightRequest } from "./request-aliases.js";
+
+export type { SiftLightRequest } from "./request-aliases.js";
+
+/** Normalizations are part of the evidence: show them in text and details. */
+function withRequestNotes(result: SiftLightResult, notes: readonly string[]): SiftLightResult {
+  if (notes.length === 0) return result;
+  return {
+    text: `${notes.map((note) => `[Request note: ${note}]`).join("\n")}\n${result.text}`,
+    details: { ...result.details, requestNotes: [...notes] },
+  };
+}
 import {
   formatMatchMetadataPage,
   formatMatchPage,
@@ -87,6 +99,7 @@ export interface SiftLightServiceOptions {
   snapshots?: SnapshotStore;
   summaryFileLimit?: number;
   structure?: CodeStructureProvider;
+  vectorSearchEnabled?: boolean;
   conceptSearch?: ConceptSearchRunner;
   semanticJudge?: SemanticJudgeIntegration;
 }
@@ -367,6 +380,7 @@ export class SiftLightService {
   readonly #runRipgrep: RipgrepRunner;
   readonly #snapshots: SnapshotStore;
   readonly #summaryFileLimit: number;
+  readonly #vectorSearchEnabled: boolean;
   readonly #capabilities = new LanguageCapabilityCatalog();
   readonly #evidence: EvidenceService;
   #lifecycle = new AbortController();
@@ -378,6 +392,7 @@ export 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,
@@ -389,13 +404,28 @@ export class SiftLightService {
   }
 
   async search(
-    input: SiftLightInput,
+    request: SiftLightRequest,
     cwd: string,
     signal?: AbortSignal,
     options: SiftLightSearchOptions = {},
+  ): Promise<SiftLightResult> {
+    const { input, notes } = normalizeRequestAliases(request);
+    return withRequestNotes(await this.#searchNormalized(input, cwd, signal, options), notes);
+  }
+
+  async #searchNormalized(
+    input: SiftLightInput,
+    cwd: string,
+    signal: AbortSignal | undefined,
+    options: SiftLightSearchOptions,
   ): Promise<SiftLightResult> {
     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: Promise<SiftLightResult>;
     if (input.mode === "await" || input.mode === "cancel") {
       request = this.#operationCommand(input, cwd, signal);

package/src/session-summary.ts

@@ -1,6 +1,6 @@
 import type { SiftLightLocale } from "./config.js";
 import { SIFT_LIGHT_VERSION } from "./package-version.js";
-import type { SiftLightInput } from "./service.js";
+import type { SiftLightRequest } from "./service.js";
 import type { SiftLightResult } from "./types.js";
 
 export const SESSION_STATUS_KEY = "sift-light_session";
@@ -13,7 +13,7 @@ export interface SessionSummarySnapshot {
   failedCalls: number;
 }
 
-function isNewQuery(input: SiftLightInput): boolean {
+function isNewQuery(input: SiftLightRequest): boolean {
   return (
     input.cursor === undefined &&
     input.sourceCursor === undefined &&
@@ -21,7 +21,7 @@ function isNewQuery(input: SiftLightInput): boolean {
   );
 }
 
-function wasAutomaticallyOrganized(input: SiftLightInput, result: SiftLightResult): boolean {
+function wasAutomaticallyOrganized(input: SiftLightRequest, result: SiftLightResult): boolean {
   const autoMode = input.mode === undefined || input.mode === "auto";
   return autoMode && input.limit === undefined && result.details.summaryFilesShown !== undefined;
 }
@@ -59,7 +59,7 @@ export class SessionSummary {
     failedCalls: 0,
   };
 
-  record(input: SiftLightInput, result: SiftLightResult): void {
+  record(input: SiftLightRequest, result: SiftLightResult): void {
     if (!isNewQuery(input)) return;
     this.#snapshot.queries += 1;
     if (result.details.status === "complete") this.#snapshot.completeQueries += 1;

package/src/source-inspection.ts

@@ -33,6 +33,8 @@ export interface SourceInspectionTarget {
   /** Raw source byte offset; retained-match focus is line-relative. */
   absoluteFocus?: number;
   focus?: number;
+  /** Structure already proven by the analysis that produced `range`. */
+  structure?: StructureDetails;
   expectedRevision?: SourceRevision;
   unverified?: boolean;
   retry?: SiftLightInput;
@@ -121,7 +123,20 @@ async function prepare(
   let range = target.range;
   let details: StructureDetails = { 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)),
+    };
+    // Whole lines keep leading modifiers such as `export` or decorators readable.
+    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:
@@ -205,7 +220,9 @@ async function prepare(
     Math.min(document.lineStarts.length, target.line + 10),
   );
   const boundary: Exclude<SourceBoundary, "mixed"> = target.range
-    ? "requested-range"
+    ? target.structure
+      ? "syntax"
+      : "requested-range"
     : details.status === "available" && details.range
       ? "syntax"
       : "line-window";
@@ -692,8 +709,16 @@ export async function continueSource(
   cursor: string,
   access: SourceAccess,
   continuations: SourceContinuations,
+  expectedPath?: string,
 ): Promise<SiftLightResult> {
   const state = continuations.resolve(cursor);
+  if (
+    expectedPath !== undefined &&
+    resolve(access.cwd, expectedPath.replace(/^@/, "")) !== resolve(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);

package/src/tool-schema.ts

@@ -10,6 +10,7 @@ import {
 } from "./analysis-limits.js";
 import {
   MAX_CONTEXT_LINES,
+  MAX_INSPECT_REQUEST_TARGETS,
   MAX_INSPECT_TARGETS,
   MAX_PAGE_SIZE,
   MAX_SELECTED_PATHS,
@@ -25,6 +26,7 @@ import {
   SIFT_LIGHT_MODES,
   fieldGuidance,
 } from "./request-contract.js";
+import { MODE_ALIASES } from "./request-aliases.js";
 
 function stringEnum<const Values extends readonly string[]>(
   values: Values,
@@ -37,15 +39,15 @@ function stringEnum<const Values extends readonly string[]>(
   });
 }
 
-export const 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}`;
+export const 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}`;
 
-export const SIFT_LIGHT_MODEL_DESCRIPTION = `Bounded local evidence search. ${MODEL_USAGE_GUIDANCE}. Copy cursors; analysis is evidence, not proof.`;
+export const 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.`;
 
 export const 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(
@@ -68,9 +70,9 @@ export const siftLightSchema = Type.Object({
   ),
   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(
@@ -95,7 +97,7 @@ export const siftLightSchema = Type.Object({
       {
         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.",
+          "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.",
       },
     ),
   ),
@@ -151,7 +153,7 @@ export const siftLightSchema = Type.Object({
       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.",
+        "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(
@@ -193,7 +195,7 @@ export const siftLightSchema = Type.Object({
   ignorePolicy: Type.Optional(
     stringEnum(["respect", "include"] as const, {
       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.",
+        "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(
@@ -264,19 +266,19 @@ export const siftLightSchema = Type.Object({
     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}`,
+    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.",
+        "1-indexed source line for path inspection/navigation; path-only inspect starts at line 1. Omit with matchIndex, matchIndices or targets.",
     }),
   ),
   matchIndex: Type.Optional(
@@ -288,9 +290,8 @@ export const siftLightSchema = Type.Object({
   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(
@@ -301,9 +302,8 @@ export const siftLightSchema = Type.Object({
       }),
       {
         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.`,
       },
     ),
   ),

package/src/tui/layout.ts

@@ -1,6 +1,6 @@
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { SiftLightLocale } from "../config.js";
-import type { SiftLightInput } from "../service.js";
+import type { SiftLightRequest } from "../service.js";
 import type { Dashboard } from "./dashboard.js";
 
 import { candy, type SiftLightTheme } from "./palette.js";
@@ -254,7 +254,7 @@ export function renderDashboard(
 }
 
 export function renderSiftLightCallLines(
-  input: SiftLightInput,
+  input: SiftLightRequest,
   locale: SiftLightLocale,
   theme: SiftLightTheme,
   width: number,

package/src/tui/renderers.ts

@@ -1,6 +1,6 @@
 import { type Component } from "@earendil-works/pi-tui";
 import type { SiftLightLocale } from "../config.js";
-import type { SiftLightInput } from "../service.js";
+import type { SiftLightRequest } from "../service.js";
 import type { SiftLightDetails } from "../types.js";
 import { dashboard } from "./dashboard.js";
 import { fit, renderDashboard, renderSiftLightCallLines, type SiftLightTheme } from "./layout.js";
@@ -47,7 +47,7 @@ function failure(text: string, locale: SiftLightLocale): string {
 }
 
 export function renderSiftLightCall(
-  input: SiftLightInput,
+  input: SiftLightRequest,
   locale: SiftLightLocale,
   theme: SiftLightTheme,
 ): Component {

package/src/types.ts

@@ -23,6 +23,8 @@ export const ESTIMATED_CHARACTERS_PER_TOKEN = 4;
 export const DEFAULT_SUMMARY_FILE_LIMIT = 30;
 export const MAX_SELECTED_PATHS = 20;
 export const MAX_INSPECT_TARGETS = 5;
+/** A request may name more targets; they are served in pages of MAX_INSPECT_TARGETS. */
+export const MAX_INSPECT_REQUEST_TARGETS = 20;
 export const MAX_DISPLAYED_OCCURRENCES = 20;
 export const MAX_STORED_MATCHES = 50_000;
 export const MAX_STORED_OCCURRENCES = 200_000;
@@ -310,6 +312,8 @@ export interface SiftLightDetails {
   source?: SourceExcerptDetails;
   inspections?: InspectBatchItemDetails[];
   scope?: SearchScopeDetails;
+  /** Disclosed request normalizations, such as a field name sent as mode. */
+  requestNotes?: string[];
   redactedCount?: number;
   redactionRequested?: boolean;
   redactionApplied?: boolean;