@takara-ai/miru-code 1.11.0 → 1.12.1

package/README.md

@@ -200,9 +200,9 @@ When wired via `miru install`, the MCP server exposes `search`, `locate`, `expan
 ### Workflow
 
 1. **`search`** with `query` — returns compact snippets (~±15 lines) and relevance scores.
-2. If a hit has **`truncated: true`**, call **`expand`** with `file_path` and `anchor_line` — not another search or a full-file read.
-3. To trace similar patterns elsewhere, call **`find_related`** with the same `file_path` and `anchor_line`.
-4. Use your editor's **Read** on `absolute_path` only when editing or when `expand` still lacks context.
+2. If a hit has **`truncated: true`**, its header names the symbol and its exact lines (`path:start-end Symbol`) plus `anchor_line`. Read just those lines with a ranged **Read** (`offset`/`limit`) — not another search or a full-file read.
+3. If that range lacks context, call **`expand`** with `file_path` and `anchor_line` for neighbouring chunks. To trace similar patterns elsewhere, call **`find_related`** with the same `file_path` and `anchor_line`.
+4. Use your editor's **Read** on `absolute_path` only for a hit's line range, to see a truncated body or edit it.
 
 Keep `repo` on follow-up calls when set.
 
@@ -376,7 +376,7 @@ Override with `MIRU_BENCHMARK_HISTORY_PATH`. Append-only JSONL of compact token
 | `repo`        | no       | Startup directory by default; set for another repo                                |
 | `include`     | no       | Gitignore-style glob patterns; only matching files are searched                    |
 | `exclude`     | no       | Gitignore-style glob patterns; matching files are skipped                          |
-| `mode`        | no       | `count` · `locations` · `lines` (default). Prefer `count`/`locations` when possible |
+| `mode`        | no       | `count` · `files` (unique paths) · `locations` · `lines` (default). Prefer `count`/`files`/`locations` when possible |
 | `limit`       | no       | Cap returned hits. Omit to return all matches                                       |
 | `ignore_case` | no       | Case-insensitive match (default `false`)                                            |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "mcpName": "ai.takara/miru",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",

package/src/agents/claude.md

@@ -1,5 +1,4 @@
 ---
 name: miru-code
-description: Code search via Miru MCP. Use search, expand, and find_related. DO NOT use Grep, Glob, or Read for exploration when Miru MCP is available.
-tools: Bash, Read
+description: Use proactively for any codebase exploration — "where is X handled", "how does Y work", "what calls Z", mapping an unfamiliar area, or finding the right file before an edit. Searches by meaning via Miru MCP instead of Grep/Glob/Read sweeps.
 ---

package/src/chunking/ast.ts

@@ -68,19 +68,6 @@ function mergeNode(node: Node, desiredLength: number): ChunkBoundary[] {
   return mergeAdjacentChunks(rawChunks, desiredLength);
 }
 
-function byteBoundariesToCharBoundaries(
-  source: string,
-  byteBoundaries: ChunkBoundary[],
-): ChunkBoundary[] {
-  const sourceBytes = new TextEncoder().encode(source);
-  const decoder = new TextDecoder();
-
-  return byteBoundaries.map((boundary) => ({
-    start: decoder.decode(sourceBytes.subarray(0, boundary.start)).length,
-    end: decoder.decode(sourceBytes.subarray(0, boundary.end)).length,
-  }));
-}
-
 /** AST-aware chunk boundaries via vendored tree-sitter grammars; null to fall back. */
 export async function chunkAst(
   source: string,
@@ -129,8 +116,8 @@ function parseBoundaries(
   }
 
   try {
-    const byteBoundaries = mergeNode(tree.rootNode, desiredLength);
-    return byteBoundariesToCharBoundaries(source, byteBoundaries);
+    // web-tree-sitter reports UTF-16 string indices (not UTF-8 bytes), so boundaries slice `source` directly.
+    return mergeNode(tree.rootNode, desiredLength);
   } finally {
     tree.delete();
   }

package/src/chunking/chunking.ts

@@ -1,11 +1,29 @@
 import type { Chunk } from "../types.ts";
 import { chunkAst } from "./ast.ts";
-import { chunkLines } from "./lines.ts";
+import { type ChunkBoundary, chunkLines } from "./lines.ts";
 import { chunkStructural } from "./structural.ts";
 
 /** Match upstream hybrid-search chunking target length. */
 const DESIRED_CHUNK_LENGTH_CHARS = 1500;
 
+/**
+ * Sibling AST nodes split mid-line leave their inter-token whitespace in no chunk, so rejoining
+ * the line later yields `exportasync`. Extend the earlier chunk across a same-line, whitespace-only
+ * gap; gaps containing a newline (between declarations) are left exactly as they were.
+ */
+function closeSameLineGap(
+  source: string,
+  boundary: ChunkBoundary,
+  next: ChunkBoundary | undefined,
+): ChunkBoundary {
+  if (!next || next.start <= boundary.end) {
+    return boundary;
+  }
+  return /^[^\S\n]+$/.test(source.slice(boundary.end, next.start))
+    ? { start: boundary.start, end: next.start }
+    : boundary;
+}
+
 export async function chunkSource(
   source: string,
   filePath: string,
@@ -26,7 +44,8 @@ export async function chunkSource(
     prefixNewlineCounts[i + 1] = prevCount + (source[i] === "\n" ? 1 : 0);
   }
 
-  for (const boundary of boundaries) {
+  for (const [i, raw] of boundaries.entries()) {
+    const boundary = closeSameLineGap(source, raw, boundaries[i + 1]);
     const endIndex = Math.max(boundary.end - 1, boundary.start);
     const text = source.slice(boundary.start, endIndex + 1);
     chunks.push({

package/src/cli.ts

@@ -541,8 +541,8 @@ async function runCli(argv: string[]): Promise<void> {
       const arg = contentRest[i];
       if (arg === "--mode" && contentRest[i + 1]) {
         const value = contentRest[++i];
-        if (value !== "count" && value !== "locations" && value !== "lines") {
-          fail(`Unknown locate mode "${value}". Use count, locations, or lines.`);
+        if (value !== "count" && value !== "files" && value !== "locations" && value !== "lines") {
+          fail(`Unknown locate mode "${value}". Use count, files, locations, or lines.`);
           process.exit(1);
         }
         options.mode = value as LiteralMode;

package/src/embeddings/openai.ts

@@ -324,6 +324,8 @@ export interface EmbeddingClient {
     input: string[] | string,
     model: string,
     dimensions?: number,
+    /** True for search queries; sent as a tiny `X-Q` header. Indexing sends nothing. */
+    query?: boolean,
   ): Promise<EmbeddingResponse>;
 }
 
@@ -364,6 +366,7 @@ function createClient(fetchImpl: EmbeddingFetch = fetch): EmbeddingClient {
       input: string[] | string,
       model: string,
       dimensions?: number,
+      query?: boolean,
     ): Promise<EmbeddingResponse> {
       await loadStoredCredentials();
       const apiKey = resolveEmbeddingApiKey();
@@ -376,6 +379,7 @@ function createClient(fetchImpl: EmbeddingFetch = fetch): EmbeddingClient {
         headers: {
           Authorization: `Bearer ${apiKey}`,
           "Content-Type": "application/json",
+          ...(query ? { "X-Q": "1" } : {}),
         },
         body: JSON.stringify(body),
       });
@@ -429,11 +433,11 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
   }
 
   /** Embed pre-windowed inputs; issues a single API request (may 413-split). */
-  async embedInputs(texts: string[]): Promise<Float32Array[]> {
+  async embedInputs(texts: string[], query = false): Promise<Float32Array[]> {
     if (texts.length === 0) {
       return [];
     }
-    const vectors = await this.embedBatchRawWithRetry(texts.map(sanitizeEmbeddingInput));
+    const vectors = await this.embedBatchRawWithRetry(texts.map(sanitizeEmbeddingInput), query);
     for (const vec of vectors) {
       if (this.dimensions === 0 && vec.length > 0) {
         this.dimensions = vec.length;
@@ -442,7 +446,7 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
     return vectors;
   }
 
-  async embedDocuments(texts: string[]): Promise<Float32Array[]> {
+  async embedDocuments(texts: string[], query = false): Promise<Float32Array[]> {
     if (texts.length === 0) {
       return [];
     }
@@ -455,7 +459,10 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
     const batches = batchEmbeddingWindowJobs(jobs, this.batchSize);
     const concurrency = resolveWorkerConcurrency();
     await mapPool(batches, concurrency, async (batch) => {
-      const vectors = await this.embedInputs(batch.map((job) => job.text));
+      const vectors = await this.embedInputs(
+        batch.map((job) => job.text),
+        query,
+      );
       assignEmbeddingWindowVectors(batch, vectors, buckets);
     });
 
@@ -468,7 +475,7 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
     return out;
   }
 
-  private async requestEmbeddings(texts: string[]): Promise<EmbeddingResponse> {
+  private async requestEmbeddings(texts: string[], query: boolean): Promise<EmbeddingResponse> {
     let lastErr: unknown;
     for (let attempt = 0; attempt <= MAX_TRANSIENT_EMBED_RETRIES; attempt++) {
       try {
@@ -477,6 +484,7 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
           texts,
           this.model,
           this.requestedDimensions,
+          query,
         );
         const elapsed = performance.now() - started;
         this.stats.requests += 1;
@@ -498,12 +506,13 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
     throw lastErr;
   }
 
-  private async embedBatchRawWithRetry(texts: string[]): Promise<Float32Array[]> {
+  private async embedBatchRawWithRetry(texts: string[], query: boolean): Promise<Float32Array[]> {
     if (texts.length === 0) {
       return [];
     }
+    const retry = (batch: string[]) => this.embedBatchRawWithRetry(batch, query);
     try {
-      const response = await this.requestEmbeddings(texts);
+      const response = await this.requestEmbeddings(texts, query);
       const vectors = vectorsFromResponse(response.data, texts.length);
       for (const vec of vectors) {
         if (this.requestedDimensions != null && vec.length !== this.requestedDimensions) {
@@ -525,8 +534,8 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
         this.stats.payloadTooLarge += 1;
         this.stats.retries += 1;
         const mid = Math.ceil(texts.length / 2);
-        const left = await this.embedBatchRawWithRetry(texts.slice(0, mid));
-        const right = await this.embedBatchRawWithRetry(texts.slice(mid));
+        const left = await retry(texts.slice(0, mid));
+        const right = await retry(texts.slice(mid));
         return [...left, ...right];
       }
       if (isPayloadTooLargeError(err) && texts.length === 1) {
@@ -544,8 +553,8 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
         const mid = Math.floor(text.length / 2);
         const leftText = text.slice(0, mid);
         const rightText = text.slice(mid);
-        const left = await this.embedBatchRawWithRetry([leftText]);
-        const right = await this.embedBatchRawWithRetry([rightText]);
+        const left = await retry([leftText]);
+        const right = await retry([rightText]);
         const parts = [left[0], right[0]].filter((vec): vec is Float32Array => vec !== undefined);
         if (parts.length === 0) {
           this.stats.errors += 1;
@@ -559,7 +568,7 @@ export class OpenAIEmbeddingBackend implements EmbeddingBackend {
   }
 
   async embedQuery(text: string): Promise<Float32Array> {
-    const [vec] = await this.embedDocuments([text]);
+    const [vec] = await this.embedDocuments([text], true);
     if (!vec) {
       throw new Error("OpenAI returned no embedding for query");
     }

package/src/installer/search-policy.ts

@@ -1,8 +1,15 @@
 /** Shared code-search policy text for instructions, Cursor rules, and sub-agents. */
 
 export const SNIPPET_GUIDANCE =
-  "Search returns compact snippets (~±15 lines). On `truncated: true`, call `expand` with " +
-  "`file_path` and `anchor_line` — only if the snippet doesn't already answer the question.";
+  "Snippets are ~±15 lines. A `truncated: true` hit names its symbol and exact lines (`path:start-end Symbol`) plus `anchor_line`: " +
+  "to see the full body, read exactly those lines with a ranged read (`offset`/`limit`), never the whole file. " +
+  "`expand` (`file_path` + `anchor_line`) is the fallback for neighbouring chunks — only if the snippet doesn't already answer.";
+
+export const WHEN_TO_REACH_FOR_MIRU =
+  "Reach for Miru FIRST, before opening files, whenever you don't know the exact path: starting in unfamiliar code, " +
+  "finding where to edit, how/where/why questions, tracing callers or similar code, docs/config. " +
+  "`locate` also does regex (`/re/`) and lists files by name (`include` globs, no literal). " +
+  "Grep/Glob only for files Miru does not index (lockfiles, binaries, generated or git-ignored).";
 
 export interface NativeToolNames {
   explorationDenied: string;
@@ -14,16 +21,21 @@ export function buildSearchPolicyTable(native: NativeToolNames): string {
   return `| Task | Use | Not |
 |------|-----|-----|
 | Exact literal (identifier, quoted string, env var, error code) | Miru MCP \`locate\` | Miru \`search\`, ${native.grep} |
+| Regex over code | Miru MCP \`locate\` with \`/regex/\` (\`mode=files\` for paths only) | ${native.grep} |
+| List files by name pattern | Miru MCP \`locate\` with \`include\` globs and no literal | Glob |
 | How/where/what handles X? (conceptual) | Miru MCP \`search\` (once) | ${native.grep}, ${native.explorationDenied} |
-| Same file, more context | Miru MCP \`expand\` on \`truncated: true\` | Re-search, ${native.read} whole file |
+| Full body of a \`truncated: true\` hit | ${native.read} the hit's \`start-end\` lines (\`offset\`/\`limit\`) | Re-search, ${native.read} whole file |
+| Same file, neighbouring chunks | Miru MCP \`expand\` (fallback) | Re-search |
 | Similar code elsewhere | Miru MCP \`find_related\` | ${native.grep} chains |
 | Search docs or config | Miru \`search\` | ${native.grep} README paths |
-| Edit a known file:line | ${native.read} (after Miru found it) | ${native.read}-before-search |`;
+| Edit a known file:line | ${native.read} the hit's \`start-end\` lines (after Miru found it) | ${native.read}-before-search |`;
 }
 
 export function buildSearchPolicyBody(native: NativeToolNames): string {
   return `DO NOT use ${native.explorationDenied} to explore how code works when Miru MCP is available.
 
+${WHEN_TO_REACH_FOR_MIRU}
+
 **Check first:** exact token (identifier, quoted string, env var, error code) → \`locate\`. Otherwise → \`search\`.
 
 ${SNIPPET_GUIDANCE}
@@ -31,10 +43,10 @@ ${SNIPPET_GUIDANCE}
 \`repo\` is optional, set it for another repo.
 
 Use Miru MCP tools:
-- \`locate\` — exact substring (env var, symbol, error code); prefer \`mode=count\` or \`locations\`
+- \`locate\` — exact substring (env var, symbol, error code) or \`/regex/\`; no literal + \`include\` globs lists files; prefer \`mode=count\`, \`files\` or \`locations\`
 - \`search\` — one call per conceptual question; use \`include\` / \`exclude\` Gitignore-style globs to scope files (same syntax as \`locate\`)
-- \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\`)
-- \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
+- \`expand\` — fallback: neighbouring chunks in the same file around \`anchor_line\` (\`file_path\` + \`anchor_line\`)
+- \`find_related\` — similar code in other files (hits may also be snippets; read the hit's lines if truncated)
 
 Call shapes:
 - \`locate(literal="<exact substring>")\` — prefer \`mode="locations"\`/\`"count"\`
@@ -43,12 +55,13 @@ Call shapes:
 Stop rules:
 - Literal in the request → \`locate\`, not \`search\`
 - One \`search\` per question — no paraphrase retries
-- \`expand\` only if the snippet doesn't already answer
-- ${native.read} only to edit a path Miru already found, not to explore
+- On \`truncated: true\`, ${native.read} only the hit's \`start-end\` lines (\`offset\`/\`limit\`); \`expand\` only if that doesn't answer
+- ${native.read} only a path Miru already found, to see a truncated body or edit it — never to explore, never the whole file
 
 Native tools are allowed ONLY when:
 - reading a file you already located via Miru, to edit it
 - searching outside the indexed repo
+- files Miru does not index (lockfiles, binaries, generated or git-ignored files)
 
 ${buildSearchPolicyTable(native)}`;
 }
