memtrace 0.3.27 → 0.3.30

package/installer/skills/commands/memtrace-index.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-index
-description: "Always use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, or when code exploration is needed but no Memtrace index exists. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed."
+description: "Always use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, when code exploration needs an index, or when searches return 0/partial results for source paths under an indexed root. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed."
 allowed-tools:
   - mcp__memtrace__index_directory
   - mcp__memtrace__check_job_status
@@ -32,6 +32,11 @@ Use the `list_indexed_repositories` MCP tool first. If the repo is already index
 
 **Success criteria:** You have a list of repo_ids and their last-indexed timestamps.
 
+If a repo is present but searches miss a source subdirectory under that repo
+root (for example `ui/`, `memtrace-ui/`, `web/`, `frontend/`, or `src/`), treat
+that as a stale/partial index. Do not use grep as a workaround. Run incremental
+indexing on the repo root, then retry the Memtrace query.
+
 ### 2. Index the directory
 
 Use the `index_directory` MCP tool:

package/installer/skills/commands/memtrace-search.md

@@ -1,11 +1,6 @@
 ---
 name: memtrace-search
-description: "Always use to find, search, locate, or look up source-code symbols, functions, classes, types, constants, definitions, implementations, logic, error strings inside code, or where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery; Memtrace uses BM25, vector search, RRF, and the AST graph."
-allowed-tools:
-  - mcp__memtrace__find_code
-  - mcp__memtrace__find_symbol
-  - mcp__memtrace__list_indexed_repositories
-user-invocable: true
+description: "Always use to find, search, locate, or look up source-code symbols, functions, classes, types, constants, definitions, implementations, logic, error strings inside code, or where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
 ---
 
 ## Overview
@@ -18,6 +13,7 @@ Find code using hybrid BM25 full-text + semantic vector search with Reciprocal R
 |------|----------|
 | `find_code` | Natural-language queries ("authentication middleware", "retry logic"), broad searches |
 | `find_symbol` | Exact identifier names ("getUserById", "PaymentService"), when you know the name |
+| `get_source_window` | Optional: bounded source read after a Memtrace hit, when your harness lacks `Read(file, offset, limit)`. Otherwise prefer your harness's bounded read with the returned `start_line` / `end_line`. |
 
 ## Steps
 
@@ -52,6 +48,15 @@ Find code using hybrid BM25 full-text + semantic vector search with Reciprocal R
 
 ### 3. Use results for next steps
 
+The default next step is a **graph tool** — `get_symbol_context`,
+`analyze_relationships`, or `get_impact`. Those answer "who calls this",
+"what's the blast radius", "what community is it part of" — context no
+file read can give. That's what Memtrace uniquely provides.
+
+Source bytes come last, only when you're about to edit or quote. Use a
+bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`,
+or `get_source_window` if your harness lacks bounded reads. Do not whole-file.
+
 Save the symbol `id` from results — pass it to:
 - `analyze_relationships` to map callers/callees
 - `get_symbol_context` for a 360-degree view
@@ -65,3 +70,7 @@ Save the symbol `id` from results — pass it to:
 | Using find_symbol for vague queries | Use `find_code` for natural-language; `find_symbol` is for exact names |
 | Ignoring the `kind` filter | Narrow results with kind=Function, kind=Class etc. to reduce noise |
 | Re-searching to get more context | Use the symbol `id` with `get_symbol_context` instead of re-searching |
+| Reading the whole file after a hit | First call `get_symbol_context` for callers/callees. If you still need source, do a bounded `Read(file, offset=start_line, limit=N)` — never whole-file. `get_source_window` is fine if your harness has no bounded read. |
+| Going straight from `find_code` to source read | Memtrace's value is the graph. Default next step is `get_symbol_context` or `get_impact`, not source. |
+| Treating 0 results as permission to grep | 0 results means broaden the Memtrace query, check repo_id/path filters, then reindex if coverage is missing |
+| Assuming a UI subdirectory is unindexed because stats show backend files | If `ui/`, `memtrace-ui/`, or another source directory is under the indexed repo root, diagnose/reindex with Memtrace instead of searching files manually |

package/installer/skills/workflows/memtrace-first.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-first
-description: "Always use first for indexed source-code repos before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed; only use file tools for configs, infra, docs, non-source artifacts, or exact paths already returned by Memtrace."
+description: "Always use first for indexed source-code repos before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results, missing languages, or partial-looking stats are not permission to grep; diagnose/reindex with Memtrace."
 ---
 
 # Memtrace First
@@ -28,11 +28,32 @@ Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_
 
 The semantic side means **string literals, error messages, magic constants, log strings, and any text inside an indexed symbol's body are findable through `find_code`**. The body got embedded; the embedding catches it. You do NOT need `Grep` to hunt for `STRIPE_KEY_FOO_BAR` if it lives inside a function in your indexed codebase.
 
+## Zero results are not a grep license
+
+If Memtrace returns 0 results, or repository stats look incomplete, do **not**
+infer that a source subdirectory is outside the index. Diagnose through
+Memtrace:
+
+1. Call `list_indexed_repositories` and identify the repo root/repo_id.
+2. If the path is under that indexed repo root, keep using Memtrace.
+3. Retry with broader `find_code` terms and, when available, `file_path` filters
+   such as `ui/`, `memtrace-ui/`, `src/`, or the framework directory.
+4. If the language/path still appears missing, run `index_directory` on the repo
+   root with `incremental: true` (or ask before `clear_existing: true`).
+5. Report the indexing coverage problem instead of silently switching to grep.
+
+**Never say "the index only covers X, so grep is right" when the target path is
+inside the indexed repository.** That is an indexing freshness/coverage issue,
+not permission to abandon Memtrace.
+
 ## The narrow exceptions where grep/glob are still right
 
 These are the ONLY cases where file tools beat memtrace:
 
-- **Files outside the indexed repo.** Vendored deps, system headers, dirs `walker::is_excluded_path` skipped (`.git`, `node_modules`, `target`, `dist`). Memtrace literally cannot see them.
+- **Files outside every indexed repo root.** Confirm this with
+  `list_indexed_repositories`; 0 search results or missing language stats do not
+  prove it. Vendored deps, system headers, and excluded dirs
+  (`.git`, `node_modules`, `target`, `dist`) are examples Memtrace cannot see.
 - **Non-source artifacts.** `.env`, `package.json`, build scripts, top-level `README.md`, raw config files. Memtrace indexes parseable code, not configuration text.
 - **Pure file-inventory questions.** "How many `*.test.ts` files exist", "list every Markdown file in `docs/`". You're asking for a file count, not a symbol search.
 - **Reading at a known path.** Once memtrace has handed you `file_path:start_line:end_line`, use `Read` — never substitute `Grep` for `Read`.
@@ -132,6 +153,8 @@ You are violating this skill if you think:
 | "Let me read the whole file" | `get_symbol_context` gives you only what matters |
 | "It's just a quick search" | Grep has no understanding of call graphs, communities, or time |
 | "I don't know if it's indexed" | Check with `list_indexed_repositories` first — takes 1 second |
+| "Memtrace returned 0 results" | Broaden the Memtrace query, check repo_id/path coverage, then reindex if needed |
+| "Stats only show Rust, but I need `ui/` or `memtrace-ui/`" | That is a coverage diagnostic. Reindex the repo root; do not grep source code. |
 | "The user didn't say to use Memtrace" | User asked about the code. Repo is indexed. Use Memtrace. |
 | "This is a simple question" | Simple questions benefit most — one `find_symbol` vs 20 file reads |
 
@@ -140,7 +163,7 @@ You are violating this skill if you think:
 Use Grep/Glob/Read ONLY for:
 - Reading the **exact source lines** of a symbol you already located via Memtrace
 - Files that are config, data, or docs (not source code symbols)
-- Repos confirmed NOT indexed in Memtrace
+- Repos or paths confirmed outside every Memtrace indexed root
 
 Never use file tools as a **discovery** mechanism when Memtrace is available.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.3.27",
+  "version": "0.3.30",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -37,9 +37,9 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.3.26",
-    "@memtrace/linux-x64": "0.3.26",
-    "@memtrace/win32-x64": "0.3.26"
+    "@memtrace/darwin-arm64": "0.3.30",
+    "@memtrace/linux-x64": "0.3.30",
+    "@memtrace/win32-x64": "0.3.30"
   },
   "engines": {
     "node": ">=18"

package/skills/commands/memtrace-index.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-index
-description: "Always use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, or when code exploration is needed but no Memtrace index exists. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed."
+description: "Always use when the user asks to index, parse, ingest, reindex, watch, or prepare a source-code repo for Memtrace analysis, when code exploration needs an index, or when searches return 0/partial results for source paths under an indexed root. Use this before Grep, Glob, rg, find, or manual code search whenever the repo can be indexed."
 allowed-tools:
   - mcp__memtrace__index_directory
   - mcp__memtrace__check_job_status
@@ -32,6 +32,11 @@ Use the `list_indexed_repositories` MCP tool first. If the repo is already index
 
 **Success criteria:** You have a list of repo_ids and their last-indexed timestamps.
 
+If a repo is present but searches miss a source subdirectory under that repo
+root (for example `ui/`, `memtrace-ui/`, `web/`, `frontend/`, or `src/`), treat
+that as a stale/partial index. Do not use grep as a workaround. Run incremental
+indexing on the repo root, then retry the Memtrace query.
+
 ### 2. Index the directory
 
 Use the `index_directory` MCP tool:

package/skills/commands/memtrace-search.md

@@ -1,11 +1,6 @@
 ---
 name: memtrace-search
-description: "Always use to find, search, locate, or look up source-code symbols, functions, classes, types, constants, definitions, implementations, logic, error strings inside code, or where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery; Memtrace uses BM25, vector search, RRF, and the AST graph."
-allowed-tools:
-  - mcp__memtrace__find_code
-  - mcp__memtrace__find_symbol
-  - mcp__memtrace__list_indexed_repositories
-user-invocable: true
+description: "Always use to find, search, locate, or look up source-code symbols, functions, classes, types, constants, definitions, implementations, logic, error strings inside code, or where code lives. Do not use Grep, Glob, rg, find, or manual file search for code discovery. If Memtrace returns 0 results, broaden the Memtrace query and diagnose/reindex; do not switch to grep."
 ---
 
 ## Overview
@@ -18,6 +13,7 @@ Find code using hybrid BM25 full-text + semantic vector search with Reciprocal R
 |------|----------|
 | `find_code` | Natural-language queries ("authentication middleware", "retry logic"), broad searches |
 | `find_symbol` | Exact identifier names ("getUserById", "PaymentService"), when you know the name |
+| `get_source_window` | Optional: bounded source read after a Memtrace hit, when your harness lacks `Read(file, offset, limit)`. Otherwise prefer your harness's bounded read with the returned `start_line` / `end_line`. |
 
 ## Steps
 
@@ -52,11 +48,37 @@ Find code using hybrid BM25 full-text + semantic vector search with Reciprocal R
 
 ### 3. Use results for next steps
 
+The default next step is a **graph tool** — `get_symbol_context`,
+`analyze_relationships`, or `get_impact`. Those answer "who calls this",
+"what's the blast radius", "what community is it part of" — context no
+file read can give. That's what Memtrace uniquely provides.
+
+Source bytes come last, only when you're about to edit or quote. Use a
+bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`,
+or `get_source_window` if your harness lacks bounded reads. Do not whole-file.
+
 Save the symbol `id` from results — pass it to:
 - `analyze_relationships` to map callers/callees
 - `get_symbol_context` for a 360-degree view
 - `get_impact` to assess blast radius before changes
 
