@takara-ai/miru-code 0.3.0 → 0.4.1

package/README.md

@@ -2,301 +2,270 @@
 
 Hybrid code search for AI agents — **TypeScript**, **Bun**, and **Takara embeddings**.
 
-## What is Miru?
+Miru helps coding agents **find code by meaning**. Ask “where is auth middleware configured?” and get back the most relevant **chunks** (file path, line range, snippet) instead of grepping the whole tree.
 
-*Miru* (見る) means “to see” or “to look” in Japanese. Miru helps coding agents **find code by meaning** instead of guessing file paths or running exhaustive greps.
+## Quick start
 
-When an agent asks “where is auth middleware configured?” or “how do we batch embeddings?”, Miru returns the most relevant **chunks** of your codebase — file path, line range, and snippet — so the agent can read only what matters.
-
-### Why hybrid search?
-
-Pure semantic search misses exact symbol matches. Pure keyword search misses paraphrased intent. Miru combines both:
-
-1. **Dense (semantic)** — Takara code embeddings (`ds1-potion-code-16m`) over structurally chunked source files.
-2. **Sparse (BM25)** — keyword scoring with an inverted index; parallelized in Bun workers on large repos.
-3. **RRF fusion** — reciprocal rank fusion merges the two ranked lists.
-4. **Reranking** — code-tuned penalties and boosts (e.g. multi-chunk files, query-term overlap).
-
-Indexes are built on demand, cached on disk, and invalidated when files change. You can search **code**, **docs**, **config**, or **all** content types.
-
-### How agents use Miru
-
-| Mode | Best for | What the agent gets |
-|------|----------|---------------------|
-| **MCP server** | Cursor, Claude Code, VS Code Copilot, Gemini CLI, Kiro, OpenCode | Native `search` and `find_related` tools over the workspace |
-| **CLI sub-agent** | Any agent with shell access | `miru init --agent <id>` writes a specialist agent that runs `miru search` / `miru find-related` via Bash |
-
-Both modes share the same index and cache. Pick MCP when your IDE supports it; use the sub-agent when you want a dedicated exploration agent without MCP wiring.
-
-## Install
-
-Requires [Bun](https://bun.sh) 1.1+ on your PATH (`curl -fsSL https://bun.sh/install | bash`).
+**Requirements:** [Bun](https://bun.sh) 1.1+ and a [Takara API key](https://takara.ai) for embeddings.
 
 ```bash
-# Run once without installing
-bunx @takara-ai/miru-code search "auth middleware" ./src
-
-# Global CLI
+# 1. Install the CLI
 bun add -g @takara-ai/miru-code
-miru search "auth middleware" ./src
 
-# Library
-bun add @takara-ai/miru-code
-```
+# 2. Store your API key (validates against Takara)
+miru setup
 
-```ts
-import { MiruIndex } from "@takara-ai/miru-code";
+# 3. Wire into your agents (MCP + instructions + sub-agent)
+miru install
 
-const index = await MiruIndex.fromPath("./src");
+# 4. Restart your IDE / agent session, then search
+miru search "auth middleware" ./src
 ```
 
-## Setup
+That’s the full path for most users. `miru install` is interactive — it detects Cursor, Claude Code, Gemini CLI, Kiro, OpenCode, GitHub Copilot, Codex, and VS Code, and lets you pick what to configure.
+
+**One-off without installing:**
 
 ```bash
-bun install
+bunx @takara-ai/miru-code search "auth middleware" ./src
 ```
 
-Add credentials to `.env.local` (loaded automatically when you run from this repo), or pass them in your MCP config `env` block (recommended — MCP does not inherit IDE env vars reliably).
-
-| Variable | Default |
-|----------|---------|
-| `TAKARA_API_KEY` | (required) Takara bearer token for embeddings |
-| `MIRU_OPENAI_BASE_URL` | `https://infer.dev.takara.ai/v1` |
-| `MIRU_OPENAI_EMBEDDING_MODEL` | `ds1-potion-code-16m` |
-| `MIRU_EMBEDDING_DIMENSIONS` | `256` (auto for potion) |
-| `MIRU_FLOAT_VECTORS` | unset (default **int8** quantized vectors); set `1` for float32 |
-| `MIRU_EMBEDDING_BATCH_SIZE` | `32` (max for this model) |
-| `MIRU_CONCURRENCY` | logical CPUs **minus 2** (min 1) |
+**Undo agent setup:** `miru uninstall`
 
-Parallelism: file reads/chunking, embedding batches (up to concurrency in flight), query embed overlapping BM25, and **BM25 scoring in Bun workers** (shards by doc range when index has 256+ chunks). BM25 uses an inverted postings list for fast single-threaded search on small indexes. Override with `MIRU_CONCURRENCY`.
+---
 
-## IDE integration
+## How to read this doc
 
-Miru supports six agent platforms. For each, you can wire the **MCP server** (recommended) and/or install a **CLI sub-agent** with `miru init`.
+| Goal | Section |
+|------|---------|
+| Get running in an IDE | [Quick start](#quick-start) → [IDE integration](#ide-integration) |
+| Search from terminal or scripts | [CLI](#cli) |
+| Use as a library | [Library](#library) |
+| Contribute to this repo | [Developing Miru](#developing-miru) |
 
-### Quick reference
+## Install options
 
-| IDE | MCP config file | Sub-agent command | Sub-agent output |
-|-----|-----------------|-------------------|------------------|
-| [Cursor](#cursor) | `~/.cursor/mcp.json` or `.cursor/mcp.json` | `miru init --agent cursor` | `.cursor/agents/miru-code.md` |
-| [Claude Code](#claude-code) | `.mcp.json` (project root) or `~/.claude.json` | `miru init --agent claude` | `.claude/agents/miru-code.md` |
-| [VS Code / Copilot](#vs-code--github-copilot) | `.vscode/mcp.json` or user profile `mcp.json` | `miru init --agent copilot` | `.github/agents/miru-code.md` |
-| [Gemini CLI](#gemini-cli) | `~/.gemini/settings.json` or `.gemini/settings.json` | `miru init --agent gemini` | `.gemini/agents/miru-code.md` |
-| [Kiro](#kiro) | `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json` | `miru init --agent kiro` | `.kiro/agents/miru-code.md` |
-| [OpenCode](#opencode) | `~/.config/opencode/opencode.json` or `opencode.json` | `miru init --agent opencode` | `.opencode/agents/miru-code.md` |
+| Method | Command | When to use |
+|--------|---------|-------------|
+| Global CLI | `bun add -g @takara-ai/miru-code` | Daily use, `miru install`, terminal search |
+| One-off | `bunx @takara-ai/miru-code …` | Try before installing |
+| Library | `bun add @takara-ai/miru-code` | Embed search in your own tool |
+| From source | [Developing Miru](#developing-miru) | Contributors |
 
-Run `miru init --agent <id> --force` to overwrite an existing sub-agent file.
+After install, `miru` is on your PATH. Run `miru` with no args for help.
 
-### MCP server
+## Credentials
 
-Run with **no arguments** to start the stdio MCP server. Indexing begins on the first `search` or `find_related` call, using the `repo` path you pass. Optional `--ref` sets the default git ref for remote repos.
+Miru needs `TAKARA_API_KEY` — a Takara bearer token for code embeddings.
 
 ```bash
-bunx @takara-ai/miru-code
-# or after bun add -g @takara-ai/miru-code:  miru
+miru setup              # interactive; validates and stores locally
+miru setup --key TOKEN  # non-interactive
+miru setup --clear      # remove stored key
 ```
 
-**Tools:** `search`, `find_related` — `repo` is required (project root or https:// git URL).
+Stored credentials live at:
 
-For MCP configs, use `bunx` as the command (`bun` with `x` in `args` works too — they're equivalent).
+- macOS: `~/Library/Application Support/miru/credentials.json`
+- Linux: `~/.config/miru/credentials.json`
+- Windows: `%APPDATA%\miru\credentials.json`
 
-Put the bearer token in `env`; MCP will not read `.env.local` unless those vars are unset.
+Override with `MIRU_CREDENTIALS_DIR`.
 
-#### Shared env block
+**For MCP in an IDE:** also set `TAKARA_API_KEY` in the MCP server `env` block. MCP subprocesses do not reliably inherit your shell or `.env.local`. `miru install` writes `"TAKARA_API_KEY": "${TAKARA_API_KEY}"` where your IDE supports variable expansion — export the var or paste your token.
 
-Use this in every MCP config below (adjust the key name if your IDE uses `environment` instead of `env`):
+## IDE integration
 
-```json
-{
-  "TAKARA_API_KEY": "your-takara-bearer-token",
-  "MIRU_OPENAI_BASE_URL": "https://infer.dev.takara.ai/v1",
-  "MIRU_OPENAI_EMBEDDING_MODEL": "ds1-potion-code-16m",
-  "MIRU_EMBEDDING_DIMENSIONS": "256"
-}
-```
+### Recommended: `miru install`
 
-### Cursor
+Configures up to three integrations per agent:
 
-**MCP** — `~/.cursor/mcp.json` or project `.cursor/mcp.json`:
+| Integration | What it does |
+|-------------|----------------|
+| **MCP server** | Native `search` and `find_related` tools |
+| **Instructions** | Marked usage block in `CLAUDE.md`, `GEMINI.md`, `AGENTS.md`, etc. |
+| **Sub-agent** | Global `miru-code` agent file (Bash-backed search for sub-agents without MCP) |
 
-```json
-{
-  "mcpServers": {
-    "miru": {
-      "command": "bunx",
-      "args": ["@takara-ai/miru-code"],
-      "env": {
-        "TAKARA_API_KEY": "your-takara-bearer-token"
-      }
-    }
-  }
-}
+```bash
+miru install      # pick agents + integrations
+miru uninstall    # remove miru entries
 ```
 
-After `bun add -g @takara-ai/miru-code`, you can use `"command": "miru"` instead.
+Restart your IDE or agent session after install.
+
+### Where files go (global user config)
 
-**Sub-agent:**
+| Agent | MCP config | Sub-agent |
+|-------|------------|-----------|
+| Claude Code | `~/.claude.json` | `~/.claude/agents/miru-code.md` |
+| Cursor | `~/.cursor/mcp.json` | `~/.cursor/agents/miru-code.md` |
+| Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/agents/miru-code.md` |
+| Kiro | `~/.kiro/settings/mcp.json` | `~/.kiro/agents/miru-code.md` |
+| OpenCode | `~/.config/opencode/opencode.json(c)` | `~/.config/opencode/agents/miru-code.md` |
+| GitHub Copilot | `~/.copilot/mcp-config.json` | `~/.copilot/agents/miru-code.agent.md` |
+| Codex | `~/.codex/config.toml` | — |
+| VS Code | user profile `Code/User/mcp.json` | — |
+
+### Per-project sub-agent (`miru init`)
+
+To commit a sub-agent into a repo for your team (project-local, not global):
 
 ```bash
-miru init --agent cursor
+miru init --agent claude --force   # → .claude/agents/miru-code.md
 ```
 
-Commit `.cursor/agents/miru-code.md` to share the exploration agent with your team.
+Agents: `cursor`, `claude`, `copilot`, `gemini`, `kiro`, `opencode`.
 
-### Claude Code
+### Manual MCP setup
 
-**MCP** — project `.mcp.json` (check into git) or user scope in `~/.claude.json`:
+Skip `miru install` and add this to your IDE’s MCP config (`mcpServers`, `servers`, or `mcp` depending on the tool):
 
 ```json
 {
-  "mcpServers": {
-    "miru": {
-      "type": "stdio",
-      "command": "bunx",
-      "args": ["@takara-ai/miru-code"],
-      "env": {
-        "TAKARA_API_KEY": "${TAKARA_API_KEY}"
-      }
+  "miru": {
+    "command": "bunx",
+    "args": ["@takara-ai/miru-code"],
+    "env": {
+      "TAKARA_API_KEY": "your-takara-bearer-token"
     }
   }
 }
 ```
 
-Claude Code supports `${VAR}` expansion in config files. Restart the session and run `/mcp` to verify the connection.
+After `bun add -g @takara-ai/miru-code`, you can use `"command": "miru"` instead of `bunx`.
 
-Or via CLI:
+**MCP tools**
 
-```bash
-claude mcp add miru -s project -- bunx @takara-ai/miru-code
-```
+| Tool | Purpose |
+|------|---------|
+| `search` | Natural-language or code query; requires `repo` (project root or `https://` git URL); optional `top_k` (default 5) |
+| `find_related` | Similar chunks to `file_path` + `line` from a prior hit; requires `repo` |
 
-**Sub-agent:**
+Indexing runs on the first tool call per `repo`. Pass the **project root** for local workspaces. Remote repos need an explicit `https://` or `http://` URL (not `git@` SSH).
 
-```bash
-miru init --agent claude
-```
+**IDE-specific notes**
 
-Writes `.claude/agents/miru-code.md` — invoke the `miru-code` agent for semantic exploration tasks.
+- **Claude Code:** supports `${TAKARA_API_KEY}` in config; verify with `/mcp`. Or: `claude mcp add miru -s user -- bunx @takara-ai/miru-code`
+- **VS Code:** uses `"servers"` not `mcpServers`; restart via **MCP: List Servers**
+- **OpenCode:** uses `mcp`, `"type": "local"`, and `environment` instead of `env`
+- **Kiro:** include `PATH` in `env` if Bun is not on the default path
 
-### VS Code / GitHub Copilot
+Optional MCP startup flags: `--ref BRANCH`, `--content code docs …`
 
-**MCP** — workspace `.vscode/mcp.json` or user profile (Command Palette: **MCP: Open User Configuration**):
+## How Miru works
 
-```json
-{
-  "servers": {
-    "miru": {
-      "type": "stdio",
-      "command": "bunx",
-      "args": ["@takara-ai/miru-code"],
-      "env": {
-        "TAKARA_API_KEY": "your-takara-bearer-token"
-      }
-    }
-  }
-}
-```
+### Hybrid search
 
-VS Code uses `"servers"` (not `mcpServers`). Use **MCP: List Servers** to start or restart the server after editing the config.
+1. **Dense (semantic)** — Takara code embeddings (`ds1-potion-code-16m`) over structurally chunked files
+2. **Sparse (BM25)** — keyword index; parallelized in Bun workers when the index has 256+ chunks
+3. **RRF fusion** — merges semantic and keyword rankings
+4. **Reranking** — code-tuned boosts and penalties
 
-**Sub-agent:**
+Index **code**, **docs**, **config**, or **all** via `--content` (CLI/MCP) or when building a library index.
 
-```bash
-miru init --agent copilot
-```
+### Agent workflow
 
-Writes `.github/agents/miru-code.md` for Copilot’s agent system.
+1. `search` with a natural-language or code query
+2. Read returned chunks
+3. `find_related` on a promising `file_path` + line (optional)
+4. Open full files only when the chunk is not enough
+5. Use grep for exhaustive literal matches
 
-### Gemini CLI
+### Caching
 
-**MCP** — `~/.gemini/settings.json` or project `.gemini/settings.json`:
-
-```json
-{
-  "mcpServers": {
-    "miru": {
-      "command": "bunx",
-      "args": ["@takara-ai/miru-code"],
-      "env": {
-        "TAKARA_API_KEY": "your-takara-bearer-token"
-      }
-    }
-  }
-}
-```
+| Layer | Behavior |
+|-------|----------|
+| **First search** | Builds index, writes disk cache |
+| **MCP (local repo, same session)** | Watches files and incrementally re-indexes; disable with `MIRU_MCP_WATCH=0` |
+| **CLI / new MCP session** | Reuses disk cache; run `miru clear <path>` after large refactors |
+| **Remote repos** | Cloned per session; use `--ref` for branch/tag |
 
-Or add interactively: `gemini mcp add`. Run `/mcp` inside a session to confirm tools are available.
+Cache: `~/Library/Caches/miru` (macOS), `~/.cache/miru` (Linux), `%LOCALAPPDATA%\miru\Cache` (Windows).
 
-**Sub-agent:**
+## CLI
 
 ```bash
-miru init --agent gemini
+miru setup
+miru install
+miru search "where are embeddings created" ./src -k 10 --content code
+miru find-related src/embeddings/openai.ts 120 ./src
+miru clear ./src
+miru uninstall
+miru help search
 ```
 
-Writes `.gemini/agents/miru-code.md`.
+| Command | Summary |
+|---------|---------|
+| `search <query> [path]` | Hybrid search; path defaults to cwd; local path or `https://` git URL |
+| `find-related <file> <line> [path]` | Semantic neighbors at that line |
+| `setup` | Store and validate `TAKARA_API_KEY` |
+| `install` | Interactive global agent setup |
+| `uninstall` | Remove miru agent configuration |
+| `init --agent <id>` | Project-local sub-agent markdown |
+| `clear [path]` | Delete disk cache |
+| *(no command)* | Start stdio MCP server |
 
-### Kiro
+**Options:** `-k` / `--top-k N` (default 5), `--content code|docs|config|all`, `--json` (force JSON output).
 
-**MCP** — `~/.kiro/settings/mcp.json` or workspace `.kiro/settings/mcp.json`:
+**Output:** In a terminal, search results are formatted for reading (path, score, snippet preview). Piped output and `--json` emit JSON (`query` + `results` with `chunk`, `score`, `location`). Progress spinners go to stderr.
 
-```json
-{
-  "mcpServers": {
-    "miru": {
-      "command": "bunx",
-      "args": ["@takara-ai/miru-code"],
-      "env": {
-        "TAKARA_API_KEY": "your-takara-bearer-token",
-        "PATH": "/usr/local/bin:/usr/bin:/bin"
-      }
-    }
-  }
-}
-```
+From **this repo**, prefix commands with `bun run miru`.
 
-Kiro runs with a minimal environment — include `PATH` if Bun is not on the default path. Approve env vars when prompted in the IDE.
+## Library
 
-**Sub-agent:**
+```ts
+import { MiruIndex } from "@takara-ai/miru-code";
 
-```bash
-miru init --agent kiro
+const index = await MiruIndex.fromPath("./src", ["code"]);
+const fromUrl = await MiruIndex.fromSource(
+  "https://github.com/org/repo",
+  ["code"],
+  undefined,
+  "main",
+);
+
+const results = await index.search({
+  query: "BM25 tokenize",
+  topK: 10,
+  filterPaths: ["src/index/bm25.ts"],
+});
+
+const related = await index.findRelated(results[0], 5);
+await index.saveToDefaultCache("./src");
 ```
 
-Writes `.kiro/agents/miru-code.md`.
-
-### OpenCode
+Exports: `MiruIndex`, `clearCache`, `findIndexCachePath`, `resolveCacheFolder`, and chunk/result types.
 
-**MCP** — `~/.config/opencode/opencode.json` or project `opencode.json`:
+## Environment variables
 
-```json
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "miru": {
-      "type": "local",
-      "command": ["bunx", "@takara-ai/miru-code"],
-      "enabled": true,
-      "environment": {
-        "TAKARA_API_KEY": "your-takara-bearer-token"
-      }
-    }
-  }
-}
-```
+| Variable | Default / notes |
+|----------|-----------------|
+| `TAKARA_API_KEY` | **Required** — Takara bearer token |
+| `MIRU_OPENAI_BASE_URL` | `https://infer.dev.takara.ai/v1` |
+| `MIRU_OPENAI_EMBEDDING_MODEL` | `ds1-potion-code-16m` |
+| `MIRU_EMBEDDING_DIMENSIONS` | `256` for potion (auto when unset) |
+| `MIRU_FLOAT_VECTORS` | unset = int8; `1` = float32 |
+| `MIRU_EMBEDDING_BATCH_SIZE` | `32` |
+| `MIRU_CONCURRENCY` | logical CPUs minus 2 (min 1) |
+| `MIRU_MCP_WATCH` | on; `0` or `false` disables MCP file watch |
+| `MIRU_CREDENTIALS_DIR` | Override credentials directory |
+| `NO_COLOR` | Disable CLI colors |
 
-OpenCode uses the `mcp` key (not `mcpServers`), requires `"type": "local"`, and uses `environment` instead of `env`. Verify with `opencode mcp list`.
+See `.env.example` for optional pipeline tuning (`MIRU_PIPELINE_*`).
 
-**Sub-agent:**
+## Developing Miru
 
 ```bash
-miru init --agent opencode
+git clone https://github.com/takara-ai/miru-code.git
+cd miru-code
+bun install
+cp .env.example .env.local   # add TAKARA_API_KEY
+bun test
+bun run typecheck
+bun run lint
 ```
 
-Writes `.opencode/agents/miru-code.md` (subagent mode with bash/read permissions).
-
-### Local development (any IDE)
-
-Point MCP at this repo instead of the published package:
+**Local MCP** — point at your clone:
 
 ```json
 {
@@ -308,63 +277,15 @@ Point MCP at this repo instead of the published package:
 }
 ```
 
-Merge into the appropriate wrapper key (`mcpServers`, `servers`, or `mcp`) for your IDE.
-
-## CLI
-
-```bash
-# Hybrid search (positional, Python-compatible)
-bun run miru search "where are embeddings created" ./src -k 5
-
-# Find semantically related chunks
-bun run miru find-related src/embeddings/openai.ts 120 ./src
-
-# Write a miru-code sub-agent for your IDE
-bun run miru init --agent cursor
-
-# Clear disk cache
-bun run miru clear ./src
-```
-
-Indexes are cached under `~/Library/Caches/miru` (macOS) or `~/.cache/miru` (Linux).
-
-## Library
-
-```ts
-import { MiruIndex } from "@takara-ai/miru-code";
-
-const index = await MiruIndex.fromPath("./src");
-const results = await index.search({ query: "BM25 tokenize", topK: 10 });
-```
-
-## Tests
-
-```bash
-bun test
-bun run typecheck
-```
-
 ## Publishing
 
-Releases use **Bun** for install, test, and `bun pm pack`. The registry upload uses **`npm publish`** on that tarball because [Bun does not yet support npm OIDC trusted publishing](https://github.com/oven-sh/bun/issues/22423) — no long-lived npm tokens in GitHub secrets.
-
-**Local publish** (logged in to npm; `publishConfig.access` is already `public`):
-
-```bash
-bun publish
-```
-
-Runs `prepublishOnly` (typecheck + tests), then a single registry upload. Do not add a `publish` script that calls `npm publish` — Bun runs lifecycle scripts after its own upload and would publish twice.
-
-**CI** (after Trusted Publisher is configured on npm):
+Releases use **Bun** for install, test, and `bun pm pack`. Registry upload uses **`npm publish`** on that tarball because [Bun does not yet support npm OIDC trusted publishing](https://github.com/oven-sh/bun/issues/22423).
 
 ```bash
-npm version patch
-git push && git push --tags
-gh release create v0.1.1 --generate-notes
+bun publish   # local, logged in to npm
 ```
 
-The `release.yml` workflow runs when the GitHub Release is published.
+**CI:** tag a GitHub Release; `release.yml` publishes to npm via Trusted Publisher.
 
 ## License
 

package/package.json

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

package/src/agents/claude.md

@@ -12,7 +12,7 @@ miru search "save_pretrained" ./my-project
 miru search "save model to disk" ./my-project --top-k 10
 ```
 
-Results are cached automatically on first run and invalidated when files change.
+First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
 
 Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
 

package/src/agents/copilot.md

@@ -12,7 +12,7 @@ miru search "save_pretrained" ./my-project
 miru search "save model to disk" ./my-project --top-k 10
 ```
 
-Results are cached automatically on first run and invalidated when files change.
+First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
 
 Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
 

package/src/agents/cursor.md

@@ -11,7 +11,7 @@ miru search "save_pretrained" ./my-project
 miru search "save model to disk" ./my-project --top-k 10
 ```
 
-Results are cached automatically on first run and invalidated when files change.
+First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
 
 Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
 

package/src/agents/gemini.md

@@ -14,7 +14,7 @@ miru search "save_pretrained" ./my-project
 miru search "save model to disk" ./my-project --top-k 10
 ```
 
-Results are cached automatically on first run and invalidated when files change.
+First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
 
 Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
 

package/src/agents/kiro.md

@@ -14,7 +14,7 @@ miru search "save_pretrained" ./my-project
 miru search "save model to disk" ./my-project --top-k 10
 ```
 
-Results are cached automatically on first run and invalidated when files change.
+First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
 
 Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config:
 

package/src/agents/opencode.md

@@ -15,7 +15,7 @@ miru search "save_pretrained" ./my-project
 miru search "save model to disk" ./my-project --top-k 10
 ```
 
-Results are cached automatically on first run and invalidated when files change.
+First run builds a disk cache. The MCP server incrementally updates local indexes while it runs; after CLI-only use or large refactors, run `miru clear <path>` to rebuild.
 
 Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: