@takara-ai/miru-code 0.4.12 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "0.4.12",
+  "version": "0.5.0",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,9 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "prepublishOnly": "bun run typecheck && bun test",
+    "benchmark:ab": "bun run scripts/search-ab-local.ts",
+    "benchmark:ab-multi": "bun run scripts/search-ab-multi.ts",
+    "benchmark:recall": "bun run scripts/benchmark-recall-tokens.ts",
     "benchmark:quality": "bun run scripts/benchmark-quality.ts",
     "benchmark:quantization": "bun run scripts/benchmark-quantization.ts"
   },

package/src/agents/claude.md

@@ -3,30 +3,3 @@ 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
 ---
-
-When Miru MCP is available, use MCP `search`, `expand`, and `find_related` — not Grep, Glob, or Read-for-exploration.
-
-| Task | Tool |
-|------|------|
-| How/where/what handles X? | Miru `search` (once) |
-| Same file, more context | Miru `expand` |
-| Similar implementations | Miru `find_related` |
-| Exact literal confirmation | Grep |
-| Edit a located file | Read |
-
-### MCP workflow
-
-1. Call `search` with `repo` set to the project root.
-2. If context is cut off, call `expand` with the hit's `file_path` and `line`.
-3. Use `find_related` for similar code in other files — not for same-file context.
-4. Read files only to edit or when `expand` still lacks context.
-
-### CLI fallback
-
-```bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-```
-
-If `miru` is not on `$PATH`, use `bunx @takara-ai/miru-code`.

package/src/agents/copilot.md

@@ -2,15 +2,3 @@
 name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related instead of grep_search or codebase_search when Miru is connected.
 ---
-
-When Miru MCP is available, use `search`, `expand`, and `find_related` instead of `grep_search`, `codebase_search`, or broad file reads.
-
-| Task | Tool |
-|------|------|
-| How/where/what handles X? | Miru `search` (once) |
-| Same file, more context | Miru `expand` |
-| Similar implementations | Miru `find_related` |
-| Exact literal confirmation | grep_search |
-| Edit a located file | read_file |
-
-Pass project root as `repo` on every MCP call.

package/src/agents/cursor.md

@@ -2,29 +2,3 @@
 name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related. DO NOT use Grep, Glob, or SemanticSearch when Miru MCP is available.
 ---
-
-Use Miru MCP tools when connected:
-
-- `search` — one call per question; always pass project root as `repo`
-- `expand` — adjacent chunks in the same file when a hit looks truncated (`file_path` + `line`)
-- `find_related` — similar code in other files after a search hit
-
-Do not re-search with paraphrases after a good first hit. Do not read whole files for exploration.
-
-| Task | Tool |
-|------|------|
-| How/where/what handles X? | Miru `search` (once) |
-| Same file, more context | Miru `expand` |
-| Similar implementations | Miru `find_related` |
-| Exact literal confirmation | Grep |
-| Edit a located file | Read |
-
-CLI fallback when MCP is unavailable:
-
-```bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-```
-
-If `miru` is not on `$PATH`, use `bunx @takara-ai/miru-code`.

package/src/agents/gemini.md

@@ -2,17 +2,3 @@
 name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related instead of grep_search or read_file for exploration.
 ---
-
-When Miru MCP is available, use `search`, `expand`, and `find_related` instead of `grep_search`, `glob`, or `read_file` for codebase exploration.
-
-| Task | Tool |
-|------|------|
-| How/where/what handles X? | Miru `search` (once) |
-| Same file, more context | Miru `expand` |
-| Similar implementations | Miru `find_related` |
-| Exact literal confirmation | grep_search |
-| Edit a located file | read_file |
-
-Pass project root as `repo` on every MCP call. Do not re-search with paraphrases after a good first hit.
-
-CLI fallback: `miru search "query" .` or `bunx @takara-ai/miru-code search "query" .`

package/src/agents/kiro.md

@@ -2,9 +2,3 @@
 name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related for codebase exploration instead of built-in grep or file search.
 ---
-
-When Miru MCP is available, use `search`, `expand`, and `find_related` before any built-in search or broad file reads.
-
-Pass project root as `repo`. Use `expand` for truncated hits in the same file. Use Grep only for exact literal confirmation.
-
-CLI fallback: `miru search "query" .`

package/src/agents/opencode.md

@@ -3,9 +3,3 @@ name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related instead of grep or glob for exploration.
 mode: subagent
 ---
-
-When Miru MCP is available, use `search`, `expand`, and `find_related` instead of grep, glob, or read-for-exploration.
-
-Pass project root as `repo` on every MCP call.
-
-CLI fallback: `miru search "query" .`

package/src/agents.ts

@@ -1,17 +1,56 @@
 import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import {
+  buildSubagentBody,
+  type NativeToolNames,
+} from "./installer/search-policy.ts";
 
 export type AgentId = "claude" | "copilot" | "cursor" | "gemini" | "kiro" | "opencode";
 
 const AGENTS_DIR = join(import.meta.dir, "agents");
 
+const AGENT_NATIVE_TOOLS: Record<AgentId, NativeToolNames> = {
+  claude: {
+    explorationDenied: "Grep, Glob, SemanticSearch, or Read",
+    grep: "Grep",
+    read: "Read",
+  },
+  cursor: {
+    explorationDenied: "Grep, Glob, SemanticSearch, or Read",
+    grep: "Grep",
+    read: "Read",
+  },
+  copilot: {
+    explorationDenied: "grep_search, codebase_search, glob, or read_file",
+    grep: "grep_search",
+    read: "read_file",
+  },
+  gemini: {
+    explorationDenied: "grep_search, glob, or read_file",
+    grep: "grep_search",
+    read: "read_file",
+  },
+  kiro: {
+    explorationDenied: "built-in grep, file search, or broad file reads",
+    grep: "Grep",
+    read: "Read",
+  },
+  opencode: {
+    explorationDenied: "grep, glob, or read-for-exploration",
+    grep: "grep",
+    read: "read",
+  },
+};
+
 export function agentDestination(agent: AgentId): string {
   const baseDir = agent === "copilot" ? ".github" : `.${agent}`;
   return join(baseDir, "agents", "miru-code.md");
 }
 
 export async function loadAgentTemplate(agent: AgentId): Promise<string> {
-  return readFile(join(AGENTS_DIR, `${agent}.md`), "utf-8");
+  const frontmatter = (await readFile(join(AGENTS_DIR, `${agent}.md`), "utf-8")).trim();
+  const body = buildSubagentBody(AGENT_NATIVE_TOOLS[agent]);
+  return `${frontmatter}\n\n${body}\n`;
 }
 
 export async function writeAgentFile(

package/src/index/create.ts

@@ -9,8 +9,10 @@ import { BM25Index } from "./bm25.ts";
 import { walkFiles } from "./file-walker.ts";
 import { detectLanguage, getExtensions, getFileStatus, readFileText } from "./files.ts";
 import type { SemanticIndex } from "./semantic-index.ts";
+import { loadRootEntryChunks } from "./entry-chunks.ts";
 import { enrichForBm25 } from "./sparse.ts";
 import { buildSemanticIndex } from "./vector-storage.ts";
+import { searchImprovementsEnabled } from "../ranking/features.ts";
 
 const DEFAULT_PIPELINE_EMBED_BATCH = 64;
 const DEFAULT_PIPELINE_EMBED_INFLIGHT = 8;
@@ -145,6 +147,17 @@ export async function createIndexFromPath(
     await Promise.race(runningFiles);
   }
 
+  if (searchImprovementsEnabled()) {
+    const entryChunks = await loadRootEntryChunks(
+      resolved,
+      displayRoot ? root : undefined,
+    );
+    if (entryChunks.length > 0) {
+      readyBySeq.set(fileSeq++, entryChunks);
+      flushReadySequentialChunks();
+    }
+  }
+
   flushReadySequentialChunks();
   await maybeScheduleEmbed(true);
   await Promise.all(embedPromises);

package/src/index/entry-chunks.ts

@@ -0,0 +1,71 @@
+import { join, relative } from "node:path";
+import type { Chunk } from "../types.ts";
+
+function indexedPath(absPath: string, repoRoot: string, displayRoot?: string): string {
+  if (displayRoot) {
+    return relative(displayRoot, absPath).replace(/\\/g, "/");
+  }
+  return absPath.replace(/\\/g, "/");
+}
+
+async function packageJsonEntryChunks(
+  absPath: string,
+  repoRoot: string,
+  displayRoot?: string,
+): Promise<Chunk[]> {
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(await Bun.file(absPath).text()) as Record<string, unknown>;
+  } catch {
+    return [];
+  }
+
+  const entryLines = ["[package entry]"];
+
+  const bin = pkg.bin;
+  if (typeof bin === "string") {
+    entryLines.push(`bin: ${bin}`);
+  } else if (bin && typeof bin === "object") {
+    for (const [name, target] of Object.entries(bin)) {
+      entryLines.push(`bin ${name}: ${String(target)}`);
+    }
+  }
+
+  if (typeof pkg.main === "string") {
+    entryLines.push(`main: ${pkg.main}`);
+  }
+
+  const types = pkg.types ?? pkg.typings;
+  if (typeof types === "string") {
+    entryLines.push(`types: ${types}`);
+  }
+
+  if (entryLines.length <= 1) {
+    return [];
+  }
+
+  const filePath = indexedPath(absPath, repoRoot, displayRoot);
+  const content = `${entryLines.join("\n")}\n`;
+
+  return [
+    {
+      content,
+      file_path: filePath,
+      start_line: 1,
+      end_line: entryLines.length,
+      language: "json",
+    },
+  ];
+}
+
+/** Synthetic chunks for root config entry points (bin/main) when indexing code repos. */
+export async function loadRootEntryChunks(
+  repoRoot: string,
+  displayRoot?: string,
+): Promise<Chunk[]> {
+  const pkgPath = join(repoRoot, "package.json");
+  if (!(await Bun.file(pkgPath).exists())) {
+    return [];
+  }
+  return packageJsonEntryChunks(pkgPath, repoRoot, displayRoot);
+}

package/src/installer/hooks/search-guard.ts

@@ -1,3 +1,5 @@
+import { SEARCH_GUARD_EXPAND_HINT } from "../search-policy.ts";
+
 const REDIRECT_PREFIX =
   "Use Miru MCP instead of built-in search tools (pass project root as `repo`). " +
   "Grep/Glob/Shell are only for exact literal confirmation or non-code tasks.";
@@ -119,10 +121,7 @@ export function searchGuardBlockReason(
   toolInput: Record<string, unknown>,
 ): string {
   const query = suggestedMiruQuery(toolName, toolInput);
-  return (
-    `${REDIRECT_PREFIX} Try Miru \`search\` with query "${query}". ` +
-    "If the hit looks truncated, call `expand` on its file_path + line — do not re-search or read the whole file."
-  );
+  return `${REDIRECT_PREFIX} Try Miru \`search\` with query "${query}". ${SEARCH_GUARD_EXPAND_HINT}`;
 }
 
 /** Map host-specific stdin JSON into a common evaluation shape. */

package/src/installer/prompt.ts

@@ -15,11 +15,31 @@ const ESC = "\x1b";
 const HIDE_CURSOR = `${ESC}[?25l`;
 const SHOW_CURSOR = `${ESC}[?25h`;
 const CLEAR_LINE = `${ESC}[2K`;
+const CURSOR_START = `${ESC}[G`;
 
 function writeRaw(text: string): void {
   output.write(text);
 }
 
+function createFrameWriter(): (lines: string[]) => void {
+  let previousLineCount = 0;
+
+  return (lines: string[]) => {
+    if (previousLineCount > 0) {
+      writeRaw(`${ESC}[${previousLineCount}A${CURSOR_START}`);
+    }
+    writeRaw(`${CLEAR_LINE}${lines.join(`\n${CLEAR_LINE}`)}\n`);
+    const extra = previousLineCount - lines.length;
+    if (extra > 0) {
+      for (let i = 0; i < extra; i++) {
+        writeRaw(`${CLEAR_LINE}\n`);
+      }
+      writeRaw(`${ESC}[${extra}A${CURSOR_START}`);
+    }
+    previousLineCount = lines.length;
+  };
+}
+
 function readKey(): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const onData = (chunk: Buffer) => {
@@ -90,12 +110,12 @@ async function withRawMode<T>(fn: () => Promise<T>): Promise<T> {
   }
 }
 