+### Multi-word natural-language queries
+
+When your query is 3+ words and feels descriptive (e.g. "validate auth token", "find HTTP server error"), don't stop at the first `find_code` call:
+
+1. First try the verbatim query.
+2. If results look generic or the right doc isn't at rank 1, fan out **in parallel** with up to 3 identifier-shaped reshapes:
+   - camelCase: "validate auth token" → `validateAuthToken`
+   - snake_case: → `validate_auth_token`
+   - Domain-likely identifiers: → `auth_token`, `tokenValidator`, `verifyToken`
+3. Memtrace's tokenizer splits camelCase / snake / kebab at index time, so reshaped queries hit identifier names directly.
+4. Take the union of top-5 from each call, dedupe by `file_path:start_line`.
+
+**Worked examples** (verbatim → reshapes to try in parallel):
+- "validate auth token" → `validateAuthToken`, `validate_auth_token`, `verifyToken`
+- "find http server error" → `findHttpServerError`, `http_error`, `serverError`
+- "render value panel" → `renderValuePanel`, `ValuePanel`, `value_panel`
+
 ## Common Mistakes
 
 | Mistake | Reality |
@@ -65,3 +87,7 @@ Save the symbol `id` from results — pass it to:
 | Using find_symbol for vague queries | Use `find_code` for natural-language; `find_symbol` is for exact names |
 | Ignoring the `kind` filter | Narrow results with kind=Function, kind=Class etc. to reduce noise |
 | Re-searching to get more context | Use the symbol `id` with `get_symbol_context` instead of re-searching |
