@takara-ai/miru-code 1.8.1 → 1.9.0

package/README.md

@@ -38,6 +38,23 @@ Restart Claude Code (or reload plugins) when prompted. Update: `/plugin marketpl
 
 **Any other IDE, or if marketplace install isn't available:** use the CLI install below.
 
+### What you get from a plugin install vs the CLI
+
+Plugin installs don't carry full CLI parity — what each one gives you depends on the IDE's own plugin capabilities, not just Miru's packaging:
+
+| | Claude Code | Codex | Cursor |
+|---|---|---|---|
+| MCP tools (`search`, `locate`, `expand`, `find_related`) | ✅ | ✅ | ❌ *(plugin ships skills + rules only — no MCP entry yet)* |
+| `miru` / Caveman / STE skills | ✅ | ✅ | ✅ |
+| Dedicated sub-agent (`miru:miru-code`) | ✅ | — | — |
+| Benchmark mode toggle (`/plugin configure`) | ✅ | — | — |
+| Search hooks | — | — | — |
+| Credentials | own plugin-scoped dir | own plugin-scoped dir | n/a |
+
+`—` means the IDE's plugin schema has no equivalent mechanism to port these to (not a packaging gap we can close): Codex's and Cursor's plugin manifests have no `agents` or `userConfig` fields, so the dedicated sub-agent and the benchmark toggle are Claude-Code-only. Search hooks aren't shipped to any plugin — they're slated for removal from Miru entirely (tracked internally), so not worth packaging.
+
+**Credentials are plugin-scoped, not shared with your CLI install.** Claude Code and Codex plugins each store auth in their own IDE-managed data directory (survives plugin updates, removed on uninstall). This means `miru setup` done via the CLI does **not** carry over to a plugin install, or vice versa — each authenticates independently on first use (interactive device-code login bootstraps automatically). If you use both the CLI and a plugin, you'll sign in twice.
+
 ## Install (CLI)
 
 ```bash
@@ -105,10 +122,8 @@ miru uninstall   # remove miru config
 
 ### Plugin packaging
 
-This repo now includes plugin packaging for:
-
-- Codex: `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json`
-- Claude Code: `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
+- Codex: `.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json`, shares the root `mcp.json`
+- Claude Code: `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, its own `.claude-plugin/mcp.json` (needed for the `userConfig` benchmark toggle — see [What you get from a plugin install vs the CLI](#what-you-get-from-a-plugin-install-vs-the-cli))
 - Cursor: `plugin.json` and `.cursor/rules/miru-code-search.mdc`
 
 Current limitation:
@@ -285,7 +300,7 @@ bun add @takara-ai/miru-code
 import { MiruIndex } from "@takara-ai/miru-code";
 
 const index = await MiruIndex.fromPath("./src");
-const results = await index.search({ query: "BM25 tokenize", topK: 10 });
+const results = await index.search({ query: "BM25 tokenize" });
 ```
 
 ## Environment
@@ -353,7 +368,8 @@ Override with `MIRU_BENCHMARK_HISTORY_PATH`. Append-only JSONL of compact token
 | ---------------- | -------- | --------------------------------------- |
 | `query`          | yes      | Natural language or code query          |
 | `repo`           | yes      | Project root or git URL                 |
-| `top_k`          | no       | Results to return (default 3, max 10)   |
+| `include`        | no       | Gitignore-style glob patterns; only matching files are searched (same as `locate.include`) |
+| `exclude`        | no       | Gitignore-style glob patterns; matching files are skipped (same as `locate.exclude`) |
 | `dedupe_by_file` | no       | Keep best hit per file (default `true`) |
 
 
@@ -364,6 +380,8 @@ Override with `MIRU_BENCHMARK_HISTORY_PATH`. Append-only JSONL of compact token
 | ------------- | -------- | ----------------------------------------------------------------------------------- |
 | `literal`     | yes      | Exact substring to find                                                             |
 | `repo`        | yes      | Project root or git URL                                                             |
+| `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 |
 | `limit`       | no       | Cap returned hits. Omit to return all matches                                       |
 | `ignore_case` | no       | Case-insensitive match (default `false`)                                            |
@@ -388,7 +406,6 @@ Override with `MIRU_BENCHMARK_HISTORY_PATH`. Append-only JSONL of compact token
 | `file_path`   | yes      | From a search hit                            |
 | `anchor_line` | yes      | From the search hit                          |
 | `repo`        | yes      | Same repo as the search                      |
-| `top_k`       | no       | Related chunks to return (default 3, max 10) |
 
 
 `**read_benchmark**` *(benchmark mode only)*

package/package.json

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

package/src/cli.ts

@@ -56,6 +56,7 @@ import {
   resolveChunk,
   resolveContent,
   resolveSearchPath,
+  SEARCH_RESULT_COUNT,
 } from "./utils.ts";
 import { maybeNotifyUpdate, miruVersion } from "./version.ts";
 
@@ -132,25 +133,6 @@ function parseContentArgv(argv: string[]): { content: ContentType[]; rest: strin
   return { content: resolveContent(content), rest };
 }
 
-function parseTopK(argv: string[]): { topK: number; rest: string[] } {
-  const rest: string[] = [];
-  let topK = 5;
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    if (arg === "-k" || arg === "--top-k") {
-      const raw = argv[++i];
-      if (raw) {
-        topK = Number(raw);
-      }
-      continue;
-    }
-    if (arg !== undefined) {
-      rest.push(arg);
-    }
-  }
-  return { topK: Number.isFinite(topK) && topK >= 1 ? Math.floor(topK) : 5, rest };
-}
-
 function emitSearchOutput(
   query: string,
   results: SearchResult[],
@@ -177,7 +159,6 @@ function emitSearchOutput(
 async function runSearch(
   path: string,
   query: string,
-  topK: number,
   content: ContentType[],
   jsonFlag: boolean,
 ): Promise<void> {
@@ -186,7 +167,7 @@ async function runSearch(
   const index = await withSpinner("Indexing and searching", async () => {
     const built = await MiruIndex.fromSource(path, content);
     await built.saveToCache(path);
-    const results = await built.search({ query, topK });
+    const results = await built.search({ query, topK: SEARCH_RESULT_COUNT });
     return { index: built, results };
   });
 
@@ -245,7 +226,6 @@ async function runFindRelated(
   path: string,
   filePath: string,
   line: number,
-  topK: number,
   content: ContentType[],
   jsonFlag: boolean,
 ): Promise<void> {
@@ -257,7 +237,7 @@ async function runFindRelated(
     if (!chunk) {
       throw new RelatedChunkNotFoundError(filePath, line);
     }
-    const hits = await built.findRelated(chunk, topK);
+    const hits = await built.findRelated(chunk, SEARCH_RESULT_COUNT);
     await built.saveToCache(path);
     return {
       results: hits,
@@ -552,21 +532,28 @@ async function runCli(argv: string[]): Promise<void> {
 
   const { present: jsonFlag, rest: jsonRest } = parseFlagArgv(rest, "--json");
   const { content, rest: contentRest } = parseContentArgv(jsonRest);
-  const { topK, rest: sizedRest } = parseTopK(contentRest);
+
+  if (
+    (command === "search" || command === "find-related") &&
+    contentRest.some((arg) => arg === "-k" || arg === "--top-k")
+  ) {
+    fail("The -k/--top-k option has been removed; Miru returns a fixed number of results.");
+    process.exit(1);
+  }
 
   if (command === "search") {
-    const query = sizedRest[0];
+    const query = contentRest[0];
     if (!query) {
       printCommandHelp("search");
       process.exit(1);
     }
-    const path = resolveSearchPath(sizedRest[1] ?? process.cwd());
-    await runSearch(path, query, topK, content, jsonFlag);
+    const path = resolveSearchPath(contentRest[1] ?? process.cwd());
+    await runSearch(path, query, content, jsonFlag);
     return;
   }
 
   if (command === "locate") {
-    const literal = sizedRest[0];
+    const literal = contentRest[0];
     if (!literal) {
       printCommandHelp("locate");
       process.exit(1);
@@ -585,10 +572,10 @@ async function runCli(argv: string[]): Promise<void> {
       }
       return Math.floor(n);
     };
-    for (let i = 1; i < sizedRest.length; i++) {
-      const arg = sizedRest[i];
-      if (arg === "--mode" && sizedRest[i + 1]) {
-        const value = sizedRest[++i];
+    for (let i = 1; i < contentRest.length; i++) {
+      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.`);
           process.exit(1);
@@ -596,8 +583,8 @@ async function runCli(argv: string[]): Promise<void> {
         options.mode = value as LiteralMode;
         continue;
       }
-      if (arg === "--limit" && sizedRest[i + 1]) {
-        options.limit = positiveInt("--limit", sizedRest[++i], 1);
+      if (arg === "--limit" && contentRest[i + 1]) {
+        options.limit = positiveInt("--limit", contentRest[++i], 1);
         continue;
       }
       if (arg === "--ignore-case") {
@@ -608,16 +595,16 @@ async function runCli(argv: string[]): Promise<void> {
         options.match_variants = true;
         continue;
       }
-      if (arg === "--include" && sizedRest[i + 1]) {
-        include.push(sizedRest[++i] as string);
+      if (arg === "--include" && contentRest[i + 1]) {
+        include.push(contentRest[++i] as string);
         continue;
       }
-      if (arg === "--exclude" && sizedRest[i + 1]) {
-        exclude.push(sizedRest[++i] as string);
+      if (arg === "--exclude" && contentRest[i + 1]) {
+        exclude.push(contentRest[++i] as string);
         continue;
       }
-      if (arg === "--context" && sizedRest[i + 1]) {
-        options.context_lines = positiveInt("--context", sizedRest[++i], 0);
+      if (arg === "--context" && contentRest[i + 1]) {
+        options.context_lines = positiveInt("--context", contentRest[++i], 0);
         continue;
       }
       if (arg !== undefined) {
@@ -636,22 +623,22 @@ async function runCli(argv: string[]): Promise<void> {
   }
 
   if (command === "expand") {
-    const filePath = sizedRest[0];
-    const lineRaw = sizedRest[1];
+    const filePath = contentRest[0];
+    const lineRaw = contentRest[1];
     if (!filePath || !lineRaw) {
       printCommandHelp("expand");
       process.exit(1);
     }
     const line = Number(lineRaw);
-    const path = resolveSearchPath(sizedRest[2] ?? process.cwd());
+    const path = resolveSearchPath(contentRest[2] ?? process.cwd());
     let before = DEFAULT_EXPAND_BEFORE;
     let after = DEFAULT_EXPAND_AFTER;
-    for (let i = 3; i < sizedRest.length; i++) {
-      const arg = sizedRest[i];
-      if (arg === "--before" && sizedRest[i + 1]) {
-        before = Number(sizedRest[++i]);
-      } else if (arg === "--after" && sizedRest[i + 1]) {
-        after = Number(sizedRest[++i]);
+    for (let i = 3; i < contentRest.length; i++) {
+      const arg = contentRest[i];
+      if (arg === "--before" && contentRest[i + 1]) {
+        before = Number(contentRest[++i]);
+      } else if (arg === "--after" && contentRest[i + 1]) {
+        after = Number(contentRest[++i]);
       }
     }
     await runExpand(path, filePath, line, before, after, content, jsonFlag);
@@ -659,15 +646,15 @@ async function runCli(argv: string[]): Promise<void> {
   }
 
   if (command === "find-related") {
-    const filePath = sizedRest[0];
-    const lineRaw = sizedRest[1];
+    const filePath = contentRest[0];
+    const lineRaw = contentRest[1];
     if (!filePath || !lineRaw) {
       printCommandHelp("find-related");
       process.exit(1);
     }
     const line = Number(lineRaw);
-    const path = resolveSearchPath(sizedRest[2] ?? process.cwd());
-    await runFindRelated(path, filePath, line, topK, content, jsonFlag);
+    const path = resolveSearchPath(contentRest[2] ?? process.cwd());
+    await runFindRelated(path, filePath, line, content, jsonFlag);
     return;
   }
 
@@ -687,6 +674,10 @@ async function runMcp(argv: string[]): Promise<void> {
       benchmark = true;
       continue;
     }
+    if (arg === "--benchmark=true" || arg === "--benchmark=false") {
+      benchmark = arg === "--benchmark=true";
+      continue;
+    }
     if (arg === "--ref" && argv[i + 1]) {
       ref = argv[++i] ?? null;
       continue;

package/src/credentials.ts

@@ -20,9 +20,14 @@ export function setStoredCredentialsEnvToken(token: string): void {
   process.env.TAKARA_API_KEY = token;
 }
 
+/** True for an unresolved `${...}` placeholder — a plugin host that didn't substitute it. */
+function isUnsubstitutedPlaceholder(value: string): boolean {
+  return value.startsWith("${") && value.endsWith("}");
+}
+
 export function resolveCredentialsDir(): string {
   const override = process.env.MIRU_CREDENTIALS_DIR;
-  if (override) {
+  if (override && !isUnsubstitutedPlaceholder(override)) {
     return override;
   }
   const home = process.env.HOME ?? process.env.USERPROFILE ?? "";

package/src/help.ts

@@ -108,11 +108,10 @@ export function printCommandHelp(command: string): void {
       section("Usage");
       writeStdout("  miru search <query> [path] [options]");
       section("Options");
-      writeStdout("  -k, --top-k N       Number of results (default: 5)");
       writeStdout("  --content TYPE      code | docs | config | all (default: code config)");
       writeStdout("  --json              JSON output (default when piped)");
       section("Example");
-      writeStdout('  miru search "where is auth" ./src -k 10 --content code docs');
+      writeStdout('  miru search "where is auth" ./src --content code docs');
       writeStdout("");
       return;
     case "locate":
@@ -149,7 +148,7 @@ export function printCommandHelp(command: string): void {
       section("Usage");
       writeStdout("  miru find-related <file> <line> [path] [options]");
       section("Example");
-      writeStdout("  miru find-related src/auth.ts 42 . -k 8");
+      writeStdout("  miru find-related src/auth.ts 42 .");
       writeStdout("");
       return;
     case "setup":

package/src/index/chunk-selector.ts

@@ -4,14 +4,16 @@ export type ChunkIndexMappings = {
 };
 
 /**
- * Union of chunk indices matching language and/or path filters.
+ * Union of chunk indices matching language and/or path filters. Path filters
+ * match an exact indexed file path or every file below a directory prefix.
  *
  * Filters combine with OR semantics: a chunk is included if it matches any
  * requested language or path. Returns `undefined` when no filters are given
- * (search all chunks) or when no chunks match.
+ * (search all chunks), and an empty array when filters match no chunks.
  *
- * Single-filter queries return the prebuilt map array directly (read-only for
- * callers). Multi-filter queries allocate a deduped index list.
+ * Exact-file and single-language queries return the prebuilt map array
+ * directly (read-only for callers). Directory and multi-filter queries
+ * allocate an index list.
  */
 export function buildChunkSelector(
   mappings: ChunkIndexMappings,
@@ -28,19 +30,28 @@ export function buildChunkSelector(
   if (langCount === 1 && pathCount === 0) {
     const lang = filterLanguages?.[0];
     if (!lang) {
-      return undefined;
+      return [];
     }
     const indices = mappings.languageMapping.get(lang);
-    return indices && indices.length > 0 ? indices : undefined;
+    return indices && indices.length > 0 ? indices : [];
   }
 
   if (pathCount === 1 && langCount === 0) {
     const fp = filterPaths?.[0];
     if (!fp) {
-      return undefined;
+      return [];
     }
-    const indices = mappings.fileMapping.get(fp);
-    return indices && indices.length > 0 ? indices : undefined;
+    const normalized = normalizePathFilter(fp);
+    const exact = [...mappings.fileMapping.entries()].find(
+      ([filePath]) => filePath.replace(/\\/g, "/") === normalized,
+    )?.[1];
+    if (exact) {
+      return exact;
+    }
+    const prefix = `${normalized}/`;
+    return [...mappings.fileMapping.entries()]
+      .filter(([filePath]) => filePath.replace(/\\/g, "/").startsWith(prefix))
+      .flatMap(([, indices]) => indices);
   }
 
   const selector: number[] = [];
@@ -48,10 +59,27 @@ export function buildChunkSelector(
     selector.push(...(mappings.languageMapping.get(lang) ?? []));
   }
   for (const fp of filterPaths ?? []) {
-    selector.push(...(mappings.fileMapping.get(fp) ?? []));
+    const normalized = normalizePathFilter(fp);
+    const exact = [...mappings.fileMapping.entries()].find(
+      ([filePath]) => filePath.replace(/\\/g, "/") === normalized,
+    )?.[1];
+    if (exact) {
+      selector.push(...exact);
+      continue;
+    }
+    const prefix = `${normalized}/`;
+    for (const [filePath, indices] of mappings.fileMapping) {
+      if (filePath.replace(/\\/g, "/").startsWith(prefix)) {
+        selector.push(...indices);
+      }
+    }
   }
   if (selector.length === 0) {
-    return undefined;
+    return [];
   }
   return [...new Set(selector)];
 }
+
+function normalizePathFilter(filePath: string): string {
+  return filePath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/$/, "");
+}

package/src/installer/search-policy.ts

@@ -1,8 +1,8 @@
 /** Shared code-search policy text for instructions, Cursor rules, and sub-agents. */
 
 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` — do not re-search or Read the whole file.";
+  "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.";
 
 export interface NativeToolNames {
   explorationDenied: string;
@@ -13,30 +13,36 @@ export interface NativeToolNames {
 export function buildSearchPolicyTable(native: NativeToolNames): string {
   return `| Task | Use | Not |
 |------|-----|-----|
-| Quick lookup — where is X handled/defined? | Miru MCP \`search\` (once) | ${native.grep}, ${native.explorationDenied} |
-| How/where/what handles X? | Miru MCP \`search\` (once) | ${native.explorationDenied}, repeat searches |
+| Exact literal (identifier, quoted string, env var, error code) | Miru MCP \`locate\` | Miru \`search\`, ${native.grep} |
+| 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 |
 | Similar code elsewhere | Miru MCP \`find_related\` | ${native.grep} chains |
 | Search docs or config | Miru \`search\` | ${native.grep} README paths |
-| Exact literal string in a file? | Miru MCP \`locate\` | ${native.grep}, Miru \`search\` |
 | Edit a known file:line | ${native.read} (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.
 
+**Check first:** exact token (identifier, quoted string, env var, error code) → \`locate\`. Otherwise → \`search\`.
+
 ${SNIPPET_GUIDANCE}
 
 Use Miru MCP tools:
-- \`search\` — one call per question; pass project root as \`repo\`
 - \`locate\` — exact substring (env var, symbol, error code); prefer \`mode=count\` or \`locations\`
+- \`search\` — one call per conceptual question; pass project root as \`repo\`; 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)
 
+Call shapes:
+- \`locate(literal="<exact substring>", repo="<project root>")\` — prefer \`mode="locations"\`/\`"count"\`
+- \`search(query="<natural language>", repo="<project root>", include=["src/auth/**"])\` — use the same \`include\` / \`exclude\` globs on \`locate\` when scoping an exact-string search
+
 Stop rules:
-- Answer from the first \`search\` — do not re-search with paraphrases
-- 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
+- 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
 
 Native tools are allowed ONLY when:
 - reading a file you already located via Miru, to edit it
@@ -50,7 +56,7 @@ export function buildMcpWorkflow(native: NativeToolNames): string {
 
 1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
 2. For exact literals, call \`locate\` (prefer \`mode=count\` or \`locations\`).
-3. If a hit has \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`.
+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.`;
 }
@@ -64,6 +70,7 @@ miru expand src/auth.ts 42 .
 miru find-related src/auth.ts 42 .
 \`\`\`
 
+After large refactors or CLI-only use, run \`miru clear <path>\` to rebuild the disk cache.
 If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
 
 export function buildSubagentBody(native: NativeToolNames): string {
@@ -90,16 +97,7 @@ ${SEARCH_POLICY_BODY}
 
 Run \`miru setup\` once — the MCP server loads credentials from \`credentials.json\`, and interactive first use can auto-start device login when nothing is stored.
 
-CLI fallback when MCP is unavailable:
-
-\`\`\`bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-\`\`\`
-
-After large refactors or CLI-only use, run \`miru clear <path>\` to rebuild the disk cache.
-If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+${CLI_FALLBACK}`;
 
 export const CURSOR_RULES_MDC = `---
 description: Miru MCP is the default for all code exploration
@@ -110,20 +108,19 @@ alwaysApply: true
 
 ${SEARCH_POLICY_BODY}
 
-When Miru MCP is connected, call \`search\` once per question. On \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`. Use \`locate\` for exact literals — not Grep. Never use Cursor SemanticSearch for codebase questions.`;
+When Miru MCP is connected: literal in the request → \`locate\`, not Grep or \`search\`. Otherwise \`search\` once. \`expand\` only if the snippet doesn't already answer. Never use Cursor SemanticSearch for codebase questions.`;
 
 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. " +
+  "Exact token (identifier, quoted string, env var, error code) → `locate`; everything else → `search` once, no paraphrase retries. " +
   `${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` — do NOT read the whole file. " +
-  "(3) `find_related` traces similar code in other files, not more context in the same file. " +
-  "(4) `locate` finds exact substrings (env vars, symbols, error codes) — prefer over Grep; use mode=count or locations when possible. " +
-  "Always pass the project root as `repo`. Local repos return `absolute_path` on each hit — use Read only to edit. " +
+  "`find_related` traces similar code elsewhere, not more context in the same file. " +
+  "Always pass the project root as `repo`; local repos return `absolute_path` — use Read only to edit. " +
   "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.";
 
 export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
@@ -137,33 +134,32 @@ export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
 
 export const MCP_SEARCH_TOOL_DESCRIPTION =
   "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 compact snippets (~±15 lines). One call per question is usually enough. " +
-  "For exact literals (env vars, symbols, error codes), use `locate` instead. " +
-  "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` — not re-search or Read.";
+  "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.";
 
 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`). " +
+  "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` to match several spellings in one call; " +
-  'or set `match_variants: true` to also match other ways the same word is written in code (e.g. "rateLimit" also finds "rate_limit"). ' +
-  "Use `include`/`exclude` (gitignore-style globs) to scope to part of a monorepo. " +
-  "Use `context_lines` in `lines` mode to get surrounding lines inline instead of a follow-up `expand`/Read. " +
+  "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.";
 
 export const MCP_EXPAND_TOOL_DESCRIPTION =
-  "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` from the 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.";
+  "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).";
 
 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`. " +
+  "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`. " +
   "For more context in the same file, use `expand` instead.";
 
 export const MCP_READ_BENCHMARK_TOOL_DESCRIPTION =
   "Cumulative Miru vs Grep token savings from saved `search` and `locate` calls. Returns compact totals {n,saved,save_pct,miru,grep}. " +
   "Do not call unless the user asks about savings.";
 
-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.";
+export const SEARCH_GUARD_EXPAND_HINT = SNIPPET_GUIDANCE;

package/src/mcp/index-cache.ts

@@ -1,5 +1,6 @@
 import { watch } from "node:fs";
 import { relative, resolve } from "node:path";
+import { isCredentialsError } from "../auth/errors.ts";
 import { walkFiles } from "../index/file-walker.ts";
 import { getExtensions } from "../index/files.ts";
 import { normalizeRelativePath, relativePathFromRoot } from "../index/incremental.ts";
@@ -13,7 +14,6 @@ import {
 } from "../utils.ts";
 
 const CACHE_MAX_SIZE = 10;
-const BUN_WATCH_RECONCILE_INTERVAL_MS = 500;
 
 /** Directory names we skip for MCP fs.watch update triggers (aligned with file-walker). */
 const WATCH_IGNORED_DIR_NAMES = new Set([
@@ -45,6 +45,8 @@ type CacheEntry = {
   pendingPaths: Set<string>;
   flushQueued: boolean;
   updateChain: Promise<void>;
+  /** Dead-credentials failure from a background re-embed; `get()` throws it until a retry clears it. */
+  lastError: Error | null;
 };
 
 export function mcpWatchEnabled(): boolean {
@@ -98,6 +100,7 @@ export class IndexCache {
         pendingPaths: new Set(),
         flushQueued: false,
         updateChain: Promise.resolve(),
+        lastError: null,
       };
       this.entries.set(cacheKey, entry);
     }
@@ -171,6 +174,9 @@ export class IndexCache {
       throw new Error(`Failed to load index for ${source}`);
     }
     await entry.updateChain;
+    if (entry.lastError) {
+      throw entry.lastError;
+    }
     return index;
   }
 
@@ -183,39 +189,11 @@ export class IndexCache {
     }
   }
 
-  private queueIndexedPaths(source: string, index: MiruIndex): void {
-    const cacheKey = computeSourceCacheKey(source);
-    const entry = this.ensureEntry(cacheKey, source);
-    for (const chunk of index.chunks) {
-      entry.pendingPaths.add(normalizeRelativePath(chunk.file_path));
-    }
-    this.scheduleFlush(cacheKey, source, entry);
-  }
-
-  /** macOS recursive fs.watch often omits filename; refresh all indexed paths incrementally. */
-  private noteAmbiguousDirectoryChange(source: string): void {
-    const cacheKey = computeSourceCacheKey(source);
-    const entry = this.entries.get(cacheKey);
-    if (!entry) {
-      return;
-    }
-
-    if (entry.index) {
-      this.queueIndexedPaths(source, entry.index);
-      return;
-    }
-
-    if (entry.task) {
-      void entry.task.then((index) => {
-        entry.index = index;
-        this.queueIndexedPaths(source, index);
-      });
-    }
-  }
-
   private noteFileChange(source: string, filename: string | null | undefined): void {
     if (!filename) {
-      this.noteAmbiguousDirectoryChange(source);
+      // macOS recursive fs.watch could omit the filename on old Bun releases (pre-1.3.14
+      // fs.watch rewrite); confirmed fixed on current Bun. No reconcile fallback for
+      // this case anymore -- an event with no filename is simply dropped.
       return;
     }
     if (shouldIgnoreWatchPath(filename)) {
@@ -253,34 +231,38 @@ export class IndexCache {
         return;
       }
 
+      const requeue = (err?: unknown): void => {
+        if (err !== undefined && isCredentialsError(err)) {
+          entry.lastError = err instanceof Error ? err : new Error(String(err));
+        }
+        for (const p of paths) {
+          entry.pendingPaths.add(p);
+        }
+      };
+
       // Prefer an index already in hand (or published on the entry). Never await
       // entry.task while that task is itself waiting on this flush — that deadlocks.
       let index = knownIndex ?? entry.index;
       if (!index && entry.task) {
         try {
           index = await entry.task;
-        } catch {
-          for (const p of paths) {
-            entry.pendingPaths.add(p);
-          }
+        } catch (err) {
+          requeue(err);
           return;
         }
       }
       if (!index) {
-        for (const p of paths) {
-          entry.pendingPaths.add(p);
-        }
+        requeue();
         return;
       }
 
       try {
         await index.applyFileChanges(paths);
-      } catch {
-        for (const p of paths) {
-          entry.pendingPaths.add(p);
-        }
+      } catch (err) {
+        requeue(err);
         return;
       }
+      entry.lastError = null;
       if (!isGitUrl(source)) {
         try {
           await index.saveToCache(resolve(source), { force: true });
@@ -364,40 +346,13 @@ export class IndexCache {
         this.noteFileChange(path, filename);
       });
     } catch {
-      // Recursive fs.watch is unavailable on some platforms. The reconciliation
-      // fallback below keeps local indexes current there.
+      // Recursive fs.watch is unavailable on some platforms (no fallback here
+      // anymore -- such a local index will only refresh on next cold load).
     }
 
-    // Bun 1.3 on macOS can create a recursive watcher without delivering file
-    // events. Reconcile periodically in Bun so a silent watcher cannot leave an
-    // MCP index stale. Native watchers remain the fast path everywhere else.
-    let reconcileInFlight = false;
-    const reconcile = (): void => {
-      if (reconcileInFlight) {
-        return;
-      }
-      const cacheKey = computeSourceCacheKey(path);
-      const entry = this.entries.get(cacheKey);
-      if (!entry?.index) {
-        return;
-      }
-      reconcileInFlight = true;
-      void this.checkAndQueueStaleFiles(path, entry.index, cacheKey).finally(() => {
-        reconcileInFlight = false;
-      });
-    };
-    const interval =
-      process.versions.bun || !nativeWatcher
-        ? setInterval(reconcile, BUN_WATCH_RECONCILE_INTERVAL_MS)
-        : null;
-    interval?.unref();
-
     this.watchers.set(resolved, {
       close: () => {
         nativeWatcher?.close();
-        if (interval) {
-          clearInterval(interval);
-        }
       },
     });
   }

package/src/mcp/server.ts

@@ -24,17 +24,15 @@ import {
 import { formatLiteralLocate } from "../literal.ts";
 import type { Chunk, ContentType, SearchResult } from "../types.ts";
 import {
-  clampMcpTopK,
   DEFAULT_EXPAND_AFTER,
   DEFAULT_EXPAND_BEFORE,
-  DEFAULT_MCP_TOP_K,
   dedupeResultsByFile,
   expandChunksAtLine,
   formatExpandResults,
   formatResults,
   localRepoRoot,
-  MAX_MCP_TOP_K,
   resolveChunk,
+  SEARCH_RESULT_COUNT,
 } from "../utils.ts";
 import { registerAuthTool, toolErrorText } from "./auth-tool.ts";
 import {
@@ -52,6 +50,8 @@ const REPO_DESCRIPTION =
 
 const BENCHMARK_SKIP_NOTES = {
   local_repo_only: "Benchmark comparisons require a local repo path; git URL repos are skipped.",
+  filtered_search:
+    "Benchmark comparisons are skipped when search is restricted by include/exclude patterns.",
   limited_locate:
     "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:
@@ -147,27 +147,35 @@ export function createMcpServer(
             "Natural language or code query — your default for all code search in this repo.",
           ),
         repo: z.string().describe(REPO_DESCRIPTION),
-        top_k: z
-          .number()
-          .int()
+        include: z
+          .array(z.string().min(1))
           .min(1)
-          .max(MAX_MCP_TOP_K)
           .optional()
-          .describe(`Number of results (default ${DEFAULT_MCP_TOP_K}, max ${MAX_MCP_TOP_K}).`),
+          .describe(
+            'Gitignore-style glob patterns; only matching files are searched (e.g. ["src/auth/**", "docs/**/*.md"]). Same semantics 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)."),
       },
     },
-    async ({ query, repo, top_k: topK, dedupe_by_file: dedupeByFile }) => {
+    async ({ query, repo, include, exclude, dedupe_by_file: dedupeByFile }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
         const repoRoot = localRepoRoot(repo);
-        const k = clampMcpTopK(topK);
-
+        const k = SEARCH_RESULT_COUNT;
         let skip: BenchmarkSkipReason | undefined;
-        if (benchmark && repoRoot) {
+        if (benchmark && (include || exclude)) {
+          skip = "filtered_search";
+        } else if (benchmark && repoRoot) {
           const comparison = await withGrepTimeoutFallback(() =>
             benchmarkSearchComparison({
               query,
@@ -199,7 +207,7 @@ export function createMcpServer(
           skip = "local_repo_only";
         }
 
-        let results = await index.search({ query, topK: k });
+        let results = await index.search({ query, topK: k, include, exclude });
         if (dedupeByFile !== false) {
           results = dedupeResultsByFile(results);
         }
@@ -226,10 +234,17 @@ export function createMcpServer(
       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.",
           ),
+        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.",
+          ),
         repo: z.string().describe(REPO_DESCRIPTION),
         mode: z
           .enum(["count", "locations", "lines"])
@@ -270,13 +285,17 @@ export function createMcpServer(
           .describe("Lines of context before/after each match, like `grep -C` (mode=lines only)."),
       },
     },
-    async ({ literal, repo, ...locateOpts }) => {
+    async ({ literal, query, repo, ...locateOpts }) => {
+      const lit = literal ?? query;
+      if (lit == null) {
+        return toolErrorText(new Error("locate requires `literal` (exact substring to find)."));
+      }
       try {
         const index = await getIndexForRepo(repo, cache);
 
         let skip: BenchmarkSkipReason | undefined;
         const repoRoot = localRepoRoot(repo);
-        if (benchmark && repoRoot && typeof literal === "string") {
+        if (benchmark && repoRoot && typeof lit === "string") {
           if (locateOpts.limit != null) {
             skip = "limited_locate";
           } else if (!selectComparableLiteralSearchTool()) {
@@ -285,7 +304,7 @@ export function createMcpServer(
           if (!skip) {
             const comparison = await withGrepTimeoutFallback(() =>
               benchmarkLocateComparison({
-                literal,
+                literal: lit,
                 repoPath: repoRoot,
                 index,
                 locate: locateOpts,
@@ -302,7 +321,7 @@ export function createMcpServer(
           skip = "local_repo_only";
         }
 
-        const result = index.locateLiteral(literal, locateOpts);
+        const result = index.locateLiteral(lit, locateOpts);
         const payload = formatLiteralLocate(result);
         const body = formatLiteralLocateText(payload);
         return toolText(skip ? withBenchmarkSkippedNote(body, skip) : body);
@@ -386,18 +405,9 @@ export function createMcpServer(
           .int()
           .describe("Line from the search hit (`anchor_line` when truncated, else `start_line`)."),
         repo: z.string().describe(REPO_DESCRIPTION),
-        top_k: z
-          .number()
-          .int()
-          .min(1)
-          .max(MAX_MCP_TOP_K)
-          .optional()
-          .describe(
-            `Number of similar chunks to return (default ${DEFAULT_MCP_TOP_K}, max ${MAX_MCP_TOP_K}).`,
-          ),
       },
     },
-    async ({ file_path: filePath, anchor_line: anchorLine, repo, top_k: topK }) => {
+    async ({ file_path: filePath, anchor_line: anchorLine, repo }) => {
       try {
         const index = await getIndexForRepo(repo, cache);
         const repoRoot = localRepoRoot(repo);
@@ -407,7 +417,7 @@ export function createMcpServer(
             `No chunk found at ${filePath}:${anchorLine}. Make sure the file is indexed and the line number is within a known chunk.`,
           );
         }
-        const results = await index.findRelated(chunk, clampMcpTopK(topK));
+        const results = await index.findRelated(chunk, SEARCH_RESULT_COUNT);
         if (results.length === 0) {
           return toolText(`No related chunks found for ${filePath}:${anchorLine}.`);
         }

package/src/miru-index.ts

@@ -14,7 +14,12 @@ import { createIndexFromPath } from "./index/create.ts";
 import { applyIncrementalFileChanges, normalizeRelativePath } from "./index/incremental.ts";
 import { persistencePaths, saveIndexBundle } from "./index/persistence.ts";
 import type { SemanticIndex } from "./index/semantic-index.ts";
-import { type LiteralLocateOptions, type LiteralLocateResult, locateLiteral } from "./literal.ts";
+import {
+  filterChunksByGlob,
+  type LiteralLocateOptions,
+  type LiteralLocateResult,
+  locateLiteral,
+} from "./literal.ts";
 import { hybridSearch, searchSemanticOnly } from "./search.ts";
 import type { Chunk, ContentType, SearchResult } from "./types.ts";
 import { chunkKey, chunkToDict, defaultContentTypes } from "./types.ts";
@@ -407,11 +412,19 @@ export class MiruIndex {
     );
   }
 
+  private getPathSelector(include?: string[], exclude?: string[]): readonly number[] | undefined {
+    if (!include?.length && !exclude?.length) {
+      return undefined;
+    }
+    const included = new Set(filterChunksByGlob(this.chunks, include, exclude).map(chunkKey));
+    return this.chunks.flatMap((chunk, index) => (included.has(chunkKey(chunk)) ? [index] : []));
+  }
+
   /**
    * Hybrid BM25 + semantic search over indexed chunks.
    *
    * `alpha` blends keyword vs vector scores (default depends on content type).
-   * `filterLanguages` / `filterPaths` restrict candidates before ranking.
+   * `include` / `exclude` glob patterns restrict candidate files before ranking.
    * `rerank` defaults to on for code indexes (cross-encoder style reranking).
    */
   async search(options: {
@@ -422,15 +435,34 @@ export class MiruIndex {
     alpha?: number | null;
     filterLanguages?: string[];
     filterPaths?: string[];
+    include?: string[];
+    exclude?: string[];
     rerank?: boolean;
   }): Promise<SearchResult[]> {
-    const { query, queryVector, topK = 10, alpha, filterLanguages, filterPaths, rerank } = options;
+    const {
+      query,
+      queryVector,
+      topK = 10,
+      alpha,
+      filterLanguages,
+      filterPaths,
+      include,
+      exclude,
+      rerank,
+    } = options;
 
     if (!this.chunks.length || !query.trim()) {
       return [];
     }
 
     const resolvedRerank = rerank ?? this.content.includes("code");
+    const selector = this.getSelector(filterLanguages, filterPaths);
+    const pathSelector = this.getPathSelector(include, exclude);
+    let effectiveSelector = pathSelector ?? selector;
+    if (selector && pathSelector) {
+      const allowedIndices = new Set(selector);
+      effectiveSelector = pathSelector.filter((index) => allowedIndices.has(index));
+    }
 
     return hybridSearch({
       query,
@@ -441,7 +473,7 @@ export class MiruIndex {
       chunks: this.chunks,
       topK,
       alpha,
-      selector: this.getSelector(filterLanguages, filterPaths),
+      selector: effectiveSelector,
       rerank: resolvedRerank,
     });
   }

package/src/search.ts

@@ -96,6 +96,10 @@ export async function hybridSearch(options: {
     rerank = true,
   } = options;
 
+  if (selector?.length === 0) {
+    return [];
+  }
+
   const alphaWeight = resolveAlpha(query, alpha);
   const tuning = rankingConfig();
   const candidateCount =

package/src/types.ts

@@ -1,7 +1,7 @@
 export type ContentType = "code" | "docs" | "config";
 
-/** Default index corpus: source code plus config (json/yaml/toml/…). */
-export const DEFAULT_CONTENT_TYPES: readonly ContentType[] = ["code", "config"];
+/** Default index corpus: source code, config (json/yaml/toml/…), and docs (md/rst/txt). */
+export const DEFAULT_CONTENT_TYPES: readonly ContentType[] = ["code", "config", "docs"];
 
 /** Mutable copy of {@link DEFAULT_CONTENT_TYPES} for API defaults. */
 export function defaultContentTypes(): ContentType[] {

package/src/utils.ts

@@ -100,22 +100,12 @@ export type ExpandResults = {
   chunks: Record<string, unknown>[];
 };
 
-export const DEFAULT_MCP_TOP_K = 3;
-export const MAX_MCP_TOP_K = 10;
+export const SEARCH_RESULT_COUNT = 5;
 
 /** Extra chunks before/after the expand anchor — MCP `expand` tool defaults. */
 export const DEFAULT_EXPAND_BEFORE = 1;
 export const DEFAULT_EXPAND_AFTER = 1;
 
-/** Clamp MCP top_k to a sane range; omit for the default. */
-export function clampMcpTopK(topK?: number): number {
-  const value = topK ?? DEFAULT_MCP_TOP_K;
-  if (!Number.isFinite(value) || value < 1) {
-    return DEFAULT_MCP_TOP_K;
-  }
-  return Math.min(Math.floor(value), MAX_MCP_TOP_K);
-}
-
 function chunkToResponseDict(chunk: Chunk, repoRoot?: string | null): Record<string, unknown> {
   const dict = chunkToDict(chunk);
   if (!repoRoot) {

package/src/version.ts

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import packageJson from "../package.json";
 import { resolveCacheFolder } from "./cache.ts";
@@ -79,7 +80,12 @@ function updateCheckPath(): string {
 
 async function readUpdateCheckCache(): Promise<UpdateCheckCache | null> {
   try {
-    const raw = await Bun.file(updateCheckPath()).text();
+    // node:fs/promises, not Bun.file().text(): a rejecting Bun.file() read
+    // (the common case here — no cache on a fresh install) doesn't keep
+    // Bun's Windows event loop alive, so the process can exit silently
+    // before this ever settles. Confirmed regression in Bun 1.4.0-1.4.2:
+    // github.com/oven-sh/bun/issues/39787 (fix open, not yet released).
+    const raw = await readFile(updateCheckPath(), "utf8");
     const parsed = JSON.parse(raw) as UpdateCheckCache;
     if (typeof parsed.checkedAt !== "number" || typeof parsed.latest !== "string") {
       return null;