@@ -58,9 +71,9 @@ export function buildMcpWorkflow(native: NativeToolNames): string {
 
 1. Call \`search\`; add \`repo\` only for another repo.
 2. For exact literals, call \`locate\` (prefer \`mode=count\` or \`locations\`).
-3. On \`truncated: true\`, call \`expand\` — only if the snippet doesn't already answer.
-4. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
-5. ${native.read} via \`absolute_path\` only when editing or when \`expand\` still lacks context.`;
+3. On \`truncated: true\`, ${native.read} the hit's \`start-end\` lines (\`offset\`/\`limit\`) — only if the snippet doesn't already answer.
+4. Use \`expand\` for neighbouring chunks if that range lacks context; \`find_related\` to trace similar code in other files.
+5. ${native.read} via \`absolute_path\` only for the hit's range, to see a truncated body or edit it.`;
 }
 
 const CLI_FALLBACK = `### CLI fallback (no MCP in this session)
@@ -116,14 +129,14 @@ export const SUBAGENT_BODY = buildSubagentBody(DEFAULT_NATIVE_TOOLS);
 
 export const MCP_SERVER_INSTRUCTIONS =
   "Miru `search` is your default for all code search queries in indexed repos — the best, fastest, and cheapest way to find code; better than any other tool. " +
-  "DO NOT use Grep, grep_search, codebase_search, Glob, SemanticSearch, or Read to explore code when this server is available. " +
+  `${WHEN_TO_REACH_FOR_MIRU} ` +
+  "DO NOT use Grep, grep_search, codebase_search, Glob, SemanticSearch, or Read to explore code while this server is available. " +
   "Exact token (identifier, quoted string, env var, error code) → `locate`; everything else → `search` once, no paraphrase retries. " +
   `${SNIPPET_GUIDANCE} ` +
-  "`find_related` traces similar code elsewhere, not more context in the same file. " +
-  "`repo` is optional, good for multi repo workflows. " +
-  "Native Grep/Glob only outside the indexed repo or for non-code tasks. " +
-  "Default indexed scope is code, config, and docs; an empty result can mean out-of-scope, not nonexistent. " +
-  "On credential errors, call this server's `auth` tool — not the host `mcp_auth` tool.";
+  "`find_related` finds similar code elsewhere. " +
+  "`repo` is optional (other repos). " +
+  "Indexed scope is code, config, and docs; an empty result can mean out-of-scope, not nonexistent. " +
+  "On credential errors, call this server's `auth` tool, not the host `mcp_auth`.";
 
 export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
   `${MCP_SERVER_INSTRUCTIONS} ` +
@@ -135,26 +148,21 @@ export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
   "To leave benchmark mode, tell the user to run `miru benchmark off` and restart the agent.";
 
 export const MCP_SEARCH_TOOL_DESCRIPTION =
+  "Semantic codebase search: find code by meaning (where/how/what handles X, callers, related code, docs, config) instead of grepping or reading files. Use FIRST when you don't know the exact path. " +
   "Your default search for all code search queries in this indexed repo — the best, fastest, and cheapest way to find code; better than any other tool. " +
-  "Returns up to 5 compact snippets (~±15 lines). One call per question. Use `include` / `exclude` Gitignore-style globs to scope files; these work the same way on `locate`. " +
-  "Exact literal (env var, symbol, error code, quoted text)? Use `locate` instead. " +
-  "On `truncated: true`, call `expand` — only if the snippet doesn't already answer the question.";
+  "Up to 5 snippets (~±15 lines), one call per question; exact literals → `locate`. " +
+  "On `truncated: true`, `expand` only if the snippet doesn't already answer.";
 
 export const MCP_LOCATE_TOOL_DESCRIPTION =
-  "Exact substring locator over the Miru index. Use for known literals (env vars, symbols, error codes, quoted text) — not meaning-based questions (`search`), " +
-  'even ones phrased as "where is X" or "what handles X" if X is a literal. ' +
-  "Returns ALL matches by default as compact {n,files,hits} — do NOT fall back to Grep/rg when n is large. " +
-  "Prefer mode=locations (or count for totals only); use lines when you need matching line text. " +
-  "Optional `limit` only if you intentionally want a sample. " +
-  "Pass an array to `literal` for several spellings in one call. " +
-  '`match_variants: true` also matches other casings (e.g. "rateLimit" also finds "rate_limit"). ' +
-  "`include`/`exclude` (gitignore-style globs) scope to part of a monorepo; " +
-  "`context_lines` in `lines` mode gets inline context instead of a follow-up `expand`. " +
-  "In benchmark mode, includes compact token savings vs agent Grep.";
+  "Exact substring locator over the Miru index, also `/regex/` and file lists (grep for identifiers, env vars, error strings, quoted text, without the noise). " +
+  'Use for known literals, not meaning-based questions (`search`), even when phrased "where is X" if X is a literal. ' +
+  "A literal in slashes (`/foo\\w+Bar/`, `/…/i`) is a regex. No literal + `include` globs lists files by name pattern; mode=files returns just matching paths. " +
+  "Returns ALL matches by default — do NOT fall back to Grep/rg when n is large; prefer mode=count/files/locations unless you need line text. " +
+  "`context_lines` (mode=lines) saves a follow-up `expand`. In benchmark mode, includes token savings vs Grep.";
 
 export const MCP_EXPAND_TOOL_DESCRIPTION =
-  "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` from the hit. " +
-  "Use only if `truncated: true` and the snippet doesn't already answer the question — not for similar code elsewhere (use find_related).";
+  "Neighbouring chunks in the SAME file as a search hit (`file_path` + `anchor_line` from the hit). " +
+  "For a `truncated: true` hit's own full body, read its `start-end` lines instead; use this only if that doesn't answer — not for similar code elsewhere (use find_related).";
 
 export const MCP_FIND_RELATED_TOOL_DESCRIPTION =
   "Find up to 5 chunks similar to a file:line in OTHER parts of the codebase. Results may be snippets; use `expand` when `truncated: true`. " +