+| Reading the whole file after a hit | First call `get_symbol_context` for callers/callees. If you still need source, do a bounded `Read(file, offset=start_line, limit=N)` — never whole-file. `get_source_window` is fine if your harness has no bounded read. |
+| Going straight from `find_code` to source read | Memtrace's value is the graph. Default next step is `get_symbol_context` or `get_impact`, not source. |
+| Treating 0 results as permission to grep | 0 results means broaden the Memtrace query, check repo_id/path filters, then reindex if coverage is missing |
+| Assuming a UI subdirectory is unindexed because stats show backend files | If `ui/`, `memtrace-ui/`, or another source directory is under the indexed repo root, diagnose/reindex with Memtrace instead of searching files manually |

package/skills/workflows/memtrace-first.md

@@ -1,6 +1,6 @@
 ---
 name: memtrace-first
-description: "Always use first for indexed source-code repos before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed; only use file tools for configs, infra, docs, non-source artifacts, or exact paths already returned by Memtrace."
+description: "Always use first for indexed source-code repos before searching files, reading code for discovery, debugging, tracing flows, finding implementations, understanding behavior, or answering how code works. Do not use Grep, Glob, rg, find, or manual file browsing for code discovery when Memtrace is indexed. Zero results, missing languages, or partial-looking stats are not permission to grep; diagnose/reindex with Memtrace."
 ---
 
 # Memtrace First
@@ -9,12 +9,15 @@ description: "Always use first for indexed source-code repos before searching fi
 
 ```
 IF THE REPO IS INDEXED IN MEMTRACE → USE MEMTRACE TOOLS FIRST.
-Memtrace returns exact file_path + start_line + end_line for every result.
-Read the file at THAT location. Do not Grep/Glob/Find to "locate" anything
-already in the graph.
+After a search hit, route to GRAPH tools (get_symbol_context, get_impact,
+analyze_relationships) — that's what Memtrace uniquely provides. Read source
+ONLY when you're about to edit or quote, and read only the bounded span
+returned by Memtrace (start_line .. end_line + small context). Do not
+Grep/Glob/Find to "locate" anything already in the graph, and do not read
+the whole file when Memtrace has given you exact lines.
 ```
 
-Memtrace is the memory layer of the codebase. It has the full knowledge graph: every symbol, call, import, community, process, and API — with time dimension. File tools are blind to this structure.
+Memtrace is the **memory layer** of the codebase, not a search engine that returns code. It has the full knowledge graph — every symbol, call, import, community, process, and API — with a time dimension. The point is to navigate that graph: who calls this, what's the blast radius, when did this change, what community is it part of. File tools are blind to all of that.
 
 **97% better accuracy. 83% fewer wasted tokens. No exceptions for what's in the graph.**
 
@@ -28,14 +31,35 @@ Memtrace's hybrid search = **BM25 over symbol metadata** (name, signature, file_
 
 The semantic side means **string literals, error messages, magic constants, log strings, and any text inside an indexed symbol's body are findable through `find_code`**. The body got embedded; the embedding catches it. You do NOT need `Grep` to hunt for `STRIPE_KEY_FOO_BAR` if it lives inside a function in your indexed codebase.
 