-function renderMultiSelect<T>(
+function buildMultiSelectLines<T>(
   title: string,
   items: Array<{ label: string; value: T; checked: boolean }>,
   cursor: number,
   footer: string,
-): void {
+): string[] {
   const lines: string[] = [];
   lines.push("");
   lines.push(bold(title));
@@ -113,7 +133,7 @@ function renderMultiSelect<T>(
   }
   lines.push("");
   lines.push(dim(footer));
-  writeRaw(`${CLEAR_LINE}${lines.join(`\n${CLEAR_LINE}`)}\n`);
+  return lines;
 }
 
 export async function promptMultiSelect<T>(
@@ -130,10 +150,11 @@ export async function promptMultiSelect<T>(
 
   const footer = "↑↓ move  space toggle  a all  enter confirm  ctrl-c cancel";
   let cursor = 0;
+  const drawFrame = createFrameWriter();
 
   return withRawMode(async () => {
     while (true) {
-      renderMultiSelect(title, items, cursor, footer);
+      drawFrame(buildMultiSelectLines(title, items, cursor, footer));
       const key = parseKey(await readKey());
 
       if (key === "ctrl-c") {
@@ -163,11 +184,13 @@ export async function promptMultiSelect<T>(
   });
 }
 
-function renderConfirm(question: string, yesSelected: boolean): void {
+function buildConfirmLines(question: string, yesSelected: boolean): string[] {
   const yes = yesSelected ? green(bold(" Yes ")) : dim(" Yes ");
   const no = yesSelected ? dim(" No ") : green(bold(" No "));
-  writeRaw(`${CLEAR_LINE}${question}  ${yes} / ${no}\n`);
-  writeRaw(`${CLEAR_LINE}${dim("←→ or y/n to choose  enter to confirm  ctrl-c to cancel")}\n`);
+  return [
+    `${question}  ${yes} / ${no}`,
+    dim("←→ or y/n to choose  enter to confirm  ctrl-c to cancel"),
+  ];
 }
 
 export async function promptConfirm(question: string, defaultYes = true): Promise<boolean> {
@@ -186,10 +209,11 @@ export async function promptConfirm(question: string, defaultYes = true): Promis
   }
 
   let yesSelected = defaultYes;
+  const drawFrame = createFrameWriter();
 
   return withRawMode(async () => {
     while (true) {
-      renderConfirm(question, yesSelected);
+      drawFrame(buildConfirmLines(question, yesSelected));
       const key = parseKey(await readKey());
 
       if (key === "ctrl-c") {

package/src/installer/search-policy.ts

@@ -1,32 +1,86 @@
 /** Shared code-search policy text for instructions, Cursor rules, and sub-agents. */
 
-export const SEARCH_POLICY_TABLE = `| Task | Use | Not |
+export const SNIPPET_GUIDANCE =
+  "Search returns compact snippets (~±15 lines around the best match). " +
+  "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` " +
+  "(or `start_line`) — do not re-search or Read the whole file.";
+
+export interface NativeToolNames {
+  explorationDenied: string;
+  grep: string;
+  read: string;
+}
+
+export function buildSearchPolicyTable(native: NativeToolNames): string {
+  return `| Task | Use | Not |
 |------|-----|-----|
-| How/where/what handles X? | Miru MCP \`search\` (once) | Grep, Glob, SemanticSearch, repeat searches |
-| Same file, more context | Miru MCP \`expand\` | Re-search, Read whole file |
-| Similar code elsewhere | Miru MCP \`find_related\` | Grep chains |
-| Search docs or config | Miru \`search\` with \`content\` | Grep README paths |
-| Exact literal exists? | Grep | Miru |
-| Edit a known file:line | Read (after Miru found it) | Read-before-search |`;
+| How/where/what handles X? | Miru MCP \`search\` (once) | ${native.explorationDenied}, repeat searches |
+| Same file, more context | Miru MCP \`expand\` on \`truncated: true\` | Re-search, ${native.read} whole file |
+| Similar code elsewhere | Miru MCP \`find_related\` | ${native.grep} chains |
+| Search docs or config | Miru \`search\` | ${native.grep} README paths |
+| Exact literal exists? | ${native.grep} | Miru |
+| Edit a known file:line | ${native.read} (after Miru found it) | ${native.read}-before-search |`;
+}
 
-export const SEARCH_POLICY_BODY = `DO NOT use Grep, Glob, SemanticSearch, or Read to explore how code works when Miru MCP is available.
+export function buildSearchPolicyBody(native: NativeToolNames): string {
+  return `DO NOT use ${native.explorationDenied} to explore how code works when Miru MCP is available.
+
+${SNIPPET_GUIDANCE}
 
 Use Miru MCP tools:
 - \`search\` — one call per question; pass project root as \`repo\`
-- \`expand\` — adjacent chunks in the same file when a hit looks truncated (\`file_path\` + \`line\` from the hit)
-- \`find_related\` — similar code in other files after a \`search\` hit
+- \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\` or \`start_line\`)
+- \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
 
 Stop rules:
 - Answer from the first \`search\` — do not re-search with paraphrases
-- If context is cut off in one file, call \`expand\` — not another \`search\` or a full-file Read
-- Read is for editing a path Miru already gave you, not for exploration
+- On \`truncated: true\`, call \`expand\` — not another \`search\` or a full-file ${native.read}
+- ${native.read} is for editing a path Miru already gave you, not for exploration
 
 Native tools are allowed ONLY when:
 - confirming an exact literal string (env var name, error code, quoted text)
 - reading a file you already located via Miru, to edit it
 - searching outside the indexed repo
 
-${SEARCH_POLICY_TABLE}`;
+${buildSearchPolicyTable(native)}`;
+}
+
+export function buildMcpWorkflow(native: NativeToolNames): string {
+  return `### MCP workflow
+
+1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
+2. If a hit has \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\` (or \`start_line\`).
+3. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
+4. ${native.read} via \`absolute_path\` only when editing or when \`expand\` still lacks context.`;
+}
+
+const CLI_FALLBACK = `### CLI fallback (no MCP in this session)
+
+\`\`\`bash
+miru search "authentication flow" .
+miru expand src/auth.ts 42 .
+miru find-related src/auth.ts 42 .
+\`\`\`
+
+If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+
+export function buildSubagentBody(native: NativeToolNames): string {
+  return `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not ${native.explorationDenied} for exploration.
+
+${buildSearchPolicyBody(native)}
+
+${buildMcpWorkflow(native)}
+
+${CLI_FALLBACK}`;
+}
+
+export const DEFAULT_NATIVE_TOOLS: NativeToolNames = {
+  explorationDenied: "Grep, Glob, SemanticSearch, or Read",
+  grep: "Grep",
+  read: "Read",
+};
+
+export const SEARCH_POLICY_BODY = buildSearchPolicyBody(DEFAULT_NATIVE_TOOLS);
 
 export const INSTRUCTIONS_MARKDOWN = `## Miru Code Search
 
@@ -54,25 +108,31 @@ alwaysApply: true
 
 ${SEARCH_POLICY_BODY}
 
-When Miru MCP is connected, call \`search\` once per question. Use \`expand\` for same-file context. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
+When Miru MCP is connected, call \`search\` once per question. On \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
 
-export const SUBAGENT_BODY = `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not Grep, Glob, SemanticSearch, or Read-for-exploration.
+export const SUBAGENT_BODY = buildSubagentBody(DEFAULT_NATIVE_TOOLS);
 
-${SEARCH_POLICY_BODY}
+export const MCP_SERVER_INSTRUCTIONS =
+  "DO NOT use Grep, Glob, SemanticSearch, or Read to explore code when this server is available. " +
+  `${SNIPPET_GUIDANCE} ` +
+  "Workflow: (1) `search` once per question — do NOT re-search with paraphrases. " +
+  "(2) On `truncated: true`, call `expand` with `file_path` and `anchor_line` (or `start_line`) — do NOT read the whole file. " +
+  "(3) `find_related` traces similar code in other files, not more context in the same file. " +
+  "Always pass the project root as `repo`. Local repos return `absolute_path` on each hit — use Read only to edit. " +
+  "Native search is only for exact literal confirmation or files outside the indexed repo.";
 
-### MCP workflow
+export const MCP_SEARCH_TOOL_DESCRIPTION =
+  "DEFAULT code exploration tool. Returns compact snippets (~±15 lines). One call per question is usually enough. " +
+  "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` (or `start_line`) — not re-search or Read.";
 
-1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
-2. If a hit looks truncated, call \`expand\` with the hit's \`file_path\` and \`line\`.
-3. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
-4. Read via \`absolute_path\` only when editing or when \`expand\` still lacks context.
+export const MCP_EXPAND_TOOL_DESCRIPTION =
+  "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` or `start_line` from a truncated hit; " +
+  "returns adjacent indexed chunks. Use when `truncated: true` — NOT for similar code in other files (use find_related). " +
+  "Prefer this over re-searching or reading the whole file.";
 
-### CLI fallback (no MCP in this session)
+export const MCP_FIND_RELATED_TOOL_DESCRIPTION =
+  "Find code similar to a file:line in OTHER parts of the codebase. Results may be snippets; use `expand` when `truncated: true`. " +
+  "For more context in the same file, use `expand` instead.";
 
-\`\`\`bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-\`\`\`
-
-If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+export const SEARCH_GUARD_EXPAND_HINT =
+  "If a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` — do not re-search or read the whole file.";

package/src/mcp/server.ts

@@ -12,6 +12,12 @@ import {
   MAX_MCP_TOP_K,
   resolveChunk,
 } from "../utils.ts";
+import {
+  MCP_EXPAND_TOOL_DESCRIPTION,
+  MCP_FIND_RELATED_TOOL_DESCRIPTION,
+  MCP_SEARCH_TOOL_DESCRIPTION,
+  MCP_SERVER_INSTRUCTIONS,
+} from "../installer/search-policy.ts";
 import { getIndexForRepo, type IndexCache, toolText } from "./index-cache.ts";
 
 const REPO_DESCRIPTION =
@@ -19,14 +25,6 @@ const REPO_DESCRIPTION =
   "Pass the project root for local workspaces. " +
   "The index is built on the first tool call and cached for the session.";
 
-const SERVER_INSTRUCTIONS =
-  "DO NOT use Grep, Glob, SemanticSearch, or Read to explore code when this server is available. " +
-  "Workflow: (1) `search` once per question — do NOT re-search with paraphrases. " +
-  "(2) If context looks cut off, call `expand` on the hit's file_path + line — do NOT read the whole file. " +
-  "(3) `find_related` traces similar code in other files, not more context in the same file. " +
-  "Always pass the project root as `repo`. Local repos return `absolute_path` on each hit — use Read only to edit. " +
-  "Native search is only for exact literal confirmation or files outside the indexed repo.";
-
 export function createMcpServer(cache: IndexCache): McpServer {
   const server = new McpServer(
     {
@@ -34,7 +32,7 @@ export function createMcpServer(cache: IndexCache): McpServer {
       version: "0.1.0",
     },
     {
-      instructions: SERVER_INSTRUCTIONS,
+      instructions: MCP_SERVER_INSTRUCTIONS,
     },
   );
 
@@ -42,9 +40,7 @@ export function createMcpServer(cache: IndexCache): McpServer {
     "search",
     {
       description:
-        "DEFAULT code exploration tool. One call per question is usually enough. " +
-        "If a hit looks truncated, call `expand` (same file) instead of re-searching or Read. " +
-        "Indexes `repo` on first call; later calls reuse the session cache.",
+        `${MCP_SEARCH_TOOL_DESCRIPTION} Indexes \`repo\` on first call; later calls reuse the session cache.`,
       inputSchema: {
         query: z.string().describe("Natural language or code query."),
         repo: z.string().describe(REPO_DESCRIPTION),
@@ -72,7 +68,7 @@ export function createMcpServer(cache: IndexCache): McpServer {
           return toolText(JSON.stringify({ error: "No results found." }));
         }
         const repoRoot = localRepoRoot(repo);
-        return toolText(JSON.stringify(formatResults(query, results, { repoRoot })));
+        return toolText(JSON.stringify(formatResults(query, results, { repoRoot, snippet: true })));
       } catch (err) {
         return toolText(err instanceof Error ? err.message : String(err));
       }
@@ -82,15 +78,15 @@ export function createMcpServer(cache: IndexCache): McpServer {
   server.registerTool(
     "expand",
     {
-      description:
-        "More context in the SAME file as a search hit. Pass file_path + line from a hit; returns adjacent indexed chunks. " +
-        "Use when a chunk looks cut off — NOT for finding similar code in other files (use find_related). " +
-        "Prefer this over re-searching or reading the whole file.",
+      description: MCP_EXPAND_TOOL_DESCRIPTION,
       inputSchema: {
         file_path: z
           .string()
           .describe("Path from a search hit (`file_path` or `absolute_path` for local repos)."),
-        line: z.number().int().describe("Line number (1-indexed) from the hit."),
+        line: z
+          .number()
+          .int()
+          .describe("Line from the hit: `anchor_line` when truncated, otherwise `start_line` (1-indexed)."),
         repo: z.string().describe(REPO_DESCRIPTION),
         before: z
           .number()
@@ -143,16 +139,17 @@ export function createMcpServer(cache: IndexCache): McpServer {
   server.registerTool(
     "find_related",
     {
-      description:
-        "Find code similar to a file:line in OTHER parts of the codebase. " +
-        "For more context in the same file, use `expand` instead.",
+      description: MCP_FIND_RELATED_TOOL_DESCRIPTION,
       inputSchema: {
         file_path: z
           .string()
           .describe(
             "Path from a search hit (`file_path` or `absolute_path` for local repos).",
           ),
-        line: z.number().int().describe("Line number (1-indexed)."),
+        line: z
+          .number()
+          .int()
+          .describe("Line from the hit: `anchor_line` when truncated, otherwise `start_line` (1-indexed)."),
         repo: z.string().describe(REPO_DESCRIPTION),
         top_k: z
           .number()
@@ -181,7 +178,10 @@ export function createMcpServer(cache: IndexCache): McpServer {
         }
         return toolText(
           JSON.stringify(
-            formatResults(`Chunks related to ${filePath}:${line}`, results, { repoRoot }),
+            formatResults(`Chunks related to ${filePath}:${line}`, results, {
+              repoRoot,
+              snippet: true,
+            }),
           ),
         );
       } catch (err) {

package/src/ranking/boosting.ts

@@ -2,6 +2,12 @@ import { basename, dirname } from "node:path";
 import { splitIdentifier } from "../tokens.ts";
 import type { Chunk } from "../types.ts";
 import { chunkKey } from "../types.ts";
+import { searchImprovementsEnabled } from "./features.ts";
+import {
+  boostExactStemMatches,
+  boostLocationSignals,
+  penalizeInstallerForLocation,
+} from "./location.ts";
 
 const SYMBOL_QUERY_RE =
   /^(?:(?:[A-Za-z_][A-Za-z0-9_]*(?:(?:::|\\|->|\.)[A-Za-z_][A-Za-z0-9_]*)+)|_(?:[A-Za-z0-9_]*)|(?:[A-Za-z][A-Za-z0-9]*[A-Z_][A-Za-z0-9_]*)|(?:[A-Z][A-Za-z0-9]*))$/;
@@ -165,6 +171,11 @@ export function applyQueryBoost(
   } else {
     boostStemMatches(combinedScores, query, maxScore, chunksByKey);
     boostEmbeddedSymbols(combinedScores, query, maxScore, allChunks, chunksByKey);
+    if (searchImprovementsEnabled()) {
+      boostExactStemMatches(combinedScores, query, maxScore, chunksByKey);
+      boostLocationSignals(combinedScores, query, maxScore, allChunks, chunksByKey);
+      penalizeInstallerForLocation(combinedScores, query, chunksByKey);
+    }
   }
   return combinedScores;
 }

package/src/ranking/features.ts

@@ -0,0 +1,11 @@
+/** Toggle search ranking/indexing improvements (A/B via MIRU_SEARCH_V2=0|1). */
+export function searchImprovementsEnabled(): boolean {
+  const value = process.env.MIRU_SEARCH_V2;
+  if (value === "0" || value === "false") {
+    return false;
+  }
+  if (value === "1" || value === "true") {
+    return true;
+  }
+  return true;
+}

package/src/ranking/location.ts

@@ -0,0 +1,241 @@
+import { basename } from "node:path";
+import type { Chunk } from "../types.ts";
+import { chunkKey } from "../types.ts";
+
+const LOCATION_QUERY_RE =
+  /\b(where(?:'s| is)?|entry\s*point|bootstrap|starts?|live[s]?|located|defined|wiring)\b/i;
+
+const ENTRY_POINT_QUERY_RE = /\b(entry\s*point|bootstrap|starts?|wiring|command\s*line)\b/i;
+
+const INTEGRATION_QUERY_RE = /\b(install|uninstall|hook|agent|configure|setup)\b/i;
+
+const INSTALLER_PATH_RE = /(?:^|\/)installer(?:\/|$)/;
+
+const ENTRY_POINT_CONTENT_RE =
+  /#!\/usr\/bin|(?:^|\n)\s*(?:async\s+)?function\s+main\s*\(|(?:^|\n)\s*if\s*\(\s*require\.main\s*===\s*module/;
+
+const PACKAGE_ENTRY_RE = /^\[package entry\]/;
+
+const LOCATION_BOOST_MULTIPLIER = 2.5;
+const INSTALLER_LOCATION_PENALTY = 0.35;
+
+/** Too common as filenames to get exact-stem boosts from incidental query tokens. */
+const IMPLEMENTATION_HINTS = new Set(
+  [
+    "command",
+    "handler",
+    "router",
+    "routing",
+    "middleware",
+    "model",
+    "channel",
+    "request",
+    "response",
+    "dispatch",
+    "pipeline",
+  ].map((w) => w.toLowerCase()),
+);
+
+const GENERIC_STEM_DENY = new Set(
+  [
+    "route",
+    "routes",
+    "router",
+    "routing",
+    "handler",
+    "middleware",
+    "channel",
+    "model",
+    "models",
+    "request",
+    "response",
+    "utils",
+    "util",
+    "server",
+    "client",
+    "application",
+    "dispatch",
+    "core",
+    "lib",
+    "main",
+    "mod",
+    "test",
+    "tests",
+    "schema",
+    "config",
+    "helper",
+    "helpers",
+    "engine",
+    "pipeline",
+    "plug",
+    "plugs",
+    "command",
+    "commands",
+    "index",
+  ].map((w) => w.toLowerCase()),
+);
+
+export function isLocationQuery(query: string): boolean {
+  return LOCATION_QUERY_RE.test(query);
+}
+
+export function isEntryPointQuery(query: string): boolean {
+  return ENTRY_POINT_QUERY_RE.test(query);
+}
+
+function fileStemMatchesQuery(filePath: string, query: string): boolean {
+  const stem = basename(filePath)
+    .replace(/\.[^.]+$/, "")
+    .toLowerCase();
+  const rawTokens = (query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? []).map((t) => t.toLowerCase());
+
+  if (rawTokens.includes(stem)) {
+    return true;
+  }
+
+  for (const token of rawTokens) {
+    if (token.includes("-") && token.split("-").includes(stem)) {
+      return false;
+    }
+  }
+
+  const stemNorm = stem.replace(/[-_]/g, "");
+  return rawTokens.some((t) => t.replace(/[-_]/g, "") === stemNorm);
+}
+
+export function isIntegrationQuery(query: string): boolean {
+  return INTEGRATION_QUERY_RE.test(query);
+}
+
+function chunkLooksLikeEntryPoint(chunk: Chunk): boolean {
+  if (PACKAGE_ENTRY_RE.test(chunk.content)) {
+    return true;
+  }
+  return ENTRY_POINT_CONTENT_RE.test(chunk.content);
+}
+
+export function boostLocationSignals(
+  boosted: Map<string, number>,
+  query: string,
+  maxScore: number,
+  allChunks: Chunk[],
+  chunksByKey: Map<string, Chunk>,
+): void {
+  if (!isLocationQuery(query)) {
+    return;
+  }
+
+  const entryPointQuery = isEntryPointQuery(query);
+  const packageBoost = maxScore * (entryPointQuery ? LOCATION_BOOST_MULTIPLIER : 0.75);
+  const codeBoost = maxScore * LOCATION_BOOST_MULTIPLIER;
+
+  for (const chunk of allChunks) {
+    if (!chunkLooksLikeEntryPoint(chunk)) {
+      continue;
+    }
+
+    const isPackageEntry = PACKAGE_ENTRY_RE.test(chunk.content);
+    if (isPackageEntry) {
+      const key = chunkKey(chunk);
+      boosted.set(key, (boosted.get(key) ?? 0) + packageBoost);
+      chunksByKey.set(key, chunk);
+      continue;
+    }
+
+    if (!entryPointQuery && !fileStemMatchesQuery(chunk.file_path, query)) {
+      continue;
+    }
+
+    const key = chunkKey(chunk);
+    boosted.set(key, (boosted.get(key) ?? 0) + codeBoost);
+    chunksByKey.set(key, chunk);
+  }
+}
+
+export function penalizeInstallerForLocation(
+  boosted: Map<string, number>,
+  query: string,
+  chunksByKey: Map<string, Chunk>,
+): void {
+  if (!isLocationQuery(query) || isIntegrationQuery(query)) {
+    return;
+  }
+
+  for (const [key, score] of boosted) {
+    const chunk = chunksByKey.get(key);
+    if (!chunk) {
+      continue;
+    }
+    if (INSTALLER_PATH_RE.test(chunk.file_path.replace(/\\/g, "/"))) {
+      boosted.set(key, score * INSTALLER_LOCATION_PENALTY);
+    }
+  }
+}
+
+function hasSpecificImplementationTarget(
+  query: string,
+  chunksByKey: Map<string, Chunk>,
+): boolean {
+  const lowered = query.toLowerCase();
+  for (const hint of IMPLEMENTATION_HINTS) {
+    if (!lowered.includes(hint)) {
+      continue;
+    }
+    for (const chunk of chunksByKey.values()) {
+      const stem = basename(chunk.file_path)
+        .replace(/\.[^.]+$/, "")
+        .toLowerCase();
+      if (stem === hint) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function boostExactStemMatches(
+  boosted: Map<string, number>,
+  query: string,
+  maxScore: number,
+  chunksByKey: Map<string, Chunk>,
+): void {
+  const keywords = new Set(
+    (query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? [])
+      .filter((w) => w.length > 2)
+      .map((w) => w.toLowerCase()),
+  );
+  if (keywords.size === 0) {
+    return;
+  }
+
+  const boost = maxScore * 0.75;
+  const preferImplementation = hasSpecificImplementationTarget(query, chunksByKey);
+
+  for (const key of [...boosted.keys()]) {
+    const chunk = chunksByKey.get(key);
+    if (!chunk) {
+      continue;
+    }
+    const stem = basename(chunk.file_path)
+      .replace(/\.[^.]+$/, "")
+      .toLowerCase();
+    const stemNorm = stem.replace(/[-_]/g, "");
+    for (const keyword of keywords) {
+      if (GENERIC_STEM_DENY.has(keyword)) {
+        continue;
+      }
+      if (preferImplementation && stem === keyword && !IMPLEMENTATION_HINTS.has(stem)) {
+        continue;
+      }
+      const keywordNorm = keyword.replace(/[-_]/g, "");
+      if (stem === keyword || stemNorm === keywordNorm) {
+        boosted.set(key, (boosted.get(key) ?? 0) + boost);
+        break;
+      }
+      const parts = keyword.split("-").filter((p) => p.length > 2);
+      if (parts.length > 1 && parts.some((p) => p === stem)) {
+        continue;
+      }
+    }
+  }
+}

package/src/search.ts

@@ -4,6 +4,8 @@ import type { SemanticIndex } from "./index/semantic-index.ts";
 import { selectorToMask } from "./index/sparse.ts";
 import { selectTopKScoreIndices } from "./index/topk.ts";
 import { applyQueryBoost, boostMultiChunkFiles } from "./ranking/boosting.ts";
+import { searchImprovementsEnabled } from "./ranking/features.ts";
+import { isLocationQuery } from "./ranking/location.ts";
 import { rerankTopk } from "./ranking/penalties.ts";
 import { resolveAlpha } from "./ranking/weighting.ts";
 import { tokenize } from "./tokens.ts";
@@ -93,7 +95,8 @@ export async function hybridSearch(options: {
   } = options;
 
   const alphaWeight = resolveAlpha(query, alpha);
-  const candidateCount = topK * 5;
+  const candidateCount =
+    searchImprovementsEnabled() && isLocationQuery(query) ? topK * 10 : topK * 5;
   const chunksByKey = new Map(chunks.map((c) => [chunkKey(c), c]));
 
   const queryVecPromise = embeddings.embedQuery(query);

package/src/snippet.ts

@@ -0,0 +1,154 @@
+import { envOptionalInt } from "./env.ts";
+import { tokenize } from "./tokens.ts";
+import type { Chunk, SearchResult } from "./types.ts";
+
+const SNIPPET_STOPWORDS = new Set(
+  "a an and are as at be by do does for from has have how if in is it not of on or the to was what when where which who why with".split(
+    " ",
+  ),
+);
+
+export interface SnippetMeta {
+  truncated: boolean;
+  anchor_line: number;
+  full_start_line: number;
+  full_end_line: number;
+}
+
+export interface SnippetResult {
+  chunk: Chunk;
+  meta: SnippetMeta;
+}
+
+export function resolveSnippetLines(): number {
+  return envOptionalInt(["MIRU_SNIPPET_LINES"], 3) ?? 15;
+}
+
+export function searchSnippetsEnabled(): boolean {
+  const value = process.env.MIRU_SEARCH_SNIPPETS;
+  if (value === "0" || value === "false") {
+    return false;
+  }
+  if (value === "1" || value === "true") {
+    return true;
+  }
+  return true;
+}
+
+function queryMatchTerms(query: string): Set<string> {
+  const terms = new Set<string>();
+  for (const tok of tokenize(query)) {
+    if (tok.length >= 3 && !SNIPPET_STOPWORDS.has(tok)) {
+      terms.add(tok);
+    }
+  }
+  for (const word of query.match(/[a-zA-Z_][a-zA-Z0-9_-]*/g) ?? []) {
+    const lower = word.toLowerCase();
+    if (lower.length >= 3 && !SNIPPET_STOPWORDS.has(lower)) {
+      terms.add(lower);
+    }
+  }
+  return terms;
+}
+
+function scoreLine(line: string, terms: Set<string>): number {
+  const lower = line.toLowerCase();
+  let score = 0;
+  for (const term of terms) {
+    if (lower.includes(term)) {
+      score++;
+    }
+  }
+  return score;
+}
+
+/** Pick the 0-based line index inside `content` that best matches the query. */
+export function anchorLineOffset(content: string, query: string): number {
+  const lines = content.split("\n");
+  if (lines.length === 0) {
+    return 0;
+  }
+
+  const terms = queryMatchTerms(query);
+  let bestIndex = Math.floor(lines.length / 2);
+  let bestScore = -1;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const score = scoreLine(line, terms);
+    if (score > bestScore) {
+      bestScore = score;
+      bestIndex = i;
+    }
+  }
+
+  return bestIndex;
+}
+
+export function trimChunkToSnippet(
+  chunk: Chunk,
+  query: string,
+  linesEachSide = resolveSnippetLines(),
+): SnippetResult {
+  const lines = chunk.content.split("\n");
+  if (lines.length === 0) {
+    return {
+      chunk,
+      meta: {
+        truncated: false,
+        anchor_line: chunk.start_line,
+        full_start_line: chunk.start_line,
+        full_end_line: chunk.end_line,
+      },
+    };
+  }
+
+  const anchorOffset = anchorLineOffset(chunk.content, query);
+  const startOffset = Math.max(0, anchorOffset - linesEachSide);
+  const endOffset = Math.min(lines.length, anchorOffset + linesEachSide + 1);
+  const truncated = startOffset > 0 || endOffset < lines.length;
+
+  if (!truncated) {
+    return {
+      chunk,
+      meta: {
+        truncated: false,
+        anchor_line: chunk.start_line + anchorOffset,
+        full_start_line: chunk.start_line,
+        full_end_line: chunk.end_line,
+      },
+    };
+  }
+
+  const snippetContent = lines.slice(startOffset, endOffset).join("\n");
+  return {
+    chunk: {
+      ...chunk,
+      content: snippetContent,
+      start_line: chunk.start_line + startOffset,
+      end_line: chunk.start_line + endOffset - 1,
+    },
+    meta: {
+      truncated: true,
+      anchor_line: chunk.start_line + anchorOffset,
+      full_start_line: chunk.start_line,
+      full_end_line: chunk.end_line,
+    },
+  };
+}
+
+export function applySnippetsToResults(
+  results: SearchResult[],
+  query: string,
+  linesEachSide?: number,
+): Array<{ result: SearchResult; meta: SnippetMeta }> {
+  const radius = linesEachSide ?? resolveSnippetLines();
+  return results.map((result) => {
+    const { chunk, meta } = trimChunkToSnippet(result.chunk, query, radius);
+    return { result: { chunk, score: result.score }, meta };
+  });
+}
+
+export function estimateResultTokens(results: SearchResult[]): number {
+  return results.reduce((sum, r) => sum + Math.floor(r.chunk.content.length / 4), 0);
+}

package/src/utils.ts

@@ -1,4 +1,5 @@
 import { join, relative, resolve, sep } from "node:path";
+import { applySnippetsToResults, searchSnippetsEnabled } from "./snippet.ts";
 import type { Chunk, ContentType, SearchResult } from "./types.ts";
 import { chunkToDict } from "./types.ts";
 
@@ -157,15 +158,35 @@ export function expandChunksAtLine(
 export function formatResults(
   query: string,
   results: SearchResult[],
-  options?: { repoRoot?: string | null },
+  options?: { repoRoot?: string | null; snippet?: boolean },
 ): { query: string; results: Record<string, unknown>[] } {
   const repoRoot = options?.repoRoot ?? null;
+  const useSnippet = options?.snippet ?? searchSnippetsEnabled();
+  const payload = useSnippet ? applySnippetsToResults(results, query) : null;
+
   return {
     query,
-    results: results.map((result) => ({
-      chunk: chunkToResponseDict(result.chunk, repoRoot),
-      score: result.score,
-    })),
+    results: results.map((result, index) => {
+      const entry = payload?.[index];
+      const chunk = entry?.result.chunk ?? result.chunk;
+      const dict = chunkToResponseDict(chunk, repoRoot);
+      if (entry?.meta.truncated) {
+        return {
+          chunk: {
+            ...dict,
+            truncated: true,
+            anchor_line: entry.meta.anchor_line,
+            full_start_line: entry.meta.full_start_line,
+            full_end_line: entry.meta.full_end_line,
+          },
+          score: result.score,
+        };
+      }
+      return {
+        chunk: dict,
+        score: result.score,
+      };
+    }),
   };
 }