package/src/literal.ts

@@ -3,7 +3,7 @@
 import ignore from "ignore";
 import type { Chunk } from "./types.ts";
 
-export type LiteralMode = "count" | "locations" | "lines";
+export type LiteralMode = "count" | "files" | "locations" | "lines";
 
 export const DEFAULT_LITERAL_MODE: LiteralMode = "lines";
 
@@ -31,6 +31,8 @@ export interface LiteralLocateResult {
   /** True only when an explicit `limit` cut the hit list short. */
   truncated: boolean;
   hits: LiteralHit[];
+  /** Sorted unique repo-relative paths. Present only in `files` mode and for file listings. */
+  file_list?: string[];
 }
 
 export interface LiteralLocateOptions {
@@ -54,6 +56,26 @@ export interface LiteralLocateOptions {
   context_lines?: number;
 }
 
+/** A `/body/` (optionally `/body/i`) literal is a regex only if the body has regex syntax, so `/api/users/` stays a plain substring. */
+const SLASH_REGEX = /^\/(.+)\/(i?)$/s;
+const REGEX_SYNTAX = /[\\^$.*+?()[\]{}|]/;
+/** Regex is tested per line; cap the tested prefix so a minified line cannot stall the scan. */
+const MAX_REGEX_LINE_CHARS = 4096;
+
+function parseRegexLiteral(literal: string, ignoreCase: boolean): RegExp | null {
+  const m = SLASH_REGEX.exec(literal);
+  if (!m || !REGEX_SYNTAX.test(m[1] ?? "")) {
+    return null;
+  }
+  try {
+    return new RegExp(m[1] ?? "", ignoreCase || m[2] === "i" ? "i" : "");
+  } catch (err) {
+    throw new Error(
+      `Invalid regex ${literal}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
 function resolveLimit(limit: number | undefined): number | null {
   if (limit == null || !Number.isFinite(limit)) {
     return null;
@@ -61,6 +83,18 @@ function resolveLimit(limit: number | undefined): number | null {
   return Math.max(1, Math.floor(limit));
 }
 
+/** True when any literal would be treated as a regex (so fixed-string baselines are not comparable). */
+export function hasRegexLiteral(literal: string | readonly string[]): boolean {
+  return (Array.isArray(literal) ? literal : [literal]).some(
+    (lit) => parseRegexLiteral(lit, false) !== null,
+  );
+}
+
+function regexMatchesLine(line: string, regexes: readonly RegExp[]): boolean {
+  const tested = line.length > MAX_REGEX_LINE_CHARS ? line.slice(0, MAX_REGEX_LINE_CHARS) : line;
+  return regexes.some((re) => re.test(tested));
+}
+
 function lineMatchesAny(
   haystack: string,
   needles: readonly string[],
@@ -147,6 +181,46 @@ export function filterChunksByGlob(
   });
 }
 
+/**
+ * The AST chunker can split one source line across two adjacent chunks (it divides large
+ * declarations on token boundaries), so neither fragment alone contains the full line. Rejoin
+ * chunks that share a boundary line before scanning, or matches spanning the split are lost.
+ */
+export function stitchSplitLines(chunks: readonly Chunk[]): readonly Chunk[] {
+  const byFile = new Map<string, Chunk[]>();
+  for (const chunk of chunks) {
+    const list = byFile.get(chunk.file_path);
+    if (list) {
+      list.push(chunk);
+    } else {
+      byFile.set(chunk.file_path, [chunk]);
+    }
+  }
+  const stitched: Chunk[] = [];
+  for (const list of byFile.values()) {
+    list.sort((a, b) => a.start_line - b.start_line || a.end_line - b.end_line);
+    let current = list[0];
+    if (!current) {
+      continue;
+    }
+    for (let i = 1; i < list.length; i++) {
+      const next = list[i] as Chunk;
+      if (next.start_line === current.end_line && next.end_line > current.start_line) {
+        current = {
+          ...current,
+          content: current.content + next.content,
+          end_line: Math.max(current.end_line, next.end_line),
+        };
+      } else {
+        stitched.push(current);
+        current = next;
+      }
+    }
+    stitched.push(current);
+  }
+  return stitched;
+}
+
 /**
  * Scan indexed chunks for an exact substring (or, with an array `literal`/`match_variants`,
  * any of several OR-matched substrings). Dedupes by file:line when chunks overlap.
@@ -168,13 +242,27 @@ export function locateLiteral(
 
   const inputLiterals = (Array.isArray(literal) ? literal : [literal]).filter((l) => l.length > 0);
   const label = inputLiterals.join(" | ");
-  const needles = expandLiterals(inputLiterals, options.match_variants === true);
+  const regexes: RegExp[] = [];
+  const plainLiterals: string[] = [];
+  for (const lit of inputLiterals) {
+    const re = parseRegexLiteral(lit, ignoreCase);
+    if (re) {
+      regexes.push(re);
+    } else {
+      plainLiterals.push(lit);
+    }
+  }
+  const needles = expandLiterals(plainLiterals, options.match_variants === true);
+  const matchesLine = (text: string): boolean =>
+    lineMatchesAny(text, needles, ignoreCase) || regexMatchesLine(text, regexes);
 
-  if (needles.length === 0) {
+  if (needles.length === 0 && regexes.length === 0) {
     return { literal: label, mode, n: 0, files: 0, truncated: false, hits: [] };
   }
 
-  const scopedChunks = filterChunksByGlob(chunks, options.include, options.exclude);
+  const scopedChunks = stitchSplitLines(
+    filterChunksByGlob(chunks, options.include, options.exclude),
+  );
 
   const seen = new Set<string>();
   const fileSet = new Set<string>();
@@ -182,13 +270,13 @@ export function locateLiteral(
   let n = 0;
 
   for (const chunk of scopedChunks) {
-    if (!lineMatchesAny(chunk.content, needles, ignoreCase)) {
+    if (regexes.length === 0 && !lineMatchesAny(chunk.content, needles, ignoreCase)) {
       continue;
     }
     const lines = chunk.content.split("\n");
     for (let i = 0; i < lines.length; i++) {
       const lineText = lines[i] ?? "";
-      if (!lineMatchesAny(lineText, needles, ignoreCase)) {
+      if (!matchesLine(lineText)) {
         continue;
       }
       const line = chunk.start_line + i;
@@ -199,7 +287,7 @@ export function locateLiteral(
       seen.add(key);
       fileSet.add(chunk.file_path);
       n += 1;
-      if (mode === "count") {
+      if (mode === "count" || mode === "files") {
         continue;
       }
       if (limit != null && hits.length >= limit) {
@@ -224,15 +312,44 @@ export function locateLiteral(
     mode,
     n,
     files: fileSet.size,
-    truncated: mode !== "count" && limit != null && n > hits.length,
-    hits: mode === "count" ? [] : hits,
+    truncated: mode !== "count" && mode !== "files" && limit != null && n > hits.length,
+    hits: mode === "count" || mode === "files" ? [] : hits,
   };
-  if (needles.length > 1) {
-    result.literals = needles;
+  if (mode === "files") {
+    result.file_list = [...fileSet].sort();
+  }
+  const searched = [...needles, ...inputLiterals.filter((l) => !plainLiterals.includes(l))];
+  if (searched.length > 1) {
+    result.literals = searched;
   }
   return result;
 }
 
+/**
+ * List indexed files, optionally scoped by gitignore-style `include`/`exclude` globs
+ * (the `locate` answer when no literal is given). Only indexed files appear.
+ */
+export function listIndexedFiles(
+  chunks: readonly Chunk[],
+  options: Pick<LiteralLocateOptions, "include" | "exclude" | "mode"> = {},
+): LiteralLocateResult {
+  const mode = options.mode === "count" ? "count" : "files";
+  const files = [
+    ...new Set(
+      filterChunksByGlob(chunks, options.include, options.exclude).map((c) => c.file_path),
+    ),
+  ].sort();
+  return {
+    literal: "",
+    mode,
+    n: files.length,
+    files: files.length,
+    truncated: false,
+    hits: [],
+    ...(mode === "files" ? { file_list: files } : {}),
+  };
+}
+
 /** Compact agent-facing JSON (minimal keys). */
 export function formatLiteralLocate(result: LiteralLocateResult): Record<string, unknown> {
   const base: Record<string, unknown> = {
@@ -249,6 +366,11 @@ export function formatLiteralLocate(result: LiteralLocateResult): Record<string,
     return base;
   }
 
+  if (result.mode === "files") {
+    base.paths = result.file_list ?? [];
+    return base;
+  }
+
   if (result.truncated) {
     base.truncated = true;
   }

package/src/mcp/auth-tool.ts

@@ -34,12 +34,10 @@ const RECOVERY_HINT =
   "signing in, check the account token balance.";
 
 const AUTH_TOOL_DESCRIPTION =
-  "Sign in with Takara credentials via device-code login — no terminal required. " +
-  "Only call this in direct response to a tool error mentioning missing, expired, rejected, or " +
-  "invalid credentials — never speculatively, since it starts a real sign-in prompt for the " +
-  "user. Call with no arguments: it opens the device-login page in the user's browser, then " +
-  "waits (up to about 45 seconds) for them to approve and returns once they have. If it " +
-  'returns "still waiting", tell the user the URL and code and call `auth` again.';
+  "Sign in with Takara device-code login. Only call in direct response to a tool error about " +
+  "missing, expired, rejected, or invalid credentials — never speculatively: it starts a real " +
+  "sign-in prompt. No arguments: opens the login page in the user's browser and waits up to ~45s " +
+  'for approval. If it returns "still waiting", tell the user the URL and code and call `auth` again.';
 
 /** Browser opener seam; the real one spawns a detached `open`/`xdg-open`/`start`. */
 export type BrowserOpener = (url: string) => boolean;
@@ -207,7 +205,7 @@ export function registerAuthTool(
           .enum(["start", "check"])
           .optional()
           .describe(
-            '"start" begins or resumes a device-code login and waits for approval (default); "check" is a single non-blocking poll.',
+            '"start" begins/resumes login and waits for approval (default); "check" polls once.',
           ),
       },
     },

package/src/mcp/format-text.ts

@@ -1,3 +1,4 @@
+import { hasRegexLiteral } from "../literal.ts";
 import type { ExpandResults } from "../utils.ts";
 
 /** Plain-text rendering of `formatResults()` output — same info as the JSON shape, no scaffolding. */
@@ -11,16 +12,58 @@ export function formatResultsText(payload: {
 
   const blocks = payload.results.map((result) => {
     const chunk = result.chunk as Record<string, unknown>;
-    const startLine = chunk.truncated ? chunk.full_start_line : chunk.start_line;
-    const endLine = chunk.truncated ? chunk.full_end_line : chunk.end_line;
-    const truncatedNote = chunk.truncated ? " [truncated: call expand for full chunk]" : "";
-    const header = `${chunk.file_path}:${startLine}-${endLine}${truncatedNote}`;
+    // A truncated hit names the matched symbol's exact range (not the source file's) so the full
+    // body is one ranged read away; `anchor_line` is the matched line for `expand`/`find_related`.
+    const startLine = chunk.truncated
+      ? (chunk.match_start_line ?? chunk.full_start_line)
+      : chunk.start_line;
+    const endLine = chunk.truncated
+      ? (chunk.match_end_line ?? chunk.full_end_line)
+      : chunk.end_line;
+    const symbol = chunk.truncated && chunk.symbol ? ` ${chunk.symbol}` : "";
+    const truncatedNote = chunk.truncated
+      ? ` [truncated: anchor_line ${chunk.anchor_line}; read lines ${startLine}-${endLine} for the full symbol, or call expand]`
+      : "";
+    const header = `${chunk.file_path}:${startLine}-${endLine}${symbol}${truncatedNote}`;
     return `${header}\n${chunk.content}`;
   });
 
   return blocks.join("\n\n");
 }
 
+/** Very long lines (minified bundles, lockfiles) cost far more than they inform. */
+const MAX_LINE_CHARS = 400;
+
+function clipLine(text: string): string {
+  return text.length > MAX_LINE_CHARS
+    ? `${text.slice(0, MAX_LINE_CHARS)}… [+${text.length - MAX_LINE_CHARS} chars]`
+    : text;
+}
+
+/** Group sorted repo-relative paths by directory so each directory prints once. */
+export function formatPathList(paths: readonly string[]): string {
+  const byDir = new Map<string, string[]>();
+  for (const path of paths) {
+    const slash = path.lastIndexOf("/");
+    const dir = slash < 0 ? "./" : path.slice(0, slash + 1);
+    const names = byDir.get(dir);
+    const name = slash < 0 ? path : path.slice(slash + 1);
+    if (names) {
+      names.push(name);
+    } else {
+      byDir.set(dir, [name]);
+    }
+  }
+  // A directory holding one match prints as a plain path; grouping only pays off for two or more.
+  return [...byDir]
+    .map(([dir, names]) =>
+      names.length === 1
+        ? `${dir === "./" ? "" : dir}${names[0]}`
+        : `${dir}\n  ${names.join("\n  ")}`,
+    )
+    .join("\n");
+}
+
 /** Plain-text rendering of `formatLiteralLocate()` output. */
 export function formatLiteralLocateText(payload: Record<string, unknown>): string {
   const label =
@@ -28,7 +71,19 @@ export function formatLiteralLocateText(payload: Record<string, unknown>): strin
   const n = payload.n as number;
   const files = payload.files as number;
   const truncatedNote = payload.truncated ? " (truncated — pass a narrower include/exclude)" : "";
-  const header = `"${label}": ${n} match${n === 1 ? "" : "es"} across ${files} file${files === 1 ? "" : "s"}${truncatedNote}`;
+  const fileCount = `${files} file${files === 1 ? "" : "s"}`;
+  // Short plain literals are worth echoing; a regex the caller just sent is not (it tokenizes poorly).
+  const counts = `${n} match${n === 1 ? "" : "es"} across ${fileCount}${truncatedNote}`;
+  const header = !label
+    ? fileCount
+    : hasRegexLiteral(label.split(" | "))
+      ? counts
+      : `"${label}": ${counts}`;
+
+  const paths = payload.paths as string[] | undefined;
+  if (paths) {
+    return paths.length === 0 ? header : `${header}\n\n${formatPathList(paths)}`;
+  }
 
   const hits = payload.hits as
     | Array<{ f: string; l: number; t?: string; ctx?: string[]; ctx_l?: number }>
@@ -38,12 +93,40 @@ export function formatLiteralLocateText(payload: Record<string, unknown>): strin
   }
 
   const lines = [header, ""];
+  if (hits.some((hit) => hit.ctx != null)) {
+    for (const hit of hits) {
+      lines.push(
+        hit.t !== undefined ? `${hit.f}:${hit.l}: ${clipLine(hit.t)}` : `${hit.f}:${hit.l}`,
+      );
+      if (hit.ctx != null && hit.ctx_l !== undefined) {
+        const ctxStart = hit.ctx_l;
+        for (let i = 0; i < hit.ctx.length; i++) {
+          lines.push(`  ${ctxStart + i}: ${clipLine(hit.ctx[i] ?? "")}`);
+        }
+      }
+    }
+    return lines.join("\n");
+  }
+
+  // Each path once: `path` then indented `line: text`, or `path: 3, 9, 40` without text.
+  const byFile = new Map<string, Array<{ l: number; t?: string }>>();
   for (const hit of hits) {
-    lines.push(hit.t !== undefined ? `${hit.f}:${hit.l}: ${hit.t}` : `${hit.f}:${hit.l}`);
-    if (hit.ctx != null && hit.ctx_l !== undefined) {
-      const ctxStart = hit.ctx_l;
-      for (let i = 0; i < hit.ctx.length; i++) {
-        lines.push(`  ${ctxStart + i}: ${hit.ctx[i]}`);
+    const group = byFile.get(hit.f);
+    if (group) {
+      group.push({ l: hit.l, t: hit.t });
+    } else {
+      byFile.set(hit.f, [{ l: hit.l, t: hit.t }]);
+    }
+  }
+  for (const [file, group] of byFile) {
+    if (group.every((hit) => hit.t === undefined)) {
+      lines.push(`${file}: ${group.map((hit) => hit.l).join(", ")}`);
+    } else if (group.length === 1) {
+      lines.push(`${file}:${group[0]?.l}: ${clipLine(group[0]?.t ?? "")}`);
+    } else {
+      lines.push(file);
+      for (const hit of group) {
+        lines.push(`  ${hit.l}: ${clipLine(hit.t ?? "")}`);
       }
     }
   }

package/src/mcp/runtime.ts

@@ -24,6 +24,7 @@ type ToolHandler<Args> = (args: Args) => Promise<{
 
 type RegisteredTool = {
   description: string;
+  meta?: Record<string, unknown>;
   inputSchema: Record<string, z.ZodType>;
   handler: ToolHandler<Record<string, unknown>>;
 };
@@ -49,11 +50,13 @@ export class MiruMcpServer {
     config: {
       description: string;
       inputSchema: S;
+      _meta?: Record<string, unknown>;
     },
     handler: ToolHandler<z.infer<z.ZodObject<S>>>,
   ): void {
     this.tools.set(name, {
       description: config.description,
+      meta: config._meta,
       inputSchema: config.inputSchema,
       handler: handler as ToolHandler<Record<string, unknown>>,
     });
@@ -163,6 +166,7 @@ export class MiruMcpServer {
       name,
       description: tool.description,
       inputSchema: shapeToJsonSchema(tool.inputSchema),
+      ...(tool.meta ? { _meta: tool.meta } : {}),
     }));
   }
 
@@ -234,8 +238,32 @@ function isNotification(message: JsonRpcMessage): message is { jsonrpc: "2.0"; m
   return "method" in message && !("id" in message);
 }
 
+/**
+ * Trim schema noise that costs tokens on every session but tells the model nothing: zod emits
+ * Number.MAX_SAFE_INTEGER / MIN_SAFE_INTEGER bounds for every `.int()`, plus `minLength: 1` and
+ * `minItems: 1` on non-empty strings and arrays. Validation still runs in zod at call time.
+ */
+function stripImplicitIntegerBounds(node: unknown): unknown {
+  if (Array.isArray(node)) {
+    return node.map(stripImplicitIntegerBounds);
+  }
+  if (node && typeof node === "object") {
+    return Object.fromEntries(
+      Object.entries(node as Record<string, unknown>)
+        .filter(
+          ([key, value]) =>
+            !(key === "maximum" && value === Number.MAX_SAFE_INTEGER) &&
+            !(key === "minimum" && value === Number.MIN_SAFE_INTEGER) &&
+            !((key === "minLength" || key === "minItems") && value === 1),
+        )
+        .map(([key, value]) => [key, stripImplicitIntegerBounds(value)]),
+    );
+  }
+  return node;
+}
+
 function shapeToJsonSchema(shape: Record<string, z.ZodType>): Record<string, unknown> {
   const schema = z.toJSONSchema(z.object(shape)) as Record<string, unknown>;
   const { $schema: _schema, ...rest } = schema;
-  return rest;
+  return stripImplicitIntegerBounds(rest) as Record<string, unknown>;
 }

package/src/mcp/server.ts

@@ -21,7 +21,7 @@ import {
   MCP_SEARCH_TOOL_DESCRIPTION,
   MCP_SERVER_INSTRUCTIONS,
 } from "../installer/search-policy.ts";
-import { formatLiteralLocate } from "../literal.ts";
+import { formatLiteralLocate, hasRegexLiteral, listIndexedFiles } from "../literal.ts";
 import type { Chunk, ContentType, SearchResult } from "../types.ts";
 import {
   DEFAULT_EXPAND_AFTER,
@@ -44,8 +44,7 @@ import { getIndexForRepo, type IndexCache, toolText } from "./index-cache.ts";
 import { MiruMcpServer } from "./runtime.ts";
 
 const REPO_DESCRIPTION =
-  "`repo` is optional. Set a local path or Git URL for another repo. " +
-  "The index is built on the first tool call and cached for the session.";
+  "`repo` is optional: local path or Git URL (default: the server's directory).";
 
 const BENCHMARK_SKIP_NOTES = {
   local_repo_only: "Benchmark comparisons require a local repo path; git URL repos are skipped.",
@@ -55,6 +54,8 @@ const BENCHMARK_SKIP_NOTES = {
     "Benchmark comparison skipped: locate.limit is global, while rg/grep limits are per file. Omit limit for a valid token and recall comparison.",
   incompatible_literal_baseline:
     "Benchmark comparison skipped: a comparable literal baseline requires rg or compatible grep. Windows findstr does not preserve locate scope, context, or count semantics.",
+  regex_or_file_list:
+    "Benchmark comparison skipped: regex and file-list locate calls have no equivalent fixed-string rg baseline.",
   grep_timeout:
     "Benchmark Grep baseline timed out; Miru results are still returned. " +
     "Raise MIRU_BENCHMARK_SEARCH_TIMEOUT (seconds) if needed.",
@@ -118,6 +119,9 @@ async function persistBenchmarkQuery(
   }
 }
 
+/** Claude Code defers MCP tools behind ToolSearch by default; keep Miru visible next to Grep/Glob/Read, including to subagents. */
+const LOAD_UPFRONT_META = { "anthropic/alwaysLoad": true };
+
 export function createMcpServer(
   cache: IndexCache,
   options?: {
@@ -155,32 +159,24 @@ export function createMcpServer(
   server.registerTool(
     "search",
     {
-      description: `${MCP_SEARCH_TOOL_DESCRIPTION} Indexes the selected directory or URL on first call; later calls reuse the session cache.`,
+      description: MCP_SEARCH_TOOL_DESCRIPTION,
+      _meta: LOAD_UPFRONT_META,
       inputSchema: {
-        query: z
-          .string()
-          .describe(
-            "Natural language or code query — your default for all code search in this repo.",
-          ),
+        query: z.string().describe("Natural language or code query."),
         repo: z.string().optional().describe(REPO_DESCRIPTION),
         include: z
           .array(z.string().min(1))
           .min(1)
           .optional()
           .describe(
-            'Gitignore-style glob patterns; only matching files are searched (e.g. ["src/auth/**", "docs/**/*.md"]). Same semantics as `locate.include`.',
+            'Gitignore-style globs; only matching files are searched, e.g. ["src/auth/**"]. Same as `locate.include`.',
           ),
         exclude: z
           .array(z.string().min(1))
           .min(1)
           .optional()
-          .describe(
-            "Gitignore-style glob patterns; matching files are skipped. Same semantics as `locate.exclude`.",
-          ),
-        dedupe_by_file: z
-          .boolean()
-          .optional()
-          .describe("Keep only the best hit per file (default true)."),
+          .describe("Gitignore-style globs; matching files are skipped. Same as `locate.exclude`."),
+        dedupe_by_file: z.boolean().optional().describe("One best hit per file (default true)."),
       },
     },
     async ({ query, repo, include, exclude, dedupe_by_file: dedupeByFile }) => {
@@ -248,26 +244,24 @@ export function createMcpServer(
     "locate",
     {
       description: MCP_LOCATE_TOOL_DESCRIPTION,
+      _meta: LOAD_UPFRONT_META,
       inputSchema: {
         literal: z
           .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
           .optional()
           .describe(
-            "Exact substring to find (env var, symbol, error code, quoted text). " +
-              "Pass an array to OR-match several substrings (e.g. spelling/casing variants) in one call.",
+            "Exact substring, or a regex in slashes like `/foo\\w+Bar/` (`/…/i` ignores case). An array ORs several. Omit and pass `include` to list files.",
           ),
         query: z
           .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
           .optional()
-          .describe(
-            "Alias for `literal` — accepted so a call shaped like `search(query=...)` still resolves as an exact-substring lookup.",
-          ),
+          .describe("Alias for `literal`."),
         repo: z.string().optional().describe(REPO_DESCRIPTION),
         mode: z
-          .enum(["count", "locations", "lines"])
+          .enum(["count", "files", "locations", "lines"])
           .optional()
           .describe(
-            "count=totals only; locations=path:line; lines=path:line+text (default). Prefer count/locations when possible.",
+            "count=totals; files=unique paths; locations=path:lines; lines=path:line+text (default).",
           ),
         limit: z
           .number()
@@ -275,46 +269,56 @@ export function createMcpServer(
           .min(1)
           .optional()
           .describe(
-            "Optional cap on returned hits. Omit to return ALL matches (recommended). Do not fall back to Grep if n is large — use mode=count or locations instead.",
+            "Cap on hits. Omit for ALL matches (recommended); if n is large use mode=count/files, not Grep.",
           ),
-        ignore_case: z.boolean().optional().describe("Case-insensitive match (default false)."),
+        ignore_case: z.boolean().optional().describe("Case-insensitive (default false)."),
         match_variants: z
           .boolean()
           .optional()
-          .describe(
-            'Also match other ways the same word might be written in code, e.g. "rateLimit" also finds "rate_limit" and "RATE_LIMIT".',
-          ),
+          .describe('Also match other casings, e.g. "rateLimit" finds "rate_limit", "RATE_LIMIT".'),
         include: z
           .array(z.string().min(1))
           .optional()
           .describe(
-            'Gitignore-style glob patterns; only matching files are searched (e.g. "apps/tldr/**/*.go").',
+            'Gitignore-style globs; only matching files are searched, e.g. ["apps/**/*.go"].',
           ),
         exclude: z
           .array(z.string().min(1))
           .optional()
-          .describe("Gitignore-style glob patterns; matching files are skipped."),
+          .describe("Gitignore-style globs; matching files are skipped."),
         context_lines: z
           .number()
           .int()
           .min(0)
           .optional()
-          .describe("Lines of context before/after each match, like `grep -C` (mode=lines only)."),
+          .describe("Context lines around each match (mode=lines only)."),
       },
     },
     async ({ literal, query, repo, ...locateOpts }) => {
       const lit = literal ?? query;
-      if (lit == null) {
-        return toolErrorText(new Error("locate requires `literal` (exact substring to find)."));
+      if (lit == null && !locateOpts.include?.length) {
+        return toolErrorText(
+          new Error(
+            "locate requires `literal` (exact substring or /regex/), or `include` globs to list files.",
+          ),
+        );
       }
       try {
         const source = repo ?? defaultRepo;
         const index = await getIndexForRepo(source, cache);
 
+        if (lit == null) {
+          const listing = listIndexedFiles(index.chunks, locateOpts);
+          const body = formatLiteralLocateText(formatLiteralLocate(listing));
+          return toolText(benchmark ? withBenchmarkSkippedNote(body, "regex_or_file_list") : body);
+        }
+
         let skip: BenchmarkSkipReason | undefined;
         const repoRoot = localRepoRoot(source);
         if (benchmark && repoRoot && typeof lit === "string") {
-          if (locateOpts.limit != null) {
+          if (locateOpts.mode === "files" || hasRegexLiteral(lit)) {
+            skip = "regex_or_file_list";
+          } else if (locateOpts.limit != null) {
             skip = "limited_locate";
           } else if (!selectLiteralBaseline()) {
             skip = "incompatible_literal_baseline";
@@ -353,27 +357,26 @@ export function createMcpServer(
     "expand",
     {
       description: MCP_EXPAND_TOOL_DESCRIPTION,
+      _meta: LOAD_UPFRONT_META,
       inputSchema: {
-        file_path: z
-          .string()
-          .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
+        file_path: z.string().describe("Path from a search hit."),
         anchor_line: z
           .number()
           .int()
-          .describe("Line from the search hit (`anchor_line` when truncated, else `start_line`)."),
+          .describe("Line from the hit (`anchor_line` if truncated, else `start_line`)."),
         repo: z.string().optional().describe(REPO_DESCRIPTION),
         before: z
           .number()
           .int()
           .min(0)
           .optional()
-          .describe(`Extra chunks before the anchor (default ${DEFAULT_EXPAND_BEFORE}).`),
+          .describe(`Extra chunks before (default ${DEFAULT_EXPAND_BEFORE}).`),
         after: z
           .number()
           .int()
           .min(0)
           .optional()
-          .describe(`Extra chunks after the anchor (default ${DEFAULT_EXPAND_AFTER}).`),
+          .describe(`Extra chunks after (default ${DEFAULT_EXPAND_AFTER}).`),
       },
     },
     async ({ file_path: filePath, anchor_line: anchorLine, repo, before, after }) => {
@@ -415,14 +418,13 @@ export function createMcpServer(
     "find_related",
     {
       description: MCP_FIND_RELATED_TOOL_DESCRIPTION,
+      _meta: LOAD_UPFRONT_META,
       inputSchema: {
-        file_path: z
-          .string()
-          .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
+        file_path: z.string().describe("Path from a search hit."),
         anchor_line: z
           .number()
           .int()
-          .describe("Line from the search hit (`anchor_line` when truncated, else `start_line`)."),
+          .describe("Line from the hit (`anchor_line` if truncated, else `start_line`)."),
         repo: z.string().optional().describe(REPO_DESCRIPTION),
       },
     },

package/src/snippet.ts

@@ -13,6 +13,11 @@ export interface SnippetMeta {
   anchor_line: number;
   full_start_line: number;
   full_end_line: number;
+  /** Exact lines of the matched (ranked) chunk — the symbol-sized range to read, not the source file. */
+  match_start_line: number;
+  match_end_line: number;
+  /** Name of the symbol the matched chunk declares, when one is recognizable. */
+  symbol: string | null;
 }
 
 export interface SnippetResult {
@@ -73,6 +78,24 @@ function scoreLine(line: string, terms: Set<string>): number {
 
 const DECLARATION_RE =
   /^\s*(?:export\s+)?(?:default\s+)?(?:async\s+)?(?:function|class|interface|enum|type|struct|trait|impl|record|namespace|contract|library|object)\b|^\s*(?:export\s+)?(?:const|let|var)\s+[$\w]+\s*=\s*[{[(]|^\s*(?:async\s+)?def\s+\w+|^\s*def\s+\w+|^\s*fn\s+\w+|^\s*func\s+\w+|^\s*defmodule\b|^\s*def\w*\b|^\s*(?:(?:public|private|protected|internal|static|final|abstract|virtual|override|sealed|partial|unsafe|extern)\s+)+(?:[A-Za-z_$][\w:<>[\]?.,\s]*\s+)+[A-Za-z_$]\w*\s*\(|^\s*(?:void|bool|boolean|char|short|int|long|float|double|string|[A-Z][\w:<>[\]?.,]*)\s+[A-Za-z_$]\w*\s*\(|^\s*(?:function\s+)?[A-Za-z_]\w*\s*\(\)\s*\{/;
+const DECLARED_NAME_RE =
+  /\b(?:function\*?|class|interface|enum|type|struct|trait|impl|record|namespace|contract|library|object|def|fn|func|defmodule)\s+([A-Za-z_$][\w$]*)|\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/;
+
+/** Name declared by the first declaration line in `content`, or null when none is recognizable. */
+export function declaredSymbol(content: string): string | null {
+  for (const line of content.split("\n").slice(0, MAX_DECLARATION_LOOKBACK)) {
+    if (!DECLARATION_RE.test(line)) {
+      continue;
+    }
+    const match = DECLARED_NAME_RE.exec(line);
+    const name = match?.[1] ?? match?.[2];
+    if (name) {
+      return name;
+    }
+  }
+  return null;
+}
+
 const BRACE_BODY_RE =
   /\b(?:function|class|interface|enum|struct|trait|impl|record|namespace|contract|library|object|fn|func)\b|=\s*[{[(]|[A-Za-z_$]\w*\s*\([^)]*\)\s*\{/;
 const RUBY_OR_ELIXIR_BODY_RE = /^\s*def\w*\b|^\s*defmodule\b/;
@@ -419,6 +442,9 @@ export function trimChunkToSnippet(
         anchor_line: chunk.start_line + anchorOffset,
         full_start_line: chunk.start_line,
         full_end_line: chunk.end_line,
+        match_start_line: chunk.start_line,
+        match_end_line: chunk.end_line,
+        symbol: declaredSymbol(chunk.content),
       },
     };
   }
@@ -436,6 +462,9 @@ export function trimChunkToSnippet(
       anchor_line: chunk.start_line + anchorOffset,
       full_start_line: chunk.start_line,
       full_end_line: chunk.end_line,
+      match_start_line: chunk.start_line,
+      match_end_line: chunk.end_line,
+      symbol: declaredSymbol(chunk.content),
     },
   };
 }
@@ -460,8 +489,20 @@ export function applySnippetsToResults(
   });
   return contextualResults.map(({ result, anchorLine }, rank) => {
     const { chunk, meta } = trimChunkToSnippet(result.chunk, query, radius, anchorLine);
+    // `result.chunk` may be the whole source file; the ranked chunk is the symbol-sized match.
+    const ranked = results[rank]?.chunk;
     const snippet = compactSupportingSnippet(
-      { chunk, meta },
+      {
+        chunk,
+        meta: ranked
+          ? {
+              ...meta,
+              match_start_line: ranked.start_line,
+              match_end_line: ranked.end_line,
+              symbol: declaredSymbol(ranked.content) ?? meta.symbol,
+            }
+          : meta,
+      },
       rank === 0 ? primaryMaxLines : supportingMaxLines,
     );
     return { result: { chunk: snippet.chunk, score: result.score }, meta: snippet.meta };

package/src/utils.ts

@@ -210,6 +210,9 @@ export function formatResults(
             anchor_line: entry.meta.anchor_line,
             full_start_line: entry.meta.full_start_line,
             full_end_line: entry.meta.full_end_line,
+            match_start_line: entry.meta.match_start_line,
+            match_end_line: entry.meta.match_end_line,
+            ...(entry.meta.symbol ? { symbol: entry.meta.symbol } : {}),
           },
           score,
         };