+## Zero results are not a grep license
+
+If Memtrace returns 0 results, or repository stats look incomplete, do **not**
+infer that a source subdirectory is outside the index. Diagnose through
+Memtrace:
+
+1. Call `list_indexed_repositories` and identify the repo root/repo_id.
+2. If the path is under that indexed repo root, keep using Memtrace.
+3. Retry with broader `find_code` terms and, when available, `file_path` filters
+   such as `ui/`, `memtrace-ui/`, `src/`, or the framework directory.
+4. If the language/path still appears missing, run `index_directory` on the repo
+   root with `incremental: true` (or ask before `clear_existing: true`).
+5. Report the indexing coverage problem instead of silently switching to grep.
+
+**Never say "the index only covers X, so grep is right" when the target path is
+inside the indexed repository.** That is an indexing freshness/coverage issue,
+not permission to abandon Memtrace.
+
 ## The narrow exceptions where grep/glob are still right
 
 These are the ONLY cases where file tools beat memtrace:
 
-- **Files outside the indexed repo.** Vendored deps, system headers, dirs `walker::is_excluded_path` skipped (`.git`, `node_modules`, `target`, `dist`). Memtrace literally cannot see them.
+- **Files outside every indexed repo root.** Confirm this with
+  `list_indexed_repositories`; 0 search results or missing language stats do not
+  prove it. Vendored deps, system headers, and excluded dirs
+  (`.git`, `node_modules`, `target`, `dist`) are examples Memtrace cannot see.
 - **Non-source artifacts.** `.env`, `package.json`, build scripts, top-level `README.md`, raw config files. Memtrace indexes parseable code, not configuration text.
 - **Pure file-inventory questions.** "How many `*.test.ts` files exist", "list every Markdown file in `docs/`". You're asking for a file count, not a symbol search.
-- **Reading at a known path.** Once memtrace has handed you `file_path:start_line:end_line`, use `Read` — never substitute `Grep` for `Read`.
+- **Reading at a known path outside Memtrace.** For configs, docs, or non-source artifacts that Memtrace cannot index, file `Read` is fine. For source-code spans returned by Memtrace, read the precise line range (your harness's `Read` with offset/limit, or `get_source_window` if your harness lacks bounded reads). Do not whole-file Read when you have a span.
 
 For everything else inside the indexed repo, memtrace is the right tool.
 
@@ -43,16 +67,18 @@ For everything else inside the indexed repo, memtrace is the right tool.
 
 | Question Claude is asking | Right tool |
 |---|---|
-| "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → file:line. Then `Read` that range. |
+| "Where is symbol `foo` defined?" | `find_symbol(name="foo")` → then `get_symbol_context` for callers/callees/community, NOT a source read unless you're editing. |
 | "What calls `foo`?" | `get_symbol_context(name="foo")` → callers with file:line each. |
-| "How does authentication work?" | `find_code(query="authentication")` → ranked symbols with file:line. |
+| "How does authentication work?" | `find_code(query="authentication")` → `get_symbol_context` on the top hit, NOT a source read. |
+| "Find behavior X" with multi-word phrase (3+ words) | `find_code(verbatim)` first; if low confidence, fan out with identifier-shaped reshapes (camelCase / snake_case). |
 | "Find the function that uses `STRIPE_KEY_FOO_BAR`" | `find_code(query="STRIPE_KEY_FOO_BAR")` → semantic finds it inside any embedded body. |
 | "Where's that error message `'connection refused for tenant'`?" | `find_code(query="connection refused for tenant")` → semantic catches it. |
 | "What breaks if I change `foo`?" | `get_impact(name="foo")` → blast radius with file:line. |
 | "What changed in `auth.ts` last week?" | `get_evolution(file_path="auth.ts", from="7d ago")`. |
 | "List all `*.test.ts` files." | `Glob` (file inventory, not symbol search). |
 | "Find this string in my `.env`." | `Grep` (non-source artifact). |
-| "Read file I already have the path of." | `Read` (path is known). |
+| "I'm about to edit `foo` — show me its source." | Bounded `Read(file_path, offset=start_line, limit=end_line-start_line+8)`, or `get_source_window` if your harness lacks bounded reads. Never whole-file. |
+| "Read config/doc file I already have the path of." | `Read` (non-source artifact, path is known). |
 
 ## Parameter Types — Read This Before Calling Any Tool
 
@@ -80,7 +106,7 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 | What you need | Use instead of Grep/Glob/Read |
 |---|---|
 | Find a function / class / symbol | `find_symbol` or `find_code` |
-| Understand how something works | `get_symbol_context` |
+| Understand how something works | `get_symbol_context` (the default next step) |
 | Find all callers of a function | `get_symbol_context` (callers field) |
 | Find all callees / dependencies | `get_symbol_context` (callees field) |
 | Trace a request / execution path | `get_process_flow` |
@@ -95,14 +121,15 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 | Dependency between two symbols | `find_dependency_path` |
 | What files change together? | `get_cochange_context` |
 | Architecture overview | `list_communities` + `find_central_symbols` |
+| About to edit / quote — need exact lines | Bounded `Read(file, offset=start_line, limit=N)` (preferred), or `get_source_window` for path-resolution parity |
 
 ## Standard Workflows
 
 ### "How does X work?" / "Explain X"
 1. `find_symbol` or `find_code` → locate the symbol
-2. `get_symbol_context` → callers, callees, community, processes
+2. `get_symbol_context` → callers, callees, community, processes (this usually answers "how it works")
 3. `get_process_flow` (if it's a process/request path)
-4. Read source ONLY for the exact lines you need to quote
+4. Only if you need to quote source: bounded `Read` at start_line..end_line, or `get_source_window`
 
 ### Debugging "X is broken"
 1. `find_symbol` → locate the broken thing
@@ -114,7 +141,7 @@ If not indexed → offer to index with `mcp__memtrace__index_directory`, then fo
 ### "Where is X defined / called?"
 1. `find_symbol` with `fuzzy: true`
 2. `get_symbol_context` for full caller/callee map
-3. Read specific file only after locating exact line
+3. Only if you need source text: bounded `Read` at start_line..end_line, or `get_source_window`
 
 ### Before any code modification
 1. `find_symbol` → confirm you have the right target
@@ -129,18 +156,25 @@ You are violating this skill if you think:
 |---|---|
 | "Let me grep for this" | `find_code` or `find_symbol` is faster and structurally aware |
 | "Let me glob for the file" | `find_symbol` returns exact location with context |
-| "Let me read the whole file" | `get_symbol_context` gives you only what matters |
+| "Let me read the whole file" | `get_symbol_context` for the WHY (callers/callees/community); a bounded source read at start_line..end_line for the WHAT |
 | "It's just a quick search" | Grep has no understanding of call graphs, communities, or time |
 | "I don't know if it's indexed" | Check with `list_indexed_repositories` first — takes 1 second |
+| "Memtrace returned 0 results" | Broaden the Memtrace query, check repo_id/path coverage, then reindex if needed |
+| "Stats only show Rust, but I need `ui/` or `memtrace-ui/`" | That is a coverage diagnostic. Reindex the repo root; do not grep source code. |
 | "The user didn't say to use Memtrace" | User asked about the code. Repo is indexed. Use Memtrace. |
 | "This is a simple question" | Simple questions benefit most — one `find_symbol` vs 20 file reads |
 
 ## When File Tools Are Still Correct
 
 Use Grep/Glob/Read ONLY for:
-- Reading the **exact source lines** of a symbol you already located via Memtrace
+- Non-source files or paths outside every indexed source repo
 - Files that are config, data, or docs (not source code symbols)
-- Repos confirmed NOT indexed in Memtrace
+- Repos or paths confirmed outside every Memtrace indexed root
+
+For source-code spans already located by Memtrace, use a **bounded** read —
+your harness's `Read(file, offset, limit)` with the returned `start_line` /
+`end_line`, or `get_source_window` if your harness lacks bounded reads. Do
+not read the whole file.
 
 Never use file tools as a **discovery** mechanism when Memtrace is available.