From 1b2c8e9109385480fb48fa192554886e834fea7f Mon Sep 17 00:00:00 2001
From: denfry <dabinayo@pm.me>
Date: Thu, 24 Sep 2026 21:54:00 +0300
Subject: [PATCH 1/2] feat: exact refs/impact, compact agent output and
 measured ranking signals

refs, impact, symbol and describe accept Owner.member / module::fn targets.
Call edges now store their receiver (index schema 4), so a call written
against a type or module resolves across files, and resolution no longer
invents edges across languages or onto another type's only member. An
Owner.member query that meets calls it cannot type lists them as
possible_call and reports coverage as partial instead of a confident empty
answer.

Agent-facing output: search/explain/refs/impact --compact print ranked
locations with numbered matching lines, refs sites carry the calling
function and a total, refs gains --exclude-tests/--path, impact reports the
build module and the build files that depend on it, describe lists a
class's members and who uses them, and symbol returns exact matches alone.

Parsing: Kotlin call edges, Rust enum-variant symbols and match-pattern
references, Java/C# enum constants. update parses changed files in a
process pool like a full build.

Ranking: resource_priors, stem_match and question_pool_floor, and a class
is returned instead of its same-named constructor. Over 342 queries:
MRR +0.010 (p=0.031), recall@10 +0.019, nDCG@10 +0.011, useful@budget
+0.022, no corpus regressing.
---
 .claude/skills/codebase-index/SKILL.md        | 148 +++-----
 .../codebase-index/references/commands.md     |  18 +
 .codex/skills/codebase-index/SKILL.md         | 148 +++-----
 .../codebase-index/references/commands.md     |  18 +
 .opencode/skills/codebase-index/SKILL.md      | 148 +++-----
 .../codebase-index/references/commands.md     |  18 +
 skill/SKILL.md                                | 148 +++-----
 skill/references/commands.md                  |  18 +
 skills/codebase-index/SKILL.md                | 148 +++-----
 skills/codebase-index/references/commands.md  |  18 +
 src/codebase_index/cli.py                     |  75 +++-
 src/codebase_index/graph/builder.py           | 105 +++++-
 src/codebase_index/graph/expand.py            |  26 +-
 src/codebase_index/graph/modules.py           | 112 ++++++
 src/codebase_index/graph/navigate.py          |  68 +++-
 src/codebase_index/indexer/pipeline.py        |  31 +-
 src/codebase_index/mcp/server.py              |  14 +-
 src/codebase_index/models.py                  |  31 ++
 src/codebase_index/output/markdown.py         | 122 ++++++-
 src/codebase_index/parsers/base.py            |  27 ++
 src/codebase_index/parsers/treesitter.py      | 106 +++++-
 src/codebase_index/retrieval/intent.py        |  18 +
 src/codebase_index/retrieval/pipeline.py      |  89 ++++-
 src/codebase_index/retrieval/priors.py        |  37 +-
 src/codebase_index/retrieval/rerank.py        |  12 +-
 src/codebase_index/retrieval/searchers.py     | 176 ++++++++--
 src/codebase_index/retrieval/tuning.py        |  48 ++-
 src/codebase_index/service.py                 |   2 +
 src/codebase_index/skill_template/SKILL.md    | 148 +++-----
 .../skill_template/references/commands.md     |  18 +
 src/codebase_index/storage/db.py              |   3 +-
 src/codebase_index/storage/repo.py            | 114 ++++++-
 src/codebase_index/storage/schema.sql         |   5 +-
 tests/eval/run_eval.py                        |   2 +
 tests/golden/describe_refresh.json            |   8 +-
 tests/golden/impact_user_model.json           |   1 +
 tests/golden/mcp_describe_symbol.json         |   8 +-
 tests/golden/mcp_find_refs.json               |  15 +-
 tests/golden/mcp_find_symbol.json             |   1 +
 tests/golden/mcp_impact_of.json               |   1 +
 tests/golden/mcp_search_code.json             |   4 +-
 tests/golden/refs_refresh_access_token.json   |  15 +-
 tests/golden/search_token.json                |   4 +-
 tests/golden/symbol_user.json                 |   1 +
 tests/test_agent_ergonomics.py                | 227 +++++++++++++
 tests/test_compact_output.py                  | 114 +++++++
 tests/test_migration_1x.py                    |  19 +-
 tests/test_priors.py                          |  28 ++
 tests/test_qualified_refs.py                  | 320 ++++++++++++++++++
 49 files changed, 2295 insertions(+), 690 deletions(-)
 create mode 100644 src/codebase_index/graph/modules.py
 create mode 100644 tests/test_agent_ergonomics.py
 create mode 100644 tests/test_compact_output.py
 create mode 100644 tests/test_qualified_refs.py

diff --git a/.claude/skills/codebase-index/SKILL.md b/.claude/skills/codebase-index/SKILL.md
index 432005b..ba39234 100644
--- a/.claude/skills/codebase-index/SKILL.md
+++ b/.claude/skills/codebase-index/SKILL.md
@@ -6,106 +6,60 @@ allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Ba
 
 # Codebase Index
 
-Use the local index before reading repository files.
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
 
-The operating principle is **Find → Trace → Verify → Predict**:
-
-- **Find** the implementation with ranked retrieval.
-- **Trace** behavior through definitions, callers, dependencies, and paths.
-- **Verify** that evidence you already hold is still true before relying on it.
-- **Predict** change impact while preserving an explicit evidence trail.
-
-## Route the question
+## Route the question — always `--compact`
 
 | Intent | Command |
 |---|---|
-| Where is X implemented? | `codebase-index search "X" --session <tag> --json` |
-| How does X work? | `codebase-index explain "X" --session <tag> --json` |
-| What is this codebase? | `codebase-index architecture --json` |
-| Find a named symbol | `codebase-index symbol "X" --json` |
-| Who calls or references X? | `codebase-index refs "X" --json` |
-| What changes if X changes? | `codebase-index impact "X" --json` |
-| What does my current diff affect? | `codebase-index diff-impact --json` |
-| How are X and Y connected? | `codebase-index path "X" "Y" --json` |
-| Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
 | Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
-| Produce a human graph | `codebase-index graph "X" --output <path>` |
-
-Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
-error messages, and the default `hybrid` mode for mixed questions. Use pure
-`vector` mode only when embeddings are enabled and exact vocabulary is unknown.
-
-Read [references/commands.md](references/commands.md) only when command options
-or routing remain unclear.
-
-## Evidence protocol
-
-1. Pick one session tag for this conversation (for example `auth-fix-1`) and
-   pass `--session <tag>` to every `search` and `explain`.
-2. Run the best-matching command with `--json`.
-3. Check `index` before trusting the payload:
-   - missing → run `codebase-index index`, then repeat;
-   - stale with fewer than 20 changed files → run `codebase-index update`;
-   - stale with 20 or more changed files → run `codebase-index index`;
-   - fresh → continue.
-4. Start with ranks 1–3. Read only `recommended_reads` line ranges.
-5. Trace one additional hop only when the question requires behavior,
-   ownership, or impact.
-6. Before answering or editing from evidence gathered earlier in the task, run
-   `codebase-index verify --session <tag> --json` and reread anything whose
-   state is not `valid` or `relocated`.
-7. Answer with `file:line` evidence and state uncertainty explicitly.
-
-Do not open whole files when a line range is available. A snippet may already
-be sufficient. `skeletonized: true` means the response intentionally folded
-unrelated body lines; read the supplied range when the missing body matters.
-
-## Evidence memory
-
-- `reused: true` with `snippet: null` — this session already received that
-  exact text and its source is unchanged. Use your earlier copy; if you can no
-  longer see it, Read the range.
-- `memory.invalidated` — evidence this session received has changed since.
-  Treat your earlier copy as wrong and reread before relying on it.
-- `stale: true` — the index is older than the file. Run `codebase-index update`
-  or Read the range.
-- A tag belongs to one context. Never give it to a subagent or another
-  conversation. Start a new tag after the context is cleared or compacted, or
-  whenever earlier snippets are no longer visible to you.
-
-Verdict states and citing evidence in notes: [references/memory.md](references/memory.md).
-
-## Confidence contract
-
-- **high** — answer from the indexed evidence.
-- **medium** — read the recommended ranges and confirm the key claim with one
-  targeted lookup if necessary.
-- **low** or no results — follow `fallback_suggestions`, then use a narrow
-  Grep/Glob fallback.
-
-On `refs` and `impact`, inspect `coverage`. If `coverage.partial` is true, an
-empty result is inconclusive; confirm with targeted Grep before saying that
-nothing references the target.
-
-Edges carry `confidence`:
-
-- `extracted` — exact parser evidence;
-- `inferred` — heuristic resolution;
-- `ambiguous` — unresolved or non-unique.
-
-Never present an inferred or ambiguous chain as certain.
-
-## Answer contract
-
-Structure repository answers around:
-
-1. **Answer** — the direct conclusion.
-2. **Evidence** — the minimum supporting `file:line` references.
-3. **Confidence** — only when evidence is partial, inferred, stale, or missing.
-4. **Next check** — only when another check would materially reduce uncertainty.
-
-Do not narrate every search step. Do not claim absence from a partial graph.
-Do not replace evidence with a generated HTML graph.
 
-For payload fields and failure handling, read
-[references/response-contract.md](references/response-contract.md).
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).
diff --git a/.claude/skills/codebase-index/references/commands.md b/.claude/skills/codebase-index/references/commands.md
index 79c91a6..197ffe7 100644
--- a/.claude/skills/codebase-index/references/commands.md
+++ b/.claude/skills/codebase-index/references/commands.md
@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.
diff --git a/.codex/skills/codebase-index/SKILL.md b/.codex/skills/codebase-index/SKILL.md
index 432005b..ba39234 100644
--- a/.codex/skills/codebase-index/SKILL.md
+++ b/.codex/skills/codebase-index/SKILL.md
@@ -6,106 +6,60 @@ allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Ba
 
 # Codebase Index
 
-Use the local index before reading repository files.
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
 
-The operating principle is **Find → Trace → Verify → Predict**:
-
-- **Find** the implementation with ranked retrieval.
-- **Trace** behavior through definitions, callers, dependencies, and paths.
-- **Verify** that evidence you already hold is still true before relying on it.
-- **Predict** change impact while preserving an explicit evidence trail.
-
-## Route the question
+## Route the question — always `--compact`
 
 | Intent | Command |
 |---|---|
-| Where is X implemented? | `codebase-index search "X" --session <tag> --json` |
-| How does X work? | `codebase-index explain "X" --session <tag> --json` |
-| What is this codebase? | `codebase-index architecture --json` |
-| Find a named symbol | `codebase-index symbol "X" --json` |
-| Who calls or references X? | `codebase-index refs "X" --json` |
-| What changes if X changes? | `codebase-index impact "X" --json` |
-| What does my current diff affect? | `codebase-index diff-impact --json` |
-| How are X and Y connected? | `codebase-index path "X" "Y" --json` |
-| Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
 | Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
-| Produce a human graph | `codebase-index graph "X" --output <path>` |
-
-Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
-error messages, and the default `hybrid` mode for mixed questions. Use pure
-`vector` mode only when embeddings are enabled and exact vocabulary is unknown.
-
-Read [references/commands.md](references/commands.md) only when command options
-or routing remain unclear.
-
-## Evidence protocol
-
-1. Pick one session tag for this conversation (for example `auth-fix-1`) and
-   pass `--session <tag>` to every `search` and `explain`.
-2. Run the best-matching command with `--json`.
-3. Check `index` before trusting the payload:
-   - missing → run `codebase-index index`, then repeat;
-   - stale with fewer than 20 changed files → run `codebase-index update`;
-   - stale with 20 or more changed files → run `codebase-index index`;
-   - fresh → continue.
-4. Start with ranks 1–3. Read only `recommended_reads` line ranges.
-5. Trace one additional hop only when the question requires behavior,
-   ownership, or impact.
-6. Before answering or editing from evidence gathered earlier in the task, run
-   `codebase-index verify --session <tag> --json` and reread anything whose
-   state is not `valid` or `relocated`.
-7. Answer with `file:line` evidence and state uncertainty explicitly.
-
-Do not open whole files when a line range is available. A snippet may already
-be sufficient. `skeletonized: true` means the response intentionally folded
-unrelated body lines; read the supplied range when the missing body matters.
-
-## Evidence memory
-
-- `reused: true` with `snippet: null` — this session already received that
-  exact text and its source is unchanged. Use your earlier copy; if you can no
-  longer see it, Read the range.
-- `memory.invalidated` — evidence this session received has changed since.
-  Treat your earlier copy as wrong and reread before relying on it.
-- `stale: true` — the index is older than the file. Run `codebase-index update`
-  or Read the range.
-- A tag belongs to one context. Never give it to a subagent or another
-  conversation. Start a new tag after the context is cleared or compacted, or
-  whenever earlier snippets are no longer visible to you.
-
-Verdict states and citing evidence in notes: [references/memory.md](references/memory.md).
-
-## Confidence contract
-
-- **high** — answer from the indexed evidence.
-- **medium** — read the recommended ranges and confirm the key claim with one
-  targeted lookup if necessary.
-- **low** or no results — follow `fallback_suggestions`, then use a narrow
-  Grep/Glob fallback.
-
-On `refs` and `impact`, inspect `coverage`. If `coverage.partial` is true, an
-empty result is inconclusive; confirm with targeted Grep before saying that
-nothing references the target.
-
-Edges carry `confidence`:
-
-- `extracted` — exact parser evidence;
-- `inferred` — heuristic resolution;
-- `ambiguous` — unresolved or non-unique.
-
-Never present an inferred or ambiguous chain as certain.
-
-## Answer contract
-
-Structure repository answers around:
-
-1. **Answer** — the direct conclusion.
-2. **Evidence** — the minimum supporting `file:line` references.
-3. **Confidence** — only when evidence is partial, inferred, stale, or missing.
-4. **Next check** — only when another check would materially reduce uncertainty.
-
-Do not narrate every search step. Do not claim absence from a partial graph.
-Do not replace evidence with a generated HTML graph.
 
-For payload fields and failure handling, read
-[references/response-contract.md](references/response-contract.md).
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).
diff --git a/.codex/skills/codebase-index/references/commands.md b/.codex/skills/codebase-index/references/commands.md
index 79c91a6..197ffe7 100644
--- a/.codex/skills/codebase-index/references/commands.md
+++ b/.codex/skills/codebase-index/references/commands.md
@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.
diff --git a/.opencode/skills/codebase-index/SKILL.md b/.opencode/skills/codebase-index/SKILL.md
index 432005b..ba39234 100644
--- a/.opencode/skills/codebase-index/SKILL.md
+++ b/.opencode/skills/codebase-index/SKILL.md
@@ -6,106 +6,60 @@ allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Ba
 
 # Codebase Index
 
-Use the local index before reading repository files.
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
 
-The operating principle is **Find → Trace → Verify → Predict**:
-
-- **Find** the implementation with ranked retrieval.
-- **Trace** behavior through definitions, callers, dependencies, and paths.
-- **Verify** that evidence you already hold is still true before relying on it.
-- **Predict** change impact while preserving an explicit evidence trail.
-
-## Route the question
+## Route the question — always `--compact`
 
 | Intent | Command |
 |---|---|
-| Where is X implemented? | `codebase-index search "X" --session <tag> --json` |
-| How does X work? | `codebase-index explain "X" --session <tag> --json` |
-| What is this codebase? | `codebase-index architecture --json` |
-| Find a named symbol | `codebase-index symbol "X" --json` |
-| Who calls or references X? | `codebase-index refs "X" --json` |
-| What changes if X changes? | `codebase-index impact "X" --json` |
-| What does my current diff affect? | `codebase-index diff-impact --json` |
-| How are X and Y connected? | `codebase-index path "X" "Y" --json` |
-| Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
 | Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
-| Produce a human graph | `codebase-index graph "X" --output <path>` |
-
-Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
-error messages, and the default `hybrid` mode for mixed questions. Use pure
-`vector` mode only when embeddings are enabled and exact vocabulary is unknown.
-
-Read [references/commands.md](references/commands.md) only when command options
-or routing remain unclear.
-
-## Evidence protocol
-
-1. Pick one session tag for this conversation (for example `auth-fix-1`) and
-   pass `--session <tag>` to every `search` and `explain`.
-2. Run the best-matching command with `--json`.
-3. Check `index` before trusting the payload:
-   - missing → run `codebase-index index`, then repeat;
-   - stale with fewer than 20 changed files → run `codebase-index update`;
-   - stale with 20 or more changed files → run `codebase-index index`;
-   - fresh → continue.
-4. Start with ranks 1–3. Read only `recommended_reads` line ranges.
-5. Trace one additional hop only when the question requires behavior,
-   ownership, or impact.
-6. Before answering or editing from evidence gathered earlier in the task, run
-   `codebase-index verify --session <tag> --json` and reread anything whose
-   state is not `valid` or `relocated`.
-7. Answer with `file:line` evidence and state uncertainty explicitly.
-
-Do not open whole files when a line range is available. A snippet may already
-be sufficient. `skeletonized: true` means the response intentionally folded
-unrelated body lines; read the supplied range when the missing body matters.
-
-## Evidence memory
-
-- `reused: true` with `snippet: null` — this session already received that
-  exact text and its source is unchanged. Use your earlier copy; if you can no
-  longer see it, Read the range.
-- `memory.invalidated` — evidence this session received has changed since.
-  Treat your earlier copy as wrong and reread before relying on it.
-- `stale: true` — the index is older than the file. Run `codebase-index update`
-  or Read the range.
-- A tag belongs to one context. Never give it to a subagent or another
-  conversation. Start a new tag after the context is cleared or compacted, or
-  whenever earlier snippets are no longer visible to you.
-
-Verdict states and citing evidence in notes: [references/memory.md](references/memory.md).
-
-## Confidence contract
-
-- **high** — answer from the indexed evidence.
-- **medium** — read the recommended ranges and confirm the key claim with one
-  targeted lookup if necessary.
-- **low** or no results — follow `fallback_suggestions`, then use a narrow
-  Grep/Glob fallback.
-
-On `refs` and `impact`, inspect `coverage`. If `coverage.partial` is true, an
-empty result is inconclusive; confirm with targeted Grep before saying that
-nothing references the target.
-
-Edges carry `confidence`:
-
-- `extracted` — exact parser evidence;
-- `inferred` — heuristic resolution;
-- `ambiguous` — unresolved or non-unique.
-
-Never present an inferred or ambiguous chain as certain.
-
-## Answer contract
-
-Structure repository answers around:
-
-1. **Answer** — the direct conclusion.
-2. **Evidence** — the minimum supporting `file:line` references.
-3. **Confidence** — only when evidence is partial, inferred, stale, or missing.
-4. **Next check** — only when another check would materially reduce uncertainty.
-
-Do not narrate every search step. Do not claim absence from a partial graph.
-Do not replace evidence with a generated HTML graph.
 
-For payload fields and failure handling, read
-[references/response-contract.md](references/response-contract.md).
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).
diff --git a/.opencode/skills/codebase-index/references/commands.md b/.opencode/skills/codebase-index/references/commands.md
index 79c91a6..197ffe7 100644
--- a/.opencode/skills/codebase-index/references/commands.md
+++ b/.opencode/skills/codebase-index/references/commands.md
@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.
diff --git a/skill/SKILL.md b/skill/SKILL.md
index 432005b..ba39234 100644
--- a/skill/SKILL.md
+++ b/skill/SKILL.md
@@ -6,106 +6,60 @@ allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Ba
 
 # Codebase Index
 
-Use the local index before reading repository files.
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
 
-The operating principle is **Find → Trace → Verify → Predict**:
-
-- **Find** the implementation with ranked retrieval.
-- **Trace** behavior through definitions, callers, dependencies, and paths.
-- **Verify** that evidence you already hold is still true before relying on it.
-- **Predict** change impact while preserving an explicit evidence trail.
-
-## Route the question
+## Route the question — always `--compact`
 
 | Intent | Command |
 |---|---|
-| Where is X implemented? | `codebase-index search "X" --session <tag> --json` |
-| How does X work? | `codebase-index explain "X" --session <tag> --json` |
-| What is this codebase? | `codebase-index architecture --json` |
-| Find a named symbol | `codebase-index symbol "X" --json` |
-| Who calls or references X? | `codebase-index refs "X" --json` |
-| What changes if X changes? | `codebase-index impact "X" --json` |
-| What does my current diff affect? | `codebase-index diff-impact --json` |
-| How are X and Y connected? | `codebase-index path "X" "Y" --json` |
-| Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
 | Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
-| Produce a human graph | `codebase-index graph "X" --output <path>` |
-
-Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
-error messages, and the default `hybrid` mode for mixed questions. Use pure
-`vector` mode only when embeddings are enabled and exact vocabulary is unknown.
-
-Read [references/commands.md](references/commands.md) only when command options
-or routing remain unclear.
-
-## Evidence protocol
-
-1. Pick one session tag for this conversation (for example `auth-fix-1`) and
-   pass `--session <tag>` to every `search` and `explain`.
-2. Run the best-matching command with `--json`.
-3. Check `index` before trusting the payload:
-   - missing → run `codebase-index index`, then repeat;
-   - stale with fewer than 20 changed files → run `codebase-index update`;
-   - stale with 20 or more changed files → run `codebase-index index`;
-   - fresh → continue.
-4. Start with ranks 1–3. Read only `recommended_reads` line ranges.
-5. Trace one additional hop only when the question requires behavior,
-   ownership, or impact.
-6. Before answering or editing from evidence gathered earlier in the task, run
-   `codebase-index verify --session <tag> --json` and reread anything whose
-   state is not `valid` or `relocated`.
-7. Answer with `file:line` evidence and state uncertainty explicitly.
-
-Do not open whole files when a line range is available. A snippet may already
-be sufficient. `skeletonized: true` means the response intentionally folded
-unrelated body lines; read the supplied range when the missing body matters.
-
-## Evidence memory
-
-- `reused: true` with `snippet: null` — this session already received that
-  exact text and its source is unchanged. Use your earlier copy; if you can no
-  longer see it, Read the range.
-- `memory.invalidated` — evidence this session received has changed since.
-  Treat your earlier copy as wrong and reread before relying on it.
-- `stale: true` — the index is older than the file. Run `codebase-index update`
-  or Read the range.
-- A tag belongs to one context. Never give it to a subagent or another
-  conversation. Start a new tag after the context is cleared or compacted, or
-  whenever earlier snippets are no longer visible to you.
-
-Verdict states and citing evidence in notes: [references/memory.md](references/memory.md).
-
-## Confidence contract
-
-- **high** — answer from the indexed evidence.
-- **medium** — read the recommended ranges and confirm the key claim with one
-  targeted lookup if necessary.
-- **low** or no results — follow `fallback_suggestions`, then use a narrow
-  Grep/Glob fallback.
-
-On `refs` and `impact`, inspect `coverage`. If `coverage.partial` is true, an
-empty result is inconclusive; confirm with targeted Grep before saying that
-nothing references the target.
-
-Edges carry `confidence`:
-
-- `extracted` — exact parser evidence;
-- `inferred` — heuristic resolution;
-- `ambiguous` — unresolved or non-unique.
-
-Never present an inferred or ambiguous chain as certain.
-
-## Answer contract
-
-Structure repository answers around:
-
-1. **Answer** — the direct conclusion.
-2. **Evidence** — the minimum supporting `file:line` references.
-3. **Confidence** — only when evidence is partial, inferred, stale, or missing.
-4. **Next check** — only when another check would materially reduce uncertainty.
-
-Do not narrate every search step. Do not claim absence from a partial graph.
-Do not replace evidence with a generated HTML graph.
 
-For payload fields and failure handling, read
-[references/response-contract.md](references/response-contract.md).
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).
diff --git a/skill/references/commands.md b/skill/references/commands.md
index 79c91a6..197ffe7 100644
--- a/skill/references/commands.md
+++ b/skill/references/commands.md
@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.
diff --git a/skills/codebase-index/SKILL.md b/skills/codebase-index/SKILL.md
index 432005b..ba39234 100644
--- a/skills/codebase-index/SKILL.md
+++ b/skills/codebase-index/SKILL.md
@@ -6,106 +6,60 @@ allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Ba
 
 # Codebase Index
 
-Use the local index before reading repository files.
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
 
-The operating principle is **Find → Trace → Verify → Predict**:
-
-- **Find** the implementation with ranked retrieval.
-- **Trace** behavior through definitions, callers, dependencies, and paths.
-- **Verify** that evidence you already hold is still true before relying on it.
-- **Predict** change impact while preserving an explicit evidence trail.
-
-## Route the question
+## Route the question — always `--compact`
 
 | Intent | Command |
 |---|---|
-| Where is X implemented? | `codebase-index search "X" --session <tag> --json` |
-| How does X work? | `codebase-index explain "X" --session <tag> --json` |
-| What is this codebase? | `codebase-index architecture --json` |
-| Find a named symbol | `codebase-index symbol "X" --json` |
-| Who calls or references X? | `codebase-index refs "X" --json` |
-| What changes if X changes? | `codebase-index impact "X" --json` |
-| What does my current diff affect? | `codebase-index diff-impact --json` |
-| How are X and Y connected? | `codebase-index path "X" "Y" --json` |
-| Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
 | Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
-| Produce a human graph | `codebase-index graph "X" --output <path>` |
-
-Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
-error messages, and the default `hybrid` mode for mixed questions. Use pure
-`vector` mode only when embeddings are enabled and exact vocabulary is unknown.
-
-Read [references/commands.md](references/commands.md) only when command options
-or routing remain unclear.
-
-## Evidence protocol
-
-1. Pick one session tag for this conversation (for example `auth-fix-1`) and
-   pass `--session <tag>` to every `search` and `explain`.
-2. Run the best-matching command with `--json`.
-3. Check `index` before trusting the payload:
-   - missing → run `codebase-index index`, then repeat;
-   - stale with fewer than 20 changed files → run `codebase-index update`;
-   - stale with 20 or more changed files → run `codebase-index index`;
-   - fresh → continue.
-4. Start with ranks 1–3. Read only `recommended_reads` line ranges.
-5. Trace one additional hop only when the question requires behavior,
-   ownership, or impact.
-6. Before answering or editing from evidence gathered earlier in the task, run
-   `codebase-index verify --session <tag> --json` and reread anything whose
-   state is not `valid` or `relocated`.
-7. Answer with `file:line` evidence and state uncertainty explicitly.
-
-Do not open whole files when a line range is available. A snippet may already
-be sufficient. `skeletonized: true` means the response intentionally folded
-unrelated body lines; read the supplied range when the missing body matters.
-
-## Evidence memory
-
-- `reused: true` with `snippet: null` — this session already received that
-  exact text and its source is unchanged. Use your earlier copy; if you can no
-  longer see it, Read the range.
-- `memory.invalidated` — evidence this session received has changed since.
-  Treat your earlier copy as wrong and reread before relying on it.
-- `stale: true` — the index is older than the file. Run `codebase-index update`
-  or Read the range.
-- A tag belongs to one context. Never give it to a subagent or another
-  conversation. Start a new tag after the context is cleared or compacted, or
-  whenever earlier snippets are no longer visible to you.
-
-Verdict states and citing evidence in notes: [references/memory.md](references/memory.md).
-
-## Confidence contract
-
-- **high** — answer from the indexed evidence.
-- **medium** — read the recommended ranges and confirm the key claim with one
-  targeted lookup if necessary.
-- **low** or no results — follow `fallback_suggestions`, then use a narrow
-  Grep/Glob fallback.
-
-On `refs` and `impact`, inspect `coverage`. If `coverage.partial` is true, an
-empty result is inconclusive; confirm with targeted Grep before saying that
-nothing references the target.
-
-Edges carry `confidence`:
-
-- `extracted` — exact parser evidence;
-- `inferred` — heuristic resolution;
-- `ambiguous` — unresolved or non-unique.
-
-Never present an inferred or ambiguous chain as certain.
-
-## Answer contract
-
-Structure repository answers around:
-
-1. **Answer** — the direct conclusion.
-2. **Evidence** — the minimum supporting `file:line` references.
-3. **Confidence** — only when evidence is partial, inferred, stale, or missing.
-4. **Next check** — only when another check would materially reduce uncertainty.
-
-Do not narrate every search step. Do not claim absence from a partial graph.
-Do not replace evidence with a generated HTML graph.
 
-For payload fields and failure handling, read
-[references/response-contract.md](references/response-contract.md).
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).
diff --git a/skills/codebase-index/references/commands.md b/skills/codebase-index/references/commands.md
index 79c91a6..197ffe7 100644
--- a/skills/codebase-index/references/commands.md
+++ b/skills/codebase-index/references/commands.md
@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.
diff --git a/src/codebase_index/cli.py b/src/codebase_index/cli.py
index 71e6f99..9d61b2c 100644
--- a/src/codebase_index/cli.py
+++ b/src/codebase_index/cli.py
@@ -413,6 +413,10 @@ def search(
         help="Tag naming ONE agent context: evidence it already received and that is "
         "unchanged is not resent; changes to it are reported (docs/MEMORY.md).",
     ),
+    compact: bool = typer.Option(
+        False, "--compact",
+        help="Agent text: ranked locations with numbered matching lines, no JSON.",
+    ),
     json_out: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
 ) -> None:
     """Hybrid ranked search; returns compact results + recommended_reads."""
@@ -439,9 +443,12 @@ def search(
     payload = search_payload(
         db_path, cfg, query, mode=mode, limit=limit, offset=offset,
         token_budget=token_budget, no_fallback=no_fallback, backend=backend, raw=raw,
-        session=session,
+        session=session, hit_lines=compact,
     )
 
+    if compact:
+        typer.echo(md_renderer.render_search_compact(payload))
+        return
     want_json = json_out or (ctx.obj and ctx.obj.get("json"))
     typer.echo(json_renderer.render(payload) if want_json else md_renderer.render(payload))
 
@@ -451,15 +458,25 @@ def symbol(
     ctx: typer.Context,
     name: str = typer.Argument(...),
     kind: Optional[str] = typer.Option(None, "--kind", help="Filter by symbol kind."),
-    exact: bool = typer.Option(False, "--exact"),
+    exact: bool = typer.Option(
+        False, "--exact", help="Only exact matches, even when there are none."
+    ),
+    session: Optional[str] = typer.Option(
+        None, "--session",
+        help="Accepted so one tag can go to every read command; this command returns "
+        "locations, not snippets, so there is nothing to withhold.",
+    ),
     json_flag: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
 ) -> None:
-    """Locate a symbol definition by name."""
+    """Locate a symbol definition by name (or `Owner.member`).
+
+    Exact matches come alone when there are any; otherwise prefix matches."""
     from .output import json as json_out
     from .output import markdown as md_out
     from .retrieval.searchers import symbol_lookup
     from .storage.db import Database
 
+    _checked_session(session)
     is_json = json_flag or bool(ctx.obj and ctx.obj.get("json"))
     db_path, _cfg = _ensure_index(ctx)
 
@@ -473,20 +490,41 @@ def refs(
     ctx: typer.Context,
     symbol_name: str = typer.Argument(...),
     kind: str = typer.Option("all", "--kind", help="callers|all"),
+    exclude_tests: bool = typer.Option(
+        False, "--exclude-tests", help="Drop sites in test files."
+    ),
+    path: Optional[list[str]] = typer.Option(
+        None, "--path", help="Keep only sites under this path prefix (repeatable)."
+    ),
+    compact: bool = typer.Option(
+        False, "--compact",
+        help="One line per site (path:line kind caller -> target), no JSON envelope.",
+    ),
+    session: Optional[str] = typer.Option(
+        None, "--session",
+        help="Accepted so one tag can go to every read command; this command returns "
+        "locations, not snippets, so there is nothing to withhold.",
+    ),
     json_flag: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
 ) -> None:
-    """Find references / callers of a symbol."""
+    """Find references / callers of a symbol (a bare name or `Owner.member`)."""
     from .output import json as json_out
     from .output import markdown as md_out
     from .retrieval.searchers import refs_lookup
     from .storage.db import Database
 
+    _checked_session(session)
     is_json = json_flag or bool(ctx.obj and ctx.obj.get("json"))
     db_path, _cfg = _ensure_index(ctx)
 
     with Database(db_path) as db:
-        resp = refs_lookup(db.conn, symbol_name, kind=kind)
-    typer.echo(json_out.render(resp) if is_json else md_out.render_refs(resp))
+        resp = refs_lookup(
+            db.conn, symbol_name, kind=kind, exclude_tests=exclude_tests, paths=path or ()
+        )
+    if compact:
+        typer.echo(md_out.render_refs_compact(resp))
+    else:
+        typer.echo(json_out.render(resp) if is_json else md_out.render_refs(resp))
 
 
 @app.command()
@@ -495,6 +533,14 @@ def impact(
     target: str = typer.Argument(..., help="File path or symbol name."),
     depth: int = typer.Option(2, "--depth"),
     direction: str = typer.Option("up", "--direction", help="up|down|both"),
+    compact: bool = typer.Option(
+        False, "--compact", help="One line per affected node, no JSON."
+    ),
+    session: Optional[str] = typer.Option(
+        None, "--session",
+        help="Accepted so one tag can go to every read command; this command returns "
+        "locations, not snippets, so there is nothing to withhold.",
+    ),
     json_flag: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
 ) -> None:
     """Blast radius: what is affected if `target` changes (graph walk)."""
@@ -506,8 +552,16 @@ def impact(
     is_json = json_flag or bool(ctx.obj and ctx.obj.get("json"))
     db_path, _cfg = _ensure_index(ctx)
 
+    _checked_session(session)
+    from .graph.expand import target_paths
+    from .graph.modules import modules_for_paths
+
     with Database(db_path) as db:
         resp = impact_lookup(db.conn, target, depth=depth, direction=direction)
+        resp.modules = modules_for_paths(Path(_cfg.root), target_paths(db.conn, target))
+    if compact:
+        typer.echo(md_out.render_impact_compact(resp))
+        return
     typer.echo(json_out.render(resp) if is_json else md_out.render_impact(resp))
 
 
@@ -560,6 +614,10 @@ def explain(
         help="Tag naming ONE agent context: evidence it already received and that is "
         "unchanged is not resent; changes to it are reported (docs/MEMORY.md).",
     ),
+    compact: bool = typer.Option(
+        False, "--compact",
+        help="Agent text: ranked locations with numbered matching lines, no JSON.",
+    ),
     json_out: bool = typer.Option(False, "--json", help="Emit machine-readable JSON."),
 ) -> None:
     """Intent-aware bundle for 'how does X work' / overview questions."""
@@ -574,9 +632,12 @@ def explain(
     payload = search_payload(
         db_path, cfg, normalize_explain_query(query), mode="hybrid", limit=10,
         token_budget=token_budget, no_fallback=False, backend=backend, raw=raw,
-        session=session,
+        session=session, hit_lines=compact,
     )
 
+    if compact:
+        typer.echo(md_renderer.render_search_compact(payload))
+        return
     want_json = json_out or (ctx.obj and ctx.obj.get("json"))
     typer.echo(json_renderer.render(payload) if want_json else md_renderer.render(payload))
 
diff --git a/src/codebase_index/graph/builder.py b/src/codebase_index/graph/builder.py
index 4547883..b0df391 100644
--- a/src/codebase_index/graph/builder.py
+++ b/src/codebase_index/graph/builder.py
@@ -3,12 +3,15 @@
 
 Runs once after all files are indexed (it needs the complete symbol/file tables).
 Symbol-target edges (call/reference/extends/implements) resolve only on an
-UNAMBIGUOUS name match — if two definitions share a name, the edge is left
-unresolved rather than guessed. Import edges resolve their module path to a file
-by POSIX path-suffix match (e.g. 'auth.token' -> '%/auth/token.py').
-
-The pass is batched: one query for globally-unique symbol names, one for file
-paths (expanded into an in-memory suffix map), one executemany for the updates.
+UNAMBIGUOUS match within the caller's language family — if two definitions share a
+name, the edge is left unresolved rather than guessed. A call written against an
+owner (`TownService.refresh(x)`, `activation::place(..)`) also resolves when exactly
+one type or module of that name defines it; that match is a heuristic, recorded as
+'inferred'. Import edges resolve their module path to a file by POSIX path-suffix
+match (e.g. 'auth.token' -> '%/auth/token.py').
+
+The pass is batched: one query for all symbols, one for file paths (expanded into
+an in-memory suffix map), one executemany for the updates.
 The per-edge variant did an indexed lookup per symbol edge and up to ~20
 full-table LIKE scans per import edge, which dominated large builds.
 """
@@ -18,6 +21,7 @@
 import sqlite3
 from typing import Optional
 
+from ..parsers.base import module_name, names_a_type
 from ..storage import repo
 
 _SYMBOL_EDGE_TYPES = {"call", "reference", "extends", "implements"}
@@ -48,12 +52,12 @@ def resolve_edges(conn: sqlite3.Connection) -> int:
     if not edges:
         return 0
 
-    unique_symbols = repo.unique_symbol_ids_by_name(conn)
+    targets = _SymbolTargets(repo.symbols_for_resolution(conn))
     suffix_map = _path_suffix_map(repo.all_file_ids_with_paths(conn))
 
-    # (dst_kind, dst_id, edge_id, confidence). A repo-unique symbol name is an exact
-    # hit -> 'extracted'; an import resolved only by path-suffix matching is a best-
-    # effort heuristic -> 'inferred'.
+    # (dst_kind, dst_id, edge_id, confidence). A name unique within its language
+    # family is an exact hit -> 'extracted'; an owner/module match and an import
+    # resolved by path-suffix matching are heuristics -> 'inferred'.
     resolutions: list[tuple[str, int, int, str]] = []
     for edge in edges:
         name = edge["dst_name"]
@@ -62,14 +66,89 @@ def resolve_edges(conn: sqlite3.Connection) -> int:
             if file_id is not None:
                 resolutions.append(("file", file_id, edge["id"], "inferred"))
         elif edge["edge_type"] in _SYMBOL_EDGE_TYPES:
-            sym_id = unique_symbols.get(name)
-            if sym_id is not None:
-                resolutions.append(("symbol", sym_id, edge["id"], "extracted"))
+            hit = targets.resolve(language_family(edge["lang"]), edge["dst_qualifier"], name)
+            if hit is not None:
+                resolutions.append(("symbol", hit[0], edge["id"], hit[1]))
 
     repo.resolve_edges_bulk(conn, resolutions)
     return len(resolutions)
 
 
+# Languages that call each other directly; any other pair cannot share a call edge.
+_LANGUAGE_FAMILIES = {
+    "kotlin": "jvm", "java": "jvm", "scala": "jvm",
+    "typescript": "js", "javascript": "js",
+    "cpp": "c",
+}
+
+
+def language_family(lang: Optional[str]) -> Optional[str]:
+    return _LANGUAGE_FAMILIES.get(lang or "", lang)
+
+
+_Key = tuple[Optional[str], str, str]
+
+
+class _SymbolTargets:
+    """Where a symbol edge may point, indexed three ways within a language family.
+
+    - by name, for names defined once in the family;
+    - by (owner type, name), for `TownService.refresh(x)`;
+    - by (module, name), for a top-level definition called through its module
+      (`activation::place(..)`, `token.refresh()`); see `module_name`.
+    A key that two files claim maps to nothing: that is ambiguity, not a guess.
+    Overloads (one owner, one file, several rows) map to the first of them.
+    """
+
+    def __init__(self, rows: list[sqlite3.Row]) -> None:
+        by_name: dict[tuple[Optional[str], str], list[tuple[int, Optional[str]]]] = {}
+        by_owner: dict[_Key, tuple[int, int]] = {}
+        by_module: dict[_Key, tuple[int, int]] = {}
+        clashes: set[_Key] = set()
+        for row in rows:
+            family = language_family(row["lang"])
+            name, sym_id, file_id = row["name"], int(row["id"]), int(row["file_id"])
+            parts = (row["qualified"] or name).split(".")
+            owner = parts[-2] if len(parts) >= 2 and parts[-1] == name else None
+            by_name.setdefault((family, name), []).append((sym_id, owner))
+            if owner is not None:
+                _claim(by_owner, clashes, (family, owner, name), sym_id, file_id)
+            elif len(parts) == 1:
+                module = module_name(row["path"])
+                _claim(by_module, clashes, (family, module, name), sym_id, file_id)
+        self._unique = {key: ids[0] for key, ids in by_name.items() if len(ids) == 1}
+        self._owned = {k: v[0] for k, v in by_owner.items() if k not in clashes}
+        self._module = {k: v[0] for k, v in by_module.items() if k not in clashes}
+
+    def resolve(
+        self, family: Optional[str], receiver: Optional[str], name: str
+    ) -> Optional[tuple[int, str]]:
+        unique = self._unique.get((family, name))
+        # `ApprenticeService.take(x)` is not a call to the family's only `take` when
+        # that one belongs to Holdings. A top-level definition keeps matching any
+        # receiver (`Utils.fn()` may be a namespace import).
+        if unique is not None and not (
+            unique[1] is not None and names_a_type(receiver) and receiver != unique[1]
+        ):
+            return unique[0], "extracted"
+        if receiver is None:
+            return None
+        sym_id = self._owned.get((family, receiver, name))
+        if sym_id is None:
+            sym_id = self._module.get((family, receiver, name))
+        return (sym_id, "inferred") if sym_id is not None else None
+
+
+def _claim(
+    table: dict[_Key, tuple[int, int]], clashes: set[_Key], key: _Key, sym_id: int, file_id: int
+) -> None:
+    first = table.get(key)
+    if first is None:
+        table[key] = (sym_id, file_id)
+    elif first[1] != file_id:
+        clashes.add(key)
+
+
 def _path_suffix_map(rows: list[sqlite3.Row]) -> dict[str, Optional[int]]:
     """Map every '/'-aligned path suffix to its file id, or None when ambiguous.
 
diff --git a/src/codebase_index/graph/expand.py b/src/codebase_index/graph/expand.py
index ba75a0f..81d1794 100644
--- a/src/codebase_index/graph/expand.py
+++ b/src/codebase_index/graph/expand.py
@@ -7,7 +7,8 @@
 
 Target resolution: an exact file path -> a file node (seeded together with all
 symbols defined in that file, so importers AND subclassers surface). Otherwise a
-symbol name -> all symbol nodes with that name. A path suffix is the last resort.
+symbol name -> all symbol nodes with that name, or a qualified `Owner.member` ->
+that type's members. A path suffix is the last resort.
 """
 
 from __future__ import annotations
@@ -17,7 +18,13 @@
 from collections import deque
 from typing import Optional
 
-from ..models import GraphCoverage, ImpactNode, ImpactResponse, IndexFreshness
+from ..models import (
+    GraphCoverage,
+    ImpactNode,
+    ImpactResponse,
+    IndexFreshness,
+    unmatched_coverage,
+)
 from ..storage import repo
 
 
@@ -76,7 +83,7 @@ def _seed_nodes(conn: sqlite3.Connection, target: str) -> list[tuple[str, int]]:
         seeds += [("symbol", int(s["id"])) for s in repo.symbols_in_file(conn, int(frow["id"]))]
         return seeds
 
-    sym_rows = repo.symbols_by_name(conn, target, exact=True)
+    sym_rows, _member = repo.symbols_for_target(conn, target)
     if sym_rows:
         return [("symbol", int(r["id"])) for r in sym_rows]
 
@@ -211,11 +218,16 @@ def walk_impact(
     return sorted(nodes.values(), key=_impact_sort_key)
 
 
+def target_paths(conn: sqlite3.Connection, target: str) -> list[str]:
+    """The file path(s) a refs/impact target resolves to."""
+    return _target_paths(conn, target)
+
+
 def _target_paths(conn: sqlite3.Connection, target: str) -> list[str]:
     """The file path(s) the target resolves to, for coverage classification."""
     if repo.file_by_path(conn, target) is not None:
         return [target]
-    sym_rows = repo.symbols_by_name(conn, target, exact=True)
+    sym_rows, _member = repo.symbols_for_target(conn, target)
     if sym_rows:
         return [r["path"] for r in sym_rows]
     suffix = repo.files_with_suffix(conn, target)
@@ -242,5 +254,9 @@ def impact_lookup(
     return ImpactResponse(
         target=target, direction=direction, depth=depth,
         index=_freshness(conn), nodes=nodes, files=files,
-        coverage=GraphCoverage.for_paths(_target_paths(conn, target)),
+        coverage=(
+            GraphCoverage.for_paths(paths)
+            if (paths := _target_paths(conn, target))
+            else unmatched_coverage(target)
+        ),
     )
diff --git a/src/codebase_index/graph/modules.py b/src/codebase_index/graph/modules.py
new file mode 100644
index 0000000..53ab7fe
--- /dev/null
+++ b/src/codebase_index/graph/modules.py
@@ -0,0 +1,112 @@
+"""Build-system modules: which module a file belongs to, and who names it.
+
+"Would a change here break another module?" is a build-graph question the code
+graph cannot answer: a Gradle subproject that nothing depends on has no incoming
+edges whether or not other projects exist. Agents answered it by grepping every
+build file. This reads the build files instead — cheaply, without evaluating
+them — and reports the lines of *other* build files that mention the module, so
+the answer comes with its evidence.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path, PurePosixPath
+from typing import Optional
+
+BUILD_FILES = (
+    "build.gradle.kts", "build.gradle", "settings.gradle.kts", "settings.gradle",
+    "pom.xml", "Cargo.toml", "package.json", "go.mod", "pyproject.toml",
+)
+_SKIP_DIRS = frozenset({
+    ".git", "build", "target", "node_modules", "dist", "out", ".gradle", ".venv",
+    "venv", "__pycache__", ".idea", ".claude", "run",
+})
+_MAX_DEPTH = 5
+_COMMENT_PREFIXES = ("//", "#", "<!--", "*", "/*")
+_MAX_REFERENCES = 20
+
+
+def owning_module(root: Path, rel_path: str) -> Optional[str]:
+    """Nearest directory above `rel_path` (below the root) that has a build file."""
+    parent = PurePosixPath(rel_path).parent
+    while str(parent) not in ("", "."):
+        if any((root / str(parent) / name).is_file() for name in BUILD_FILES):
+            return str(parent)
+        parent = parent.parent
+    return None
+
+
+def _build_files(root: Path) -> list[Path]:
+    found: list[Path] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        rel = Path(dirpath).relative_to(root)
+        depth = len(rel.parts)
+        dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS and depth < _MAX_DEPTH]
+        found.extend(Path(dirpath) / f for f in filenames if f in BUILD_FILES)
+    return sorted(found)
+
+
+def module_references(root: Path, module: str) -> list[dict]:
+    """Lines of build files outside `module` that name it (`include`, deps, members)."""
+    name = PurePosixPath(module).name
+    # `:realism-polity`, "realism-polity", ../realism-polity, realism_polity (Cargo
+    # crates use either spelling), bounded so `realism-polity-api` is not a hit.
+    spellings = {name, name.replace("-", "_"), name.replace("_", "-")}
+    pattern = re.compile(
+        r"(?<![\w-])(?:" + "|".join(re.escape(s) for s in sorted(spellings)) + r")(?![\w-])"
+    )
+    own = (root / module).resolve()
+    out: list[dict] = []
+    for path in _build_files(root):
+        if path.resolve().parent == own:
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        settings = path.name.startswith("settings.gradle")
+        in_members = False
+        for number, line in enumerate(text.splitlines(), start=1):
+            opens = _MEMBERS_OPEN.search(line)
+            if line.lstrip().startswith(_COMMENT_PREFIXES):
+                continue
+            if pattern.search(line):
+                membership = settings or in_members or bool(opens) or "include" in line
+                out.append({
+                    "path": path.relative_to(root).as_posix(),
+                    "line": number,
+                    "text": line.strip()[:160],
+                    "kind": "member" if membership else "dependency",
+                })
+                if len(out) >= _MAX_REFERENCES:
+                    return out
+            if opens and "]" not in line[opens.end():]:
+                in_members = True
+            elif in_members and "]" in line:
+                in_members = False
+    return out
+
+
+# A workspace member list (Cargo `members = [`, npm `"workspaces": [`): naming a
+# module there includes it in the build; it is not a dependency on it.
+_MEMBERS_OPEN = re.compile(r"""^\s*"?(?:(?:default-)?members|workspaces)"?\s*[=:]\s*\[""")
+
+
+def modules_for_paths(root: Path, paths: list[str]) -> list[dict]:
+    """One entry per module the paths live in, with the build lines that name it."""
+    seen: dict[str, dict] = {}
+    for rel in paths:
+        module = owning_module(root, rel)
+        if module is None or module in seen:
+            continue
+        refs = module_references(root, module)
+        seen[module] = {
+            "module": module,
+            # `member`: the build includes the module; `dependency`: another module
+            # names it outside a member list, which is how dependencies are declared.
+            "referenced_by": refs,
+            "dependents": sorted({r["path"] for r in refs if r["kind"] == "dependency"}),
+        }
+    return list(seen.values())
diff --git a/src/codebase_index/graph/navigate.py b/src/codebase_index/graph/navigate.py
index 086e9a6..5f3cbbc 100644
--- a/src/codebase_index/graph/navigate.py
+++ b/src/codebase_index/graph/navigate.py
@@ -137,7 +137,7 @@ def path_payload(conn: sqlite3.Connection, src: str, dst: str) -> dict:
 def describe_payload(conn: sqlite3.Connection, query: str) -> dict:
     """A node card: definition(s), callers, callees, centrality, module, god status."""
     base = {"query": query, "index": _freshness(conn)}
-    sym_rows = repo.symbols_by_name(conn, query, exact=True)
+    sym_rows, _member = repo.symbols_for_target(conn, query)
     if not sym_rows:
         return {**base, "found": False,
                 "reason": f"No symbol named `{query}` is indexed. Try `search` or `symbol`."}
@@ -160,9 +160,15 @@ def describe_payload(conn: sqlite3.Connection, query: str) -> dict:
     primary_row = max(sym_rows, key=lambda r: int(r["in_degree"]) + int(r["out_degree"]))
     primary_id = int(primary_row["id"])
 
+    from ..retrieval.searchers import refs_lookup
+
+    # Same resolution as `refs`: for `Owner.member`, or a name several types share,
+    # only the sites that belong to these definitions, each naming its caller.
     callers = [
-        {"path": r["path"], "line": r["line"], "confidence": r["confidence"]}
-        for r in repo.refs_for_name(conn, query)
+        {"path": s.path, "line": s.line, "confidence": s.confidence,
+         "caller": s.caller, "target": s.target}
+        for s in refs_lookup(conn, query, kind="callers").sites
+        if s.kind == "call"
     ]
     callees = []
     for e in repo.outgoing_edges(conn, "symbol", primary_id):
@@ -175,7 +181,7 @@ def describe_payload(conn: sqlite3.Connection, query: str) -> dict:
     module = primary_row["path"].rsplit("/", 1)[0] if "/" in primary_row["path"] else "(root)"
     god = _god_rank(conn, primary_row["name"], primary_row["path"])
 
-    return {
+    card = {
         **base,
         "found": True,
         "definitions": definitions,
@@ -186,6 +192,60 @@ def describe_payload(conn: sqlite3.Connection, query: str) -> dict:
         "callers": callers,
         "callees": callees,
     }
+    if primary_row["kind"] in _TYPE_KINDS:
+        card.update(_type_card(conn, primary_id))
+    return card
+
+
+_TYPE_KINDS = frozenset({"class", "interface", "enum", "struct", "trait", "impl", "record"})
+_TYPE_CARD_CAP = 40
+
+
+def _type_card(conn: sqlite3.Connection, type_id: int) -> dict:
+    """Members of a type and the graph around them, as one card.
+
+    A class is rarely called itself: its methods are. Describing `TreasuryService`
+    by the class node alone gave zero callers and zero callees, so the card lists
+    the members and folds their edges from and to code *outside* the type.
+    """
+    members = repo.members_of(conn, type_id)
+    member_ids = {int(m["id"]) for m in members}
+    inside = member_ids | {type_id}
+    used_by: dict[tuple[str, str, str], dict] = {}
+    uses: dict[tuple[str, str], dict] = {}
+    for m in members:
+        for e in repo.incoming_edges(conn, "symbol", int(m["id"])):
+            if e["src_kind"] == "symbol" and int(e["src_id"]) in inside:
+                continue
+            src = _node_ref(conn, e["src_kind"], int(e["src_id"]))
+            if src is None:
+                continue
+            key = (src["path"], src["name"], m["name"])
+            used_by.setdefault(key, {"member": m["name"], "caller": src["name"],
+                                     "path": src["path"], "line": e["line"],
+                                     "confidence": e["confidence"]})
+        for e in repo.outgoing_edges(conn, "symbol", int(m["id"])):
+            if e["dst_id"] is None or (e["dst_kind"] == "symbol" and int(e["dst_id"]) in inside):
+                continue
+            dst = _node_ref(conn, e["dst_kind"], int(e["dst_id"]))
+            if dst is None:
+                continue
+            uses.setdefault((dst["path"], dst["name"]), {**dst, "edge_type": e["edge_type"],
+                                  "confidence": e["confidence"]})
+    return {
+        "members": [
+            {"name": m["name"], "kind": m["kind"], "line_start": m["line_start"],
+             "line_end": m["line_end"], "signature": m["signature"],
+             "in_degree": int(m["in_degree"])}
+            for m in members
+        ],
+        "used_by": sorted(used_by.values(), key=lambda r: (r["path"], r["line"] or 0))[
+            :_TYPE_CARD_CAP],
+        "used_by_total": len(used_by),
+        "uses": sorted(uses.values(), key=lambda r: (r["path"], r["line_start"] or 0))[
+            :_TYPE_CARD_CAP],
+        "uses_total": len(uses),
+    }
 
 
 def _god_rank(conn: sqlite3.Connection, name: str, path: str) -> Optional[int]:
diff --git a/src/codebase_index/indexer/pipeline.py b/src/codebase_index/indexer/pipeline.py
index 7bd92c1..21d85fd 100644
--- a/src/codebase_index/indexer/pipeline.py
+++ b/src/codebase_index/indexer/pipeline.py
@@ -16,7 +16,7 @@
 from ..discovery.walker import walk
 from ..embeddings.backend import resolve_backend
 from ..graph.builder import build_graph
-from ..parsers.base import ParseResult
+from ..parsers.base import ParseResult, names_a_type
 from ..parsers.line_chunker import chunk_text
 from ..parsers.treesitter import UnsupportedLanguage, parse_file
 from ..storage import repo
@@ -292,6 +292,9 @@ def _resolve_edges(
         symbol.name: symbol_ids[idx]
         for idx, symbol in enumerate(parse_result.symbols)
     }
+    local_types = {
+        symbol.name for symbol in parse_result.symbols if symbol.kind in _TYPE_KINDS
+    }
     rows: list[dict] = []
     for edge in parse_result.edges:
         src_id = (
@@ -301,6 +304,10 @@ def _resolve_edges(
         )
         src_kind = "symbol" if edge.src_symbol_index is not None else "file"
         dst_id = name_to_id.get(edge.callee_name)
+        if dst_id is not None and _names_foreign_type(edge.receiver, local_types):
+            # `Other.refresh()` is not this file's `refresh`; leave it to the
+            # global pass, which can match the receiver to its owning type.
+            dst_id = None
         rows.append(
             {
                 "edge_type": edge.edge_type,
@@ -311,11 +318,25 @@ def _resolve_edges(
                 "dst_name": edge.callee_name,
                 "line": edge.line,
                 "resolved": 1 if dst_id is not None else 0,
+                "dst_qualifier": edge.receiver,
             }
         )
     return rows
 
 
+_TYPE_KINDS = frozenset({"class", "record", "struct", "interface", "trait", "enum", "impl"})
+
+
+def _names_foreign_type(receiver: Optional[str], local_types: set[str]) -> bool:
+    """True when a call's receiver names a type this file does not define.
+
+    A variable, `this`/`self`, `Self` or a constant says nothing about the callee's
+    type (see `names_a_type`), so same-file resolution keeps its old behaviour.
+    """
+    return names_a_type(receiver) and receiver not in local_types
+
+
+
 def _utc_now_iso() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
@@ -351,6 +372,7 @@ def update_index(
     scope = _git_changed_since(root, since) if since else None
 
     seen: set[str] = set()
+    changed: list = []
     for cand in walk(root, config):
         seen.add(cand.rel_path)
         if scope is not None and cand.rel_path not in scope:
@@ -377,8 +399,13 @@ def update_index(
             )
             stats.skipped += 1
             continue
+        changed.append(cand)
 
-        pr = _parse_one_inline(cand, config, sha256=sha)
+    # Parse like a full build does: in a process pool once there are enough files.
+    # Parsing a large change set one file at a time made `update` slower than
+    # rebuilding from scratch (2009 changed files: 149 s, against 13 s for a full
+    # build of all 5904).
+    for cand, pr in zip(changed, _parse_all(changed, config)):
         _add_stats(stats, _write_candidate(conn, cand, pr, now))
 
     if scope is None:
diff --git a/src/codebase_index/mcp/server.py b/src/codebase_index/mcp/server.py
index fe8866d..f19aecc 100644
--- a/src/codebase_index/mcp/server.py
+++ b/src/codebase_index/mcp/server.py
@@ -210,14 +210,19 @@ def find_symbol(
 def find_refs(
     symbol: str,
     kind: str = "all",
+    exclude_tests: bool = False,
+    path: Optional[str] = None,
 ) -> str:
     """Find all references and callers of a symbol.
 
-    Returns call sites with file path and line number.
+    Returns call sites with file path, line number and the calling function.
 
     Args:
-        symbol: Symbol name whose references to find.
+        symbol: Symbol name, or `Owner.member` / `module::fn` to exclude same-named
+            members of other types.
         kind: "callers" for call edges only, "all" for any reference type.
+        exclude_tests: Drop sites in test files.
+        path: Keep only sites under this path prefix.
     """
     db_path, _ = _resolve_db()
     if not db_path.exists():
@@ -227,7 +232,10 @@ def find_refs(
     from ..storage.db import Database
 
     with Database(db_path) as db:
-        resp = refs_lookup(db.conn, symbol, kind=kind)
+        resp = refs_lookup(
+            db.conn, symbol, kind=kind, exclude_tests=exclude_tests,
+            paths=[path] if path else (),
+        )
     return _emit("find_refs", resp.model_dump())
 
 
diff --git a/src/codebase_index/models.py b/src/codebase_index/models.py
index b87ec79..dde6a59 100644
--- a/src/codebase_index/models.py
+++ b/src/codebase_index/models.py
@@ -65,6 +65,9 @@ class SymbolResponse(BaseModel):
     query: str
     index: IndexFreshness
     symbols: list[SymbolDef] = []
+    # Prefix matches left out because exact matches exist (`symbol --exact` drops
+    # them silently; the default reports how many there were).
+    more_prefix_matches: int = 0
 
 
 class GraphCoverage(BaseModel):
@@ -109,13 +112,38 @@ def for_paths(cls, paths: Iterable[str]) -> "GraphCoverage":
         )
 
 
+def unmatched_coverage(target: str) -> GraphCoverage:
+    """Coverage for a target that matched no indexed definition or call site.
+
+    An empty answer here says nothing about the code: the name may be misspelt,
+    external, or in an unindexed file. Mark it partial so it is not read as
+    "no callers".
+    """
+    return GraphCoverage(
+        partial=True,
+        reason=(
+            f"No indexed definition or call site matches '{target}'. Check the name "
+            "with `symbol` (use Owner.member for a method), or confirm with Grep."
+        ),
+    )
+
+
 class RefSite(BaseModel):
     path: str
     line: int
+    # 'call' | 'reference' (a non-call use, e.g. a Rust enum variant in a `match`
+    # pattern) | 'definition' | 'possible_call' (an Owner.member query: a same-named
+    # call whose receiver the index cannot type, so it may or may not be this one).
     kind: str
     # Audit trail (see edges.confidence): 'extracted' = exact match, 'inferred' =
     # heuristic, 'ambiguous' = unresolved/non-unique. Defaults keep older callers valid.
     confidence: str = "extracted"
+    # The definition a call resolved to ('TownService.refresh'), and what it was
+    # called on ('TownService', 'town', 'this'); tell same-named methods apart.
+    target: Optional[str] = None
+    receiver: Optional[str] = None
+    # The function or method the call sits in ('TreasuryService.withdraw').
+    caller: Optional[str] = None
 
 
 class RefsResponse(BaseModel):
@@ -143,3 +171,6 @@ class ImpactResponse(BaseModel):
     nodes: list[ImpactNode] = []
     files: list[str] = []           # distinct affected files, ranked
     coverage: GraphCoverage = Field(default_factory=GraphCoverage)
+    # Build-system modules the target is defined in, with the build-file lines that
+    # name them (graph/modules.py). Filled by the CLI, which knows the repo root.
+    modules: list[dict] = []
diff --git a/src/codebase_index/output/markdown.py b/src/codebase_index/output/markdown.py
index 6914e34..ee39b22 100644
--- a/src/codebase_index/output/markdown.py
+++ b/src/codebase_index/output/markdown.py
@@ -171,6 +171,8 @@ def render_symbols(resp: SymbolResponse) -> str:
             f"| `{display}` | {symbol.kind} | `{symbol.path}` | "
             f"{symbol.line_start}-{symbol.line_end} | `{signature}` |"
         )
+    if resp.more_prefix_matches:
+        lines.append(f"\n_{resp.more_prefix_matches} more symbols start with `{resp.query}`._")
     return "\n".join(lines).rstrip() + "\n"
 
 
@@ -199,17 +201,110 @@ def render_refs(resp: RefsResponse) -> str:
             lines.append(note)
         return "\n".join(lines).rstrip() + "\n"
 
-    lines.append("| kind | path | line | confidence |")
-    lines.append("|------|------|------|------------|")
+    lines.append("| kind | path | line | in | target | confidence |")
+    lines.append("|------|------|------|----|--------|------------|")
     for site in resp.sites:
+        target = site.target or (f"on `{site.receiver}`" if site.receiver else "")
+        caller = f"`{site.caller}`" if site.caller else ""
         lines.append(
-            f"| {site.kind} | `{site.path}` | {site.line} | {_conf_mark(site.confidence) or 'exact'} |"
+            f"| {site.kind} | `{site.path}` | {site.line} | {caller} | {target} "
+            f"| {_conf_mark(site.confidence) or 'exact'} |"
         )
     if note:
         lines.append(note)
     return "\n".join(lines).rstrip() + "\n"
 
 
+def render_search_compact(payload: dict) -> str:
+    """Agent text for search/explain: ranked locations with numbered lines.
+
+    One `path:start-end symbols` header per result and, under it, the numbered
+    lines that carry the match — ready to cite as `file:line` without a Read.
+    Evidence the session already holds is one line (`already sent`).
+    """
+    index = payload.get("index") or {}
+    head = f"# {payload.get('intent', '')} · confidence {payload.get('confidence', '')}"
+    if not index.get("exists", True):
+        head += " · NO INDEX: run `codebase-index index`"
+    elif index.get("stale"):
+        head += (f" · index stale ({index.get('files_changed_since_build', '?')} files"
+                 " changed): run `codebase-index update`")
+    memory = payload.get("memory") or {}
+    for item in memory.get("invalidated") or []:
+        head += f"\n# changed since sent: {item.get('path')}:{item.get('line_start')}"
+    lines = [head]
+    for r in payload.get("results", []):
+        loc = f"{r['path']}:{r['line_start']}-{r['line_end']}"
+        names = ",".join(r.get("symbols") or [])
+        label = f"{loc} {names}".rstrip()
+        if r.get("stale"):
+            label += " [stale: file changed, Read it]"
+        if r.get("reused"):
+            lines.append(f"{label} (already sent)")
+            continue
+        lines.append(label)
+        hits = r.get("hits")
+        if hits is None and r.get("snippet"):
+            hits = [[r["line_start"] + i, t.strip()]
+                    for i, t in enumerate(r["snippet"].splitlines()[:8]) if t.strip()]
+        prev = None
+        for n, text in hits or []:
+            if prev is not None and n > prev + 1:
+                lines.append("    …")
+            lines.append(f"  {n}| {text}")
+            prev = n
+    if not payload.get("results"):
+        lines.append("# no results")
+    fallback = payload.get("fallback_suggestions") or {}
+    if fallback:
+        tips = "; ".join(f"{k}: {v}" for k, v in fallback.items() if v)
+        if tips:
+            lines.append(f"# low confidence — {tips}"[:400])
+    page = payload.get("pagination") or {}
+    if page.get("has_more"):
+        lines.append(f"# more results: --offset {page.get('next_offset')}")
+    return "\n".join(lines)
+
+
+def render_impact_compact(resp: ImpactResponse) -> str:
+    """Agent text for impact: `d<hops> path:line name via edge [confidence]`."""
+    lines = [f"# impact {resp.target} · {resp.direction} · depth {resp.depth} · "
+             f"{len(resp.files)} files"]
+    if resp.coverage.partial:
+        lines.append(f"# partial: {resp.coverage.reason}")
+    for m in resp.modules:
+        deps = ", ".join(m.get("dependents") or []) or "none"
+        members = [f"{r['path']}:{r['line']}" for r in m.get("referenced_by", [])
+                   if r.get("kind") == "member"]
+        incl = f" · included by {', '.join(members)}" if members else ""
+        lines.append(f"# module {m['module']}: build files depending on it: {deps}{incl}")
+    for n in sorted(resp.nodes, key=lambda x: (x.distance, x.path, x.line_start or 0)):
+        loc = f"{n.path}:{n.line_start}" if n.line_start else n.path
+        conf = "" if n.via_confidence in (None, "extracted") else f" [{n.via_confidence}]"
+        lines.append(f"d{n.distance} {loc} {n.name or ''} via {n.via_edge or '?'}{conf}".replace("  ", " "))
+    return "\n".join(lines)
+
+
+def render_refs_compact(resp: RefsResponse) -> str:
+    """One line per site, for agents: `path:line kind caller -> target [confidence]`."""
+    counts: dict[str, int] = {}
+    for site in resp.sites:
+        counts[site.kind] = counts.get(site.kind, 0) + 1
+    # The total is stated so an agent copies it instead of recounting the list.
+    summary = ", ".join(
+        f"{n} {kind}{'' if n == 1 else 's'}" for kind, n in sorted(counts.items())
+    )
+    lines = [f"# {resp.query}: {summary or 'no sites'}"]
+    if resp.coverage.partial:
+        lines.append(f"# partial: {resp.coverage.reason}")
+    for site in resp.sites:
+        target = site.target or (f"{site.receiver}.?" if site.receiver else "?")
+        caller = f"{site.caller} -> " if site.caller else ""
+        conf = "" if site.confidence == "extracted" else f" [{site.confidence}]"
+        lines.append(f"{site.path}:{site.line} {site.kind} {caller}{target}{conf}")
+    return "\n".join(lines)
+
+
 def _node_label(ref: dict) -> str:
     name = ref.get("name")
     path = ref.get("path") or ""
@@ -265,7 +360,8 @@ def render_describe(payload: dict) -> str:
         lines.append(f"**callers ({len(callers)}):**")
         for c in callers[:20]:
             mark = _conf_mark(c.get("confidence"))
-            lines.append(f"- `{c['path']}:{c['line']}`{' · ' + mark if mark else ''}")
+            caller = f" in `{c['caller']}`" if c.get("caller") else ""
+            lines.append(f"- `{c['path']}:{c['line']}`{caller}{' · ' + mark if mark else ''}")
         lines.append("")
 
     callees = payload.get("callees", [])
@@ -277,6 +373,24 @@ def render_describe(payload: dict) -> str:
                          f"{' · ' + mark if mark else ''}")
         lines.append("")
 
+    members = payload.get("members", [])
+    if members:
+        lines.append(f"**members ({len(members)}):**")
+        for m in members:
+            sig = f" — `{m['signature']}`" if m.get("signature") else ""
+            lines.append(f"- {m['kind']} `{m['name']}` :{m['line_start']}-{m['line_end']}{sig}")
+        lines.append("")
+    for key, title in (("used_by", "used by"), ("uses", "uses")):
+        rows = payload.get(key, [])
+        if rows:
+            lines.append(f"**{title} ({payload.get(key + '_total', len(rows))}):**")
+            for r in rows:
+                if key == "used_by":
+                    lines.append(f"- `{r['caller']}` → `{r['member']}` at `{r['path']}:{r['line']}`")
+                else:
+                    lines.append(f"- {_node_label(r)} _{r.get('edge_type', '')}_")
+            lines.append("")
+
     return "\n".join(lines).rstrip() + "\n"
 
 
diff --git a/src/codebase_index/parsers/base.py b/src/codebase_index/parsers/base.py
index f72bfaa..529875a 100644
--- a/src/codebase_index/parsers/base.py
+++ b/src/codebase_index/parsers/base.py
@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from pathlib import PurePosixPath
 from typing import Optional, Protocol
 
 
@@ -34,6 +35,32 @@ class Edge:
     callee_name: str
     line: int
     src_symbol_index: Optional[int] = None
+    # What the call was made on, e.g. 'TownService' for `TownService.refresh(x)`;
+    # None for a bare call or a receiver that is not a plain (dotted) name.
+    receiver: Optional[str] = None
+
+
+def module_name(path: str) -> str:
+    """The name code uses for the module a file defines: `activation` for
+    `src/activation.rs`, `auth` for `auth/__init__.py` or `auth/mod.rs`."""
+    p = PurePosixPath(path)
+    if p.stem in ("mod", "__init__", "index") and p.parent.name:
+        return p.parent.name
+    return p.stem
+
+
+def names_a_type(receiver: Optional[str]) -> bool:
+    """True when a call receiver reads as a type name: `TownService`, `Foo`.
+
+    Not a variable (`town`), `this`/`self`, Rust's `Self` (the enclosing type), or
+    a constant (`WOOD`, `MAX_SIZE`): those say nothing about which type is called.
+    """
+    return (
+        receiver is not None
+        and receiver[:1].isupper()
+        and receiver != "Self"
+        and not receiver.isupper()
+    )
 
 
 @dataclass
diff --git a/src/codebase_index/parsers/treesitter.py b/src/codebase_index/parsers/treesitter.py
index 67981dc..f0a8d8b 100644
--- a/src/codebase_index/parsers/treesitter.py
+++ b/src/codebase_index/parsers/treesitter.py
@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 from typing import Optional
 
 from tree_sitter import Parser, Query, QueryCursor
@@ -37,6 +38,8 @@ def parse_file(lang: str, text: str) -> ParseResult:
     else:
         symbols = _extract_symbols_generic(root, source)
     edges = _extract_edges(root, symbols, source)
+    if lang == "rust":
+        edges.extend(_rust_path_references(root, symbols, source))
     if spec is not None:
         edges.extend(_extract_graph_edges(spec, grammar, root, symbols))
     del grammar
@@ -128,6 +131,9 @@ def _extract_symbols(root, lang: str, source: bytes) -> list[Symbol]:
     "trait_declaration": "trait",  # php
     "enum_declaration": "enum",  # java, csharp, ts
     "enum_item": "enum",  # rust
+    "enum_variant": "variant",  # rust
+    "enum_constant": "variant",  # java
+    "enum_member_declaration": "variant",  # csharp
     "enum_specifier": "enum",  # c/cpp
     "impl_item": "impl",  # rust
     # modules / namespaces (NOT containers — a function inside stays a function, not a method)
@@ -310,11 +316,56 @@ def _extract_edges(root, symbols: list[Symbol], source: bytes) -> list[Edge]:
                 callee_name=_node_text(callee, source),
                 line=line,
                 src_symbol_index=_enclosing_symbol_index(symbols, line),
+                receiver=_receiver_name(node, source),
             )
         )
     return edges
 
 
+# Where a Rust `Owner::name` path is a use of `name` rather than part of a longer
+# path, an import, or a call (calls are already edges).
+_RUST_PATH_SKIP_PARENTS = frozenset({
+    "scoped_identifier", "scoped_type_identifier", "use_declaration", "scoped_use_list",
+    "use_list", "use_as_clause", "use_wildcard",
+})
+
+
+def _rust_path_references(root, symbols: list[Symbol], source: bytes) -> list[Edge]:
+    """`CoreError::ObjectDamaged` in a pattern or a value, as a 'reference' edge.
+
+    Enum variants are matched (`Err(CoreError::ObjectDamaged(_)) =>`,
+    `if let Kind::A = ..`) and passed around (`Err(CoreError::Gone)`) far more often
+    than they are called, so without these edges `refs` finds the constructions of
+    a variant but not the code that handles it.
+    """
+    edges: list[Edge] = []
+    for node in _walk(root):
+        kind = _kind(node)
+        if kind not in {"scoped_identifier", "scoped_type_identifier"}:
+            continue
+        parent = node.parent
+        pkind = _kind(parent) if parent is not None else ""
+        if pkind in _RUST_PATH_SKIP_PARENTS:
+            continue
+        if pkind == "call_expression" and _field(parent, "function") == node:
+            continue
+        if kind == "scoped_type_identifier" and pkind not in {"struct_pattern", "struct_expression"}:
+            continue  # type positions: `-> io::Result<..>` is not a use of a variant
+        name, path = _field(node, "name"), _field(node, "path")
+        if name is None or path is None:
+            continue
+        owner = re.split(r"::", _node_text(path, source))[-1]
+        line = _row(_start_point(node)) + 1
+        edges.append(Edge(
+            edge_type="reference",
+            callee_name=_node_text(name, source),
+            line=line,
+            src_symbol_index=_enclosing_symbol_index(symbols, line),
+            receiver=owner if _RECEIVER_NAME.fullmatch(owner) else None,
+        ))
+    return edges
+
+
 _EDGE_PREFIXES = {"import.": "import", "extends.": "extends", "implements.": "implements"}
 
 
@@ -368,9 +419,13 @@ def _callee_node(node):
     if kind not in {"call", "call_expression", "invocation_expression", "function_call_expression"}:
         return None
     # ruby `call` uses field "method"; everything else uses field "function".
-    fn = _field(node, "function") or _field(node, "method")
+    fn = _field(node, "function") or _field(node, "method") or _kotlin_callee(node)
     if fn is None:
         return None
+    if _kind(fn) == "navigation_expression":  # kotlin: Foo.bar(...)
+        suffix = _named_children(fn)[-1]
+        name = _named_children(suffix)[-1] if _named_children(suffix) else None
+        return name if name is not None and _kind(name) in _CALLEE_LEAVES else None
     if _kind(fn) in _CALLEE_LEAVES:
         return fn
     # member / selector / scoped / field access: take the trailing identifier.
@@ -385,6 +440,55 @@ def _callee_node(node):
     return None
 
 
+def _kotlin_callee(node):
+    """Kotlin's `call_expression` has no named fields: its first named child is the
+    callee (`simple_identifier` or `navigation_expression`), followed by
+    `call_suffix`."""
+    children = _named_children(node)
+    if len(children) >= 2 and _kind(children[-1]) == "call_suffix":
+        return children[0]
+    return None
+
+
+# Field that holds the receiver of a member call, per grammar: java `object`,
+# python/js/ts `object`, go `operand`, rust field `value` / scoped `path`,
+# c/c++ `argument`, c# `expression`, ruby `receiver`.
+_RECEIVER_FIELDS = ("object", "operand", "value", "path", "argument", "expression", "receiver")
+_RECEIVER_NAME = re.compile(r"[A-Za-z_$][\w$]*(?:(?:\.|::)[A-Za-z_$][\w$]*)*")
+
+
+def _receiver_name(node, source: bytes) -> Optional[str]:
+    """The last segment of a call's receiver when it is a plain (dotted) name.
+
+    `TownService.refresh(x)` -> 'TownService', `a.b.Foo.bar()` -> 'Foo',
+    `Foo::new()` -> 'Foo', `self.save()` -> 'self'. A computed receiver
+    (`get().x()`, `a[0].x()`) or a bare call yields None: there is no name to
+    resolve against.
+    """
+    kind = _kind(node)
+    if kind == "method_invocation":
+        holder = node
+    elif kind == "call" and _field(node, "receiver") is not None:
+        holder = node
+    else:
+        holder = _field(node, "function") or _kotlin_callee(node)
+        if holder is None or _kind(holder) in _CALLEE_LEAVES:
+            return None
+    if _kind(holder) == "navigation_expression":
+        receiver = _named_children(holder)[0]
+        text = _node_text(receiver, source).strip()
+        return re.split(r"\.|::", text)[-1] if _RECEIVER_NAME.fullmatch(text) else None
+    receiver = next(
+        (r for f in _RECEIVER_FIELDS if (r := _field(holder, f)) is not None), None
+    )
+    if receiver is None:
+        return None
+    text = _node_text(receiver, source).strip()
+    if not _RECEIVER_NAME.fullmatch(text):
+        return None
+    return re.split(r"\.|::", text)[-1]
+
+
 def _kind(node) -> str:
     value = getattr(node, "type", None)
     if value is None:
diff --git a/src/codebase_index/retrieval/intent.py b/src/codebase_index/retrieval/intent.py
index cefe865..89fcad2 100644
--- a/src/codebase_index/retrieval/intent.py
+++ b/src/codebase_index/retrieval/intent.py
@@ -32,6 +32,24 @@
 }
 
 
+_QUESTION_RE = re.compile(
+    r"^\s*(?:how|what|where|which|who|whom|whose|why|when|does|do|is|are|can|could|"
+    r"should|would|will)\b|\?\s*$",
+    re.I,
+)
+
+
+def is_question(query: str) -> bool:
+    """True for a question ("how is a crop loaded", "which books can be bought?").
+
+    Separate from intent: most such questions classify as KEYWORD, but they differ
+    from terse keyword or commit-subject queries in one way that matters to
+    retrieval — the answer is usually named by a noun the question paraphrases, so
+    it tends to sit lower in each retriever's list.
+    """
+    return bool(_QUESTION_RE.search(query))
+
+
 def detect_intent(query: str) -> IntentPlan:
     matched = [_PLANS[intent] for pattern, intent in _RULES if pattern.search(query)]
     if not matched:
diff --git a/src/codebase_index/retrieval/pipeline.py b/src/codebase_index/retrieval/pipeline.py
index 11f7bde..9370743 100644
--- a/src/codebase_index/retrieval/pipeline.py
+++ b/src/codebase_index/retrieval/pipeline.py
@@ -14,10 +14,12 @@
 from ..config import Config
 from ..indexer.freshness import compute_freshness
 from . import searchers
+from ..output.redact import redact_snippet
 from .budget import apply_budget
 from .diversity import deduplicate, mmr_select
 from .fusion import fuse
-from .intent import detect_intent
+from .intent import detect_intent, is_question
+from .lexical import salient_terms
 from .rerank import rerank
 from .tuning import DEFAULT_TUNING, RetrievalTuning
 from .types import Confidence
@@ -185,6 +187,81 @@ def _bounded_read(entry: dict, max_lines: int) -> dict:
     }
 
 
+_MAX_HIT_LINES = 8
+_MAX_HIT_CHARS = 180
+
+
+_SUFFIXES = ("ing", "ed", "es", "s")
+
+
+def _display_stem(term: str) -> str:
+    for suffix in _SUFFIXES:
+        if term.endswith(suffix) and len(term) - len(suffix) >= 4:
+            return term[: -len(suffix)]
+    return term
+
+
+def _range_lines(conn: sqlite3.Connection, cand) -> tuple[int, list[str]]:
+    """(first line number, lines) of the candidate's full range.
+
+    A symbol-retriever candidate carries only its signature as `content`; the body
+    is in the chunk that covers it.
+    """
+    content = getattr(cand, "content", None) or ""
+    start, end = int(cand.line_start), int(cand.line_end)
+    lines = content.splitlines()
+    if len(lines) >= end - start + 1:
+        return start, lines
+    row = conn.execute(
+        "SELECT c.content, c.line_start FROM chunks c JOIN files f ON f.id = c.file_id "
+        "WHERE f.path = ? AND c.line_start <= ? AND c.line_end >= ? "
+        "ORDER BY c.line_end - c.line_start LIMIT 1",
+        (cand.path, start, end),
+    ).fetchone()
+    if row is None:
+        return start, lines
+    chunk = row[0].splitlines()
+    offset = start - int(row[1])
+    return start, chunk[offset:offset + (end - start + 1)]
+
+
+def _hit_lines(conn: sqlite3.Connection, cand, terms: tuple[str, ...]) -> list[list]:
+    """The candidate's lines an agent would cite, numbered: `[[line, text], ...]`.
+
+    What `grep -n` gives, restricted to a ranked candidate: its first line (the
+    signature or declaration) and the lines that contain a query term, rarer terms
+    weighing more, then back in file order. A snippet
+    without line numbers sends an agent back to grep for them before it can cite.
+    """
+    start, lines = _range_lines(conn, cand)
+    if not lines:
+        return []
+    lowered = [line.casefold() for line in lines]
+    # Display only, never ranking: "persisted" should light up `persist()`.
+    terms = tuple(dict.fromkeys(_display_stem(t) for t in terms if len(t) >= 3))
+    # A term on every other line ("town" in a town module) says little about
+    # which lines matter; weight each by how rarely it occurs in this range.
+    weight = {t: 1.0 / max(1, sum(t in low for low in lowered)) for t in terms}
+    scored: list[tuple[float, int]] = []
+    for i, low in enumerate(lowered):
+        score = sum(weight[t] for t in terms if t in low)
+        if score:
+            scored.append((score, i))
+    first = next((i for i, line in enumerate(lines) if line.strip()), 0)
+    picked = {first}
+    for _score, i in sorted(scored, key=lambda s: (-s[0], s[1])):
+        if len(picked) >= _MAX_HIT_LINES:
+            break
+        picked.add(i)
+    out = []
+    for i in sorted(picked):
+        text = redact_snippet(lines[i].strip())
+        if len(text) > _MAX_HIT_CHARS:
+            text = text[: _MAX_HIT_CHARS - 1] + "…"
+        out.append([start + i, text])
+    return out
+
+
 def search(
     conn: sqlite3.Connection,
     query: str,
@@ -203,6 +280,7 @@ def search(
     explain: bool = False,
     evidence: Optional[Callable[[dict, list], None]] = None,
     max_read_lines: int = 120,
+    hit_lines: bool = False,
 ) -> dict:
     tuning = tuning or DEFAULT_TUNING
     plan = detect_intent(query)
@@ -215,7 +293,10 @@ def search(
     # a tiny `limit` still leaves selection something to choose between; multiplier
     # 1 means "no over-fetch at all" and takes the page size verbatim.
     pool_mult = max(1, tuning.candidate_pool_multiplier)
-    pool_limit = fetch_limit if pool_mult == 1 else max(fetch_limit * pool_mult, 20)
+    floor = tuning.candidate_pool_floor
+    if tuning.question_pool_floor and is_question(query):
+        floor = max(floor, tuning.question_pool_floor)
+    pool_limit = fetch_limit if pool_mult == 1 else max(fetch_limit * pool_mult, floor)
     lists, weights = _run_retrievers(
         conn,
         query,
@@ -255,6 +336,10 @@ def search(
     all_results, all_recommended = apply_budget(
         ranked, token_budget=scaled_budget, compactor=compactor
     )
+    if hit_lines:
+        terms = salient_terms(query)
+        for result, cand in zip(all_results, ranked):
+            result["hits"] = _hit_lines(conn, cand, terms)
 
     # Paginate: slice results and filter recommended_reads to the current page.
     paginated = all_results[offset:offset + limit]
diff --git a/src/codebase_index/retrieval/priors.py b/src/codebase_index/retrieval/priors.py
index c9e0bec..6bf7dd6 100644
--- a/src/codebase_index/retrieval/priors.py
+++ b/src/codebase_index/retrieval/priors.py
@@ -22,6 +22,9 @@ class SourceRole(str, Enum):
     TEST = "test"
     DOCUMENTATION = "documentation"
     GENERATED_VENDOR_BUILD = "generated_vendor_build"
+    # Extended roles (RetrievalTuning.resource_priors).
+    LOCALIZATION = "localization"
+    WORKFLOW_ARTIFACT = "workflow_artifact"
     UNKNOWN = "unknown"
 
 
@@ -107,6 +110,22 @@ class SourceRole(str, Enum):
         ".zig",
     }
 )
+# Localisation catalogues repeat every user-facing noun of a feature, so they match
+# natural-language questions about it better than the code does.
+_LOCALIZATION_DIRS = frozenset({"i18n", "l10n", "lang", "langs", "locale", "locales",
+                                "translations"})
+_LOCALIZATION_SUFFIXES = frozenset({".po", ".pot", ".xliff", ".xlf", ".strings", ".resx",
+                                    ".arb", ".ftl"})
+_LOCALE_STEM_RE = re.compile(r"[a-z]{2,3}(?:[_-][a-z]{2,4})?", re.IGNORECASE)
+# Suffixes a catalogue under a localisation directory may have.
+_DATA_SUFFIXES = frozenset({".json", ".json5", ".yaml", ".yml", ".toml", ".xml", ".csv",
+                            ".tsv", ".properties", ".mcmeta", ".nbt", ".snbt", ".ini",
+                            ".cfg", ".conf"})
+# Review diffs, patches and the scratch directories agents write plans into: they
+# quote the code (and the question's words) without being the code.
+_WORKFLOW_SUFFIXES = frozenset({".diff", ".patch", ".orig", ".rej"})
+_KEPT_DOT_DIRS = frozenset({".github", ".gitlab", ".circleci", ".devcontainer",
+                            ".husky", ".config"})
 _MINIFIED_NAME_RE = re.compile(r"(?:^|[._-])min(?:ified)?(?:[._-]|$)", re.IGNORECASE)
 _TEST_QUERY_RE = re.compile(
     r"\b(?:test|tests|testing|e2e|spec|specs|fixture|fixtures|mock|mocks|pytest|jest)\b",
@@ -134,6 +153,8 @@ class SourceRole(str, Enum):
     # answer of all. Measured as quality-neutral on the benchmark corpora, so this
     # value preserves the role ordering rather than chasing a score.
     SourceRole.GENERATED_VENDOR_BUILD: -0.25,
+    SourceRole.LOCALIZATION: -0.25,
+    SourceRole.WORKFLOW_ARTIFACT: -0.25,
     SourceRole.UNKNOWN: 0.0,
 }
 _TEST_QUERY_PRIOR = 0.05
@@ -146,7 +167,7 @@ def _path_parts(path: str) -> tuple[str, ...]:
     return tuple(part for part in PurePosixPath(normalized).parts if part not in {"", "."})
 
 
-def classify_source_role(path: str) -> SourceRole:
+def classify_source_role(path: str, *, extended: bool = False) -> SourceRole:
     """Classify *path* into a small set of ranking roles.
 
     Generated/vendor/build markers take precedence over test markers: a vendored
@@ -168,6 +189,17 @@ def classify_source_role(path: str) -> SourceRole:
         or any(part in _GENERATED_DIRS for part in lowered[:-1])
     ):
         return SourceRole.GENERATED_VENDOR_BUILD
+    if extended:
+        if suffix in _WORKFLOW_SUFFIXES or any(
+            part.startswith(".") and len(part) > 1 and part not in _KEPT_DOT_DIRS
+            for part in lowered[:-1]
+        ):
+            return SourceRole.WORKFLOW_ARTIFACT
+        if suffix in _LOCALIZATION_SUFFIXES or (
+            any(part in _LOCALIZATION_DIRS for part in lowered[:-1])
+            and (suffix in _DATA_SUFFIXES or _LOCALE_STEM_RE.fullmatch(stem))
+        ):
+            return SourceRole.LOCALIZATION
     if is_test_path(path):
         return SourceRole.TEST
     if (
@@ -206,6 +238,7 @@ def source_role_prior(
     *,
     query: str = "",
     intent: Intent | str | None = None,
+    extended: bool = False,
 ) -> float:
     """Return a deterministic, bounded additive score for a source path.
 
@@ -214,7 +247,7 @@ def source_role_prior(
     or vendored paths stay penalized even when they contain tests.
     """
 
-    role = classify_source_role(path)
+    role = classify_source_role(path, extended=extended)
     if role is SourceRole.TEST and is_test_intent(query, intent):
         return _TEST_QUERY_PRIOR
     return _ROLE_PRIORS[role]
diff --git a/src/codebase_index/retrieval/rerank.py b/src/codebase_index/retrieval/rerank.py
index 464bb8c..8d24b1c 100644
--- a/src/codebase_index/retrieval/rerank.py
+++ b/src/codebase_index/retrieval/rerank.py
@@ -28,6 +28,11 @@
 _DEGREE_CAP = 0.08
 
 
+def _stem(path: str) -> str:
+    name = path.rsplit("/", 1)[-1]
+    return name.split(".", 1)[0].lower()
+
+
 def rerank(
     candidates: list[Candidate],
     *,
@@ -75,6 +80,9 @@ def rerank(
         if any(t in c.path.lower() for t in terms):
             bonus += 0.05
             reasons.append(f"in {c.path.rsplit('/', 1)[0] or '.'}/")
+        if tuning.stem_match and not demoted and _stem(c.path) in terms:
+            bonus += tuning.stem_match_weight
+            reasons.append("file named after a query term")
 
         if c.in_degree:
             bonus += min(_DEGREE_CAP, math.log1p(c.in_degree) * _DEGREE_SCALE)
@@ -91,7 +99,9 @@ def rerank(
             bonus += min(_DEGREE_CAP, math.log1p(c.in_degree + c.out_degree) * (_DEGREE_SCALE / 2))
 
         if tuning.source_priors and ("/" in c.path or "\\" in c.path):
-            prior = source_role_prior(c.path, query=query, intent=intent)
+            prior = source_role_prior(
+                c.path, query=query, intent=intent, extended=tuning.resource_priors
+            )
             if prior:
                 bonus += prior
                 reasons.append(f"source prior {prior:+.2f}")
diff --git a/src/codebase_index/retrieval/searchers.py b/src/codebase_index/retrieval/searchers.py
index fbae798..9eba5ed 100644
--- a/src/codebase_index/retrieval/searchers.py
+++ b/src/codebase_index/retrieval/searchers.py
@@ -10,9 +10,13 @@
 import re
 import sqlite3
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Sequence
 
 from ..config import Config
+from ..discovery.classify import detect_language, is_test_path
+from ..parsers.languages import CONTAINER_KINDS
+from ..graph.builder import language_family
+from ..parsers.base import names_a_type
 from ..indexer.freshness import compute_freshness
 from ..models import (
     GraphCoverage,
@@ -21,6 +25,7 @@
     RefsResponse,
     SymbolDef,
     SymbolResponse,
+    unmatched_coverage,
 )
 from ..storage import repo
 from .fuzzy import identifier_similarity
@@ -323,6 +328,22 @@ def symbol_candidates(
         for row in _fuzzy_symbol_rows(conn, query, limit=limit, kind=kind):
             rows_by_key.setdefault((row["path"], row["line_start"], row["name"]), row)
 
+    # A constructor shares its class's name, and its `new X()` callers give it the
+    # higher in-degree, so it used to take the file's one slot on the page with a
+    # one-line body while the class it constructs never appeared. Keep the class.
+    types_found = {
+        (row["path"], row["name"]) for row in rows_by_key.values()
+        if row["kind"] in CONTAINER_KINDS
+    }
+    rows_by_key = {
+        key: row for key, row in rows_by_key.items()
+        if not (
+            row["kind"] == "method"
+            and (row["path"], row["name"]) in types_found
+            and (row["qualified"] or "").endswith(f"{row['name']}.{row['name']}")
+        )
+    }
+
     scored: list[tuple] = []
     for row in rows_by_key.values():
         subs = _name_subtokens(row["name"])
@@ -497,7 +518,19 @@ def _freshness(
 def symbol_lookup(
     conn: sqlite3.Connection, name: str, *, kind: Optional[str], exact: bool
 ) -> SymbolResponse:
-    rows = repo.symbols_by_name(conn, name, kind=kind, exact=exact)
+    rows = repo.symbols_by_name(conn, name, kind=kind, exact=True)
+    more = 0
+    if not exact:
+        prefixed = repo.symbols_by_name(conn, name, kind=kind, exact=False)
+        if rows:
+            # An exact hit is what was asked for; twenty `TreasuryX` prefix matches
+            # around it cost tokens and bury it.
+            more = len(prefixed) - len(rows)
+        else:
+            rows = prefixed
+    member = repo.split_member(name) if not rows else None
+    if member is not None:
+        rows = [r for r in repo.symbols_by_owner(conn, *member) if not kind or r["kind"] == kind]
     symbols = [
         SymbolDef(
             name=row["name"],
@@ -510,38 +543,137 @@ def symbol_lookup(
         )
         for row in rows
     ]
-    return SymbolResponse(query=name, index=_freshness(conn), symbols=symbols)
+    return SymbolResponse(
+        query=name, index=_freshness(conn), symbols=symbols, more_prefix_matches=more
+    )
 
 
-def refs_lookup(conn: sqlite3.Connection, name: str, *, kind: str) -> RefsResponse:
-    defs = repo.symbols_by_name(conn, name, exact=True)
-    sites = [
-        RefSite(
-            path=row["path"],
-            line=row["line"],
-            kind="call",
-            confidence=row["confidence"] if "confidence" in row.keys() else "extracted",
-        )
-        for row in repo.refs_for_name(conn, name)
-    ]
+def refs_lookup(
+    conn: sqlite3.Connection,
+    name: str,
+    *,
+    kind: str,
+    exclude_tests: bool = False,
+    paths: Sequence[str] = (),
+) -> RefsResponse:
+    """Definitions, calls and references of `name` (a bare or `Owner.member` name).
+
+    `exclude_tests` drops sites in test files; `paths` keeps only sites under one of
+    the given path prefixes. Both filter what is reported, including the count of
+    possible calls behind `coverage.partial`.
+    """
+    defs, member = repo.symbols_for_target(conn, name)
+    possible: list[sqlite3.Row] = []
+    if member is None:
+        rows = repo.refs_for_name(conn, name)
+    else:
+        # `Owner.member`: calls resolved to one of Owner's definitions, plus
+        # unresolved calls made on a receiver literally named Owner.
+        owner, short = member
+        def_ids = {int(row["id"]) for row in defs}
+        rows, possible = [], []
+        for row in repo.refs_for_name(conn, short):
+            if row["dst_id"] in def_ids or (row["dst_id"] is None and row["receiver"] == owner):
+                rows.append(row)
+            elif defs and row["edge_type"] == "call" and _may_call_member(row, defs):
+                possible.append(row)
+    if kind == "callers":
+        rows = [row for row in rows if row["edge_type"] == "call"]
+    keep = _site_filter(exclude_tests, paths)
+    rows = [row for row in rows if keep(row["path"])]
+    possible = [row for row in possible if keep(row["path"])]
+    sites = [_ref_site(row, row["edge_type"]) for row in rows]
+    sites += [_ref_site(row, "possible_call") for row in possible]
     if kind == "all":
         sites.extend(
             # A definition is the symbol itself — exact by construction.
-            RefSite(path=row["path"], line=row["line_start"], kind="definition")
+            RefSite(
+                path=row["path"], line=row["line_start"], kind="definition",
+                target=row["qualified"] or row["name"],
+            )
             for row in defs
+            if keep(row["path"])
         )
-    sites.sort(key=lambda site: (site.path, site.line, site.kind))
+    def_paths = [row["path"] for row in defs]
+    # Known sites by location; possible ones after them, nearest to a definition first.
+    sites.sort(key=lambda site: (
+        site.kind == "possible_call",
+        -_shared_dirs(site.path, def_paths) if site.kind == "possible_call" else 0,
+        site.path, site.line, site.kind,
+    ))
     # Coverage is judged by the symbol's defining language(s); fall back to the
     # call-site files when the symbol has no indexed definition.
-    coverage_paths = [row["path"] for row in defs] or [s.path for s in sites]
-    return RefsResponse(
-        query=name,
-        index=_freshness(conn),
-        sites=sites,
-        coverage=GraphCoverage.for_paths(coverage_paths),
+    if not (defs or sites):
+        coverage = unmatched_coverage(name)
+    else:
+        coverage = GraphCoverage.for_paths(def_paths or [s.path for s in sites])
+    if possible:
+        coverage = GraphCoverage(
+            partial=True,
+            languages=coverage.languages,
+            reason=(
+                f"{len(possible)} call(s) to `{member[1] if member else name}` have a "
+                "receiver the index cannot type (a variable or an expression such as "
+                "`chest.holdings()`), so any of them may call this. They are listed as "
+                "`possible_call`, nearest to the definition first; read the ones that "
+                "matter to confirm."
+            ),
+        )
+    return RefsResponse(query=name, index=_freshness(conn), sites=sites, coverage=coverage)
+
+
+def _site_filter(exclude_tests: bool, paths: Sequence[str]):
+    prefixes = tuple(p.replace("\\", "/").strip("/") + "/" for p in paths if p.strip("/\\"))
+
+    def keep(path: str) -> bool:
+        if exclude_tests and is_test_path(path):
+            return False
+        return not prefixes or any((path + "/").startswith(p) for p in prefixes)
+
+    return keep
+
+
+def _ref_site(row: sqlite3.Row, kind: str) -> RefSite:
+    return RefSite(
+        path=row["path"],
+        line=row["line"],
+        kind=kind,
+        confidence=row["confidence"] if "confidence" in row.keys() else "extracted",
+        target=row["target"],
+        receiver=row["receiver"],
+        caller=row["src_qualified"] or row["src_name"],
     )
 
 
+def _may_call_member(row: sqlite3.Row, defs: list[sqlite3.Row]) -> bool:
+    """An unresolved same-named call that could still land on one of `defs`.
+
+    A receiver naming another type (`ApprenticeService.take`) cannot; a variable,
+    constant or expression receiver might. Only calls written in a
+    language one of the definitions is written in are considered.
+    """
+    if row["dst_id"] is not None:
+        return False
+    if names_a_type(row["receiver"]):
+        return False
+    families = {language_family(detect_language(d["path"])) for d in defs}
+    return language_family(detect_language(row["path"])) in families
+
+
+def _shared_dirs(path: str, others: list[str]) -> int:
+    """Longest run of leading directories `path` shares with any of `others`."""
+    parts = path.split("/")[:-1]
+    best = 0
+    for other in others:
+        shared = 0
+        for a, b in zip(parts, other.split("/")[:-1]):
+            if a != b:
+                break
+            shared += 1
+        best = max(best, shared)
+    return best
+
+
 def vector_candidates(
     conn: sqlite3.Connection, query: str, backend, *, limit: int
 ) -> list["M4Candidate"]:
diff --git a/src/codebase_index/retrieval/tuning.py b/src/codebase_index/retrieval/tuning.py
index 6d47543..b389223 100644
--- a/src/codebase_index/retrieval/tuning.py
+++ b/src/codebase_index/retrieval/tuning.py
@@ -157,6 +157,46 @@ class RetrievalTuning:
     truth from commits, which touch tests. 0.5 is the only setting that improves
     both partitions (+0.015 test-answer, +0.020 implementation-answer)."""
 
+    resource_priors: bool = True
+    """Extend the source priors past code/test/docs: localisation catalogues and
+    workflow artifacts (review diffs, patches, agent scratch directories) are
+    demoted to the level of generated code.
+
+    Found on a Minecraft monorepo: for "how does the town treasury work" the page
+    held the English and Russian language files (every UI string about the treasury
+    lives there) and five review diffs of the commits that built it, while the
+    SavedData class the question was about fell off the page.
+
+    A wider variant also stripped data files (`.json`, `.yml`) of the implementation
+    bonus; it cost TerraForge a query whose answer is `.github/workflows/release.yml`
+    and was dropped: configuration is sometimes the answer."""
+
+    stem_match: bool = True
+    """Credit a file whose name *is* one of the query terms (`Treasury.java` for
+    "how does the treasury store items"). Name co-occurrence deliberately gives a
+    single matched term nothing, and the symbol bonus only fires for symbol-level
+    hits, so a file-level chunk of the class named after the subject got no credit
+    for it."""
+
+    stem_match_weight: float = 0.20
+    """Bonus for a file stem equal to a query term; see `stem_match`.
+
+    Swept 0.10 / 0.20 / 0.30 over 342 queries on six query sets: 0.20 improved or
+    held every corpus; 0.30 added recall on two and cost terra-incognita MRR."""
+
+    candidate_pool_floor: int = 20
+    """Minimum candidate pool when the pool is over-fetched (multiplier > 1)."""
+
+    question_pool_floor: int = 40
+    """Candidate-pool floor for a question-form query (see `intent.is_question`).
+
+    On 24 natural-language questions over a 5.9k-file monorepo, a 40-deep pool
+    raised MRR 0.436 -> 0.472 and recall@10 0.750 -> 0.833: the class a question
+    paraphrases is often ranked 20-40 by every retriever and only the reranker's
+    name signals can lift it. On 318 commit-subject queries a 40-deep pool was
+    MRR-neutral (-0.009, p=0.36) at +17 ms p50, so the wider pool is spent only
+    where it pays. 0 disables it."""
+
     # --- selection, continued -----------------------------------------------
     max_per_file: int = 1
     """Hits from one file kept in place before the rest are pushed to the tail.
@@ -199,6 +239,9 @@ def baseline(cls) -> RetrievalTuning:
             # and it kept up to three hits from any one file.
             candidate_pool_multiplier=1,
             max_per_file=3,
+            resource_priors=False,
+            stem_match=False,
+            question_pool_floor=0,
         )
 
     @classmethod
@@ -210,7 +253,10 @@ def v190(cls) -> RetrievalTuning:
         better than the release it replaces. Both must keep working, so a later
         default change can never silently redefine its own comparison point.
         """
-        return cls(name_cooccurrence=False, max_per_file=3)
+        return cls(
+            name_cooccurrence=False, max_per_file=3,
+            resource_priors=False, stem_match=False, question_pool_floor=0,
+        )
 
 
     def without(self, flag: str) -> RetrievalTuning:
diff --git a/src/codebase_index/service.py b/src/codebase_index/service.py
index 33f85d5..0eb4d93 100644
--- a/src/codebase_index/service.py
+++ b/src/codebase_index/service.py
@@ -79,6 +79,7 @@ def search_payload(
     backend: Any = None,
     raw: bool = False,
     session: Optional[str] = None,
+    hit_lines: bool = False,
 ) -> dict:
     """One search session: open the DB (vector-enabled when the backend is
     live), run retrieval, return the payload dict both surfaces serialize.
@@ -115,6 +116,7 @@ def search_payload(
                 compact_min_reduction=cfg.retrieval.compact_min_reduction,
                 evidence=evidence,
                 max_read_lines=cfg.retrieval.max_read_lines,
+                hit_lines=hit_lines,
             )
     if tag is not None and not enabled:
         payload["memory"] = {"session": tag, "available": False, "reason": "memory is disabled"}
diff --git a/src/codebase_index/skill_template/SKILL.md b/src/codebase_index/skill_template/SKILL.md
index 432005b..ba39234 100644
--- a/src/codebase_index/skill_template/SKILL.md
+++ b/src/codebase_index/skill_template/SKILL.md
@@ -6,106 +6,60 @@ allowed-tools: Bash(codebase-index search *), Bash(codebase-index explain *), Ba
 
 # Codebase Index
 
-Use the local index before reading repository files.
+Use the local index before reading repository files. It answers with ranked,
+numbered lines, so most answers need no Read and no Grep at all.
 
-The operating principle is **Find → Trace → Verify → Predict**:
-
-- **Find** the implementation with ranked retrieval.
-- **Trace** behavior through definitions, callers, dependencies, and paths.
-- **Verify** that evidence you already hold is still true before relying on it.
-- **Predict** change impact while preserving an explicit evidence trail.
-
-## Route the question
+## Route the question — always `--compact`
 
 | Intent | Command |
 |---|---|
-| Where is X implemented? | `codebase-index search "X" --session <tag> --json` |
-| How does X work? | `codebase-index explain "X" --session <tag> --json` |
-| What is this codebase? | `codebase-index architecture --json` |
-| Find a named symbol | `codebase-index symbol "X" --json` |
-| Who calls or references X? | `codebase-index refs "X" --json` |
-| What changes if X changes? | `codebase-index impact "X" --json` |
-| What does my current diff affect? | `codebase-index diff-impact --json` |
-| How are X and Y connected? | `codebase-index path "X" "Y" --json` |
-| Describe X and its neighborhood | `codebase-index describe "X" --json` |
+| Where / how does X work? | `codebase-index search "X" --compact --session <tag>` |
+| Overview of a feature | `codebase-index explain "X" --compact --session <tag>` |
+| Every caller / call site of X | `codebase-index refs "Owner.member" --compact` |
+| What breaks if X changes (incl. other modules) | `codebase-index impact "Owner.member" --compact` |
+| Find a definition | `codebase-index symbol "X"` |
+| A class: members, who uses it | `codebase-index describe "Class" --json` |
+| What does my diff affect? | `codebase-index diff-impact --json` |
 | Is what I read earlier still true? | `codebase-index verify --session <tag> --json` |
-| Produce a human graph | `codebase-index graph "X" --output <path>` |
-
-Use `search --mode symbol` for exact symbol work, `--mode fts` for text and
-error messages, and the default `hybrid` mode for mixed questions. Use pure
-`vector` mode only when embeddings are enabled and exact vocabulary is unknown.
-
-Read [references/commands.md](references/commands.md) only when command options
-or routing remain unclear.
-
-## Evidence protocol
-
-1. Pick one session tag for this conversation (for example `auth-fix-1`) and
-   pass `--session <tag>` to every `search` and `explain`.
-2. Run the best-matching command with `--json`.
-3. Check `index` before trusting the payload:
-   - missing → run `codebase-index index`, then repeat;
-   - stale with fewer than 20 changed files → run `codebase-index update`;
-   - stale with 20 or more changed files → run `codebase-index index`;
-   - fresh → continue.
-4. Start with ranks 1–3. Read only `recommended_reads` line ranges.
-5. Trace one additional hop only when the question requires behavior,
-   ownership, or impact.
-6. Before answering or editing from evidence gathered earlier in the task, run
-   `codebase-index verify --session <tag> --json` and reread anything whose
-   state is not `valid` or `relocated`.
-7. Answer with `file:line` evidence and state uncertainty explicitly.
-
-Do not open whole files when a line range is available. A snippet may already
-be sufficient. `skeletonized: true` means the response intentionally folded
-unrelated body lines; read the supplied range when the missing body matters.
-
-## Evidence memory
-
-- `reused: true` with `snippet: null` — this session already received that
-  exact text and its source is unchanged. Use your earlier copy; if you can no
-  longer see it, Read the range.
-- `memory.invalidated` — evidence this session received has changed since.
-  Treat your earlier copy as wrong and reread before relying on it.
-- `stale: true` — the index is older than the file. Run `codebase-index update`
-  or Read the range.
-- A tag belongs to one context. Never give it to a subagent or another
-  conversation. Start a new tag after the context is cleared or compacted, or
-  whenever earlier snippets are no longer visible to you.
-
-Verdict states and citing evidence in notes: [references/memory.md](references/memory.md).
-
-## Confidence contract
-
-- **high** — answer from the indexed evidence.
-- **medium** — read the recommended ranges and confirm the key claim with one
-  targeted lookup if necessary.
-- **low** or no results — follow `fallback_suggestions`, then use a narrow
-  Grep/Glob fallback.
-
-On `refs` and `impact`, inspect `coverage`. If `coverage.partial` is true, an
-empty result is inconclusive; confirm with targeted Grep before saying that
-nothing references the target.
-
-Edges carry `confidence`:
-
-- `extracted` — exact parser evidence;
-- `inferred` — heuristic resolution;
-- `ambiguous` — unresolved or non-unique.
-
-Never present an inferred or ambiguous chain as certain.
-
-## Answer contract
-
-Structure repository answers around:
-
-1. **Answer** — the direct conclusion.
-2. **Evidence** — the minimum supporting `file:line` references.
-3. **Confidence** — only when evidence is partial, inferred, stale, or missing.
-4. **Next check** — only when another check would materially reduce uncertainty.
-
-Do not narrate every search step. Do not claim absence from a partial graph.
-Do not replace evidence with a generated HTML graph.
 
-For payload fields and failure handling, read
-[references/response-contract.md](references/response-contract.md).
+`--compact` prints `path:start-end symbol` per result with the matching lines
+numbered underneath (`  24| public static final String FILE_ID = ...`). Cite
+those lines as `path:24` directly. Read a range only when the lines shown do not
+answer the question — and then only that range, never the whole file.
+
+Name members as `Owner.member` (`TownService.refresh`, `activation::place`,
+`CoreError::ObjectDamaged`) so same-named methods of other types are excluded.
+`refs --compact` lines are `path:line kind caller -> target`: the list of call
+sites with the calling function is usually the whole answer. Add
+`--exclude-tests` for production-only lists and `--path <prefix>` for one module.
+`kind reference` is a non-call use, e.g. an enum variant matched in a `match` arm.
+
+`impact --compact` starts with `# module <m>: build files depending on it: ...`
+— the answer to "does another module depend on this", with no build-file grep.
+
+## Protocol
+
+1. Pick one session tag per conversation (e.g. `auth-fix-1`); pass it to
+   `search`/`explain`. Results already sent in this session print as
+   `(already sent)` — use your earlier copy.
+2. A header saying `index stale` → run `codebase-index update` once; `NO INDEX`
+   → `codebase-index index`.
+3. Batch independent questions into one Bash call (`cmd1; echo ---; cmd2`).
+4. `# partial:` on refs/impact means the list may be incomplete. For
+   `Owner.member` it lists `possible_call` sites (calls on a variable the index
+   cannot type), nearest first: check those few lines, do not grep the repo.
+5. Before relying on evidence from earlier in a long task, run
+   `codebase-index verify --session <tag> --json`.
+6. Grep only when the index returns nothing relevant or for non-code text.
+
+Edge confidence: `extracted` exact, `inferred` heuristic (receiver matched a
+type), `ambiguous` unresolved. Never present an inferred chain as certain.
+
+## Answer
+
+Lead with the answer, then the minimum `file:line` evidence. State uncertainty
+only when evidence is partial, inferred or stale.
+
+Options and JSON fields: [references/commands.md](references/commands.md),
+[references/response-contract.md](references/response-contract.md),
+session memory: [references/memory.md](references/memory.md).
diff --git a/src/codebase_index/skill_template/references/commands.md b/src/codebase_index/skill_template/references/commands.md
index 79c91a6..197ffe7 100644
--- a/src/codebase_index/skill_template/references/commands.md
+++ b/src/codebase_index/skill_template/references/commands.md
@@ -37,6 +37,24 @@ codebase-index describe "<file-or-symbol>" --json
 
 - `architecture` reads module analysis cached at index time.
 - `refs` finds definitions, calls, and graph-backed references.
+  For a method whose name several types share, pass `Owner.member`
+  (`TownService.refresh`, or `module::fn` for a top-level function); each site
+  names its `caller` and the `target` it resolved to. Calls the index cannot type
+  (`chest.holdings().take(..)`) come back as `possible_call`, nearest first, with
+  `coverage.partial: true`: read those before claiming a complete list.
+  `impact` and `symbol` accept the same form.
+  Filters: `--exclude-tests`, `--path <prefix>` (repeatable). `--compact` prints
+  `path:line kind caller -> target [confidence]`, one site per line.
+- `search`, `explain` and `impact` also take `--compact`: agent text instead of
+  JSON. For search/explain, each result is `path:start-end symbols` followed by up
+  to eight numbered lines that carry the match (rarer query words first);
+  evidence already sent to the session prints as `(already sent)`. For impact,
+  one `d<hops> path:line name via edge` line per node, after a
+  `# module ...` line naming the build files that depend on the target's module.
+- `symbol` returns exact matches alone when there are any and reports how many
+  prefix matches it left out (`more_prefix_matches`); `--exact` drops them.
+- `describe` on a class, enum, struct or trait also lists its `members` and
+  folds their edges into `used_by` / `uses` (code outside the type).
 - `impact` walks dependents (`up`), dependencies (`down`), or both.
 - `diff-impact` aggregates impact for tracked changes relative to a verified
   Git commit; new or excluded files are reported as unresolved.
diff --git a/src/codebase_index/storage/db.py b/src/codebase_index/storage/db.py
index 7cb1da1..ca2c808 100644
--- a/src/codebase_index/storage/db.py
+++ b/src/codebase_index/storage/db.py
@@ -9,7 +9,8 @@
 
 # 2: chunks gained a denormalized `symbol_names` column (FTS symbol-name boost).
 # 3: edges gained a `confidence` column (extracted/inferred/ambiguous audit trail).
-SCHEMA_VERSION = 3
+# 4: edges gained a `dst_qualifier` column (call receiver, for Class.method resolution).
+SCHEMA_VERSION = 4
 
 
 class Database:
diff --git a/src/codebase_index/storage/repo.py b/src/codebase_index/storage/repo.py
index 3dbd716..36ee866 100644
--- a/src/codebase_index/storage/repo.py
+++ b/src/codebase_index/storage/repo.py
@@ -6,7 +6,7 @@
 import sqlite3
 from typing import Any, Iterable, Optional, Sequence
 
-from ..parsers.base import Chunk, Symbol
+from ..parsers.base import Chunk, Symbol, module_name
 
 
 def upsert_file(
@@ -254,14 +254,17 @@ def replace_edges(
         """
         INSERT INTO edges
             (edge_type, src_kind, src_id, dst_kind, dst_id, dst_name, file_id, line,
-             resolved, confidence)
+             resolved, confidence, dst_qualifier)
         VALUES
             (:edge_type, :src_kind, :src_id, :dst_kind, :dst_id, :dst_name, :file_id, :line,
-             :resolved, :confidence)
+             :resolved, :confidence, :dst_qualifier)
         """,
         # confidence defaults to 'extracted' for callers (and tests) that predate the
         # audit-trail column; the global graph pass refines it (see graph/builder.py).
-        [{"confidence": "extracted", **edge, "file_id": file_id} for edge in edges],
+        [
+            {"confidence": "extracted", "dst_qualifier": None, **edge, "file_id": file_id}
+            for edge in edges
+        ],
     )
     return len(edges)
 
@@ -271,22 +274,91 @@ def count_edges(conn: sqlite3.Connection) -> int:
 
 
 def refs_for_name(conn: sqlite3.Connection, name: str) -> list[sqlite3.Row]:
+    qualifier = (
+        "e.dst_qualifier" if _has_column(conn, "edges", "dst_qualifier") else "NULL"
+    )
     return conn.execute(
-        """
+        f"""
         SELECT e.line AS line, f.path AS path, e.edge_type AS edge_type,
                e.resolved AS resolved, e.src_id AS src_id, e.src_kind AS src_kind,
-               e.confidence AS confidence,
+               e.confidence AS confidence, e.dst_id AS dst_id,
+               {qualifier} AS receiver, dst.qualified AS target,
                src.name AS src_name, src.qualified AS src_qualified
         FROM edges e
         JOIN files f ON f.id = e.file_id
         LEFT JOIN symbols src ON src.id = e.src_id AND e.src_kind = 'symbol'
-        WHERE e.dst_name = ? AND e.edge_type = 'call'
+        LEFT JOIN symbols dst ON dst.id = e.dst_id AND e.dst_kind = 'symbol'
+        WHERE e.dst_name = ? AND e.edge_type IN ('call', 'reference')
         ORDER BY f.path, e.line
         """,
         (name,),
     ).fetchall()
 
 
+def symbols_by_owner(
+    conn: sqlite3.Connection, owner: str, name: str
+) -> list[sqlite3.Row]:
+    """Members `name` of a type called `owner` ('TownService', 'refresh'), or
+    top-level definitions `name` in a module called `owner` ('activation', 'place')."""
+    members = conn.execute(
+        """
+        SELECT s.*, f.path AS path
+        FROM symbols s JOIN files f ON f.id = s.file_id
+        WHERE s.name = :name
+          AND (s.qualified = :member
+               OR substr(s.qualified, -length(:suffix)) = :suffix)
+        ORDER BY f.path, s.line_start
+        """,
+        {"name": name, "member": f"{owner}.{name}", "suffix": f".{owner}.{name}"},
+    ).fetchall()
+    if members:
+        return members
+    return [
+        row for row in conn.execute(
+            "SELECT s.*, f.path AS path FROM symbols s JOIN files f ON f.id = s.file_id "
+            "WHERE s.name = ? AND (s.qualified = s.name OR s.qualified IS NULL) "
+            "ORDER BY f.path, s.line_start",
+            (name,),
+        )
+        if module_name(row["path"]) == owner
+    ]
+
+
+def split_member(query: str) -> Optional[tuple[str, str]]:
+    """'TownService.refresh' / 'pkg.TownService::refresh' -> ('TownService', 'refresh')."""
+    parts = re.split(r"\.|::|#", query.strip())
+    if len(parts) < 2 or not all(_IDENTIFIER.fullmatch(p) for p in parts):
+        return None
+    return parts[-2], parts[-1]
+
+
+_IDENTIFIER = re.compile(r"[A-Za-z_$][\w$]*")
+
+
+def symbols_for_target(
+    conn: sqlite3.Connection, target: str
+) -> tuple[list[sqlite3.Row], Optional[tuple[str, str]]]:
+    """Definitions a refs/impact/symbol target names, and the (owner, member) split.
+
+    An exact symbol name wins (the pre-existing behaviour); otherwise a qualified
+    `Owner.member` matches members of types named Owner. The split is returned
+    whenever the target is qualified, so callers can also match unresolved call
+    sites by their receiver.
+    """
+    rows = symbols_by_name(conn, target, exact=True)
+    if rows:
+        return rows, None
+    member = split_member(target)
+    if member is None:
+        return [], None
+    return symbols_by_owner(conn, *member), member
+
+
+def _has_column(conn: sqlite3.Connection, table: str, column: str) -> bool:
+    # An index built by an older schema is still read in place (see db.py).
+    return any(row[1] == column for row in conn.execute(f"PRAGMA table_info({table})"))
+
+
 def fts_search(
     conn: sqlite3.Connection, match_query: str, *, limit: int
 ) -> list[sqlite3.Row]:
@@ -355,7 +427,7 @@ def symbol_search(
     )
     return conn.execute(
         f"""
-        SELECT s.name, s.kind, s.signature, s.line_start, s.line_end,
+        SELECT s.name, s.kind, s.signature, s.line_start, s.line_end, s.qualified,
                s.in_degree, s.out_degree, f.path, f.mtime_ns, f.is_generated,
                (s.name = :exact COLLATE NOCASE) AS is_exact
         FROM symbols s
@@ -383,7 +455,7 @@ def symbol_search(
 def unresolved_edges(conn: sqlite3.Connection) -> list[sqlite3.Row]:
     return conn.execute(
         "SELECT e.id AS id, e.edge_type AS edge_type, e.dst_name AS dst_name, "
-        "       f.lang AS lang "
+        "       e.dst_qualifier AS dst_qualifier, f.lang AS lang "
         "FROM edges e JOIN files f ON f.id = e.file_id "
         "WHERE e.resolved = 0 AND e.dst_name IS NOT NULL ORDER BY e.id"
     ).fetchall()
@@ -469,14 +541,13 @@ def name_ref_counts(conn: sqlite3.Connection, names: Sequence[str]) -> dict[str,
     return {row["dst_name"]: int(row["c"]) for row in rows}
 
 
-def unique_symbol_ids_by_name(conn: sqlite3.Connection) -> dict[str, int]:
-    """Map symbol name -> id for names defined exactly once in the repo."""
-    return {
-        row["name"]: int(row["sym_id"])
-        for row in conn.execute(
-            "SELECT name, MIN(id) AS sym_id FROM symbols GROUP BY name HAVING COUNT(*) = 1"
-        )
-    }
+def symbols_for_resolution(conn: sqlite3.Connection) -> list[sqlite3.Row]:
+    """Every symbol with what the graph pass matches edges on (see graph/builder.py)."""
+    return conn.execute(
+        "SELECT s.id AS id, s.name AS name, s.qualified AS qualified, "
+        "       s.file_id AS file_id, f.path AS path, f.lang AS lang "
+        "FROM symbols s JOIN files f ON f.id = s.file_id ORDER BY s.id"
+    ).fetchall()
 
 
 def all_file_ids_with_paths(conn: sqlite3.Connection) -> list[sqlite3.Row]:
@@ -509,6 +580,15 @@ def symbols_in_file(conn: sqlite3.Connection, file_id: int) -> list[sqlite3.Row]
     ).fetchall()
 
 
+def members_of(conn: sqlite3.Connection, symbol_id: int) -> list[sqlite3.Row]:
+    """Direct children of a symbol (a class's methods, an enum's variants)."""
+    return conn.execute(
+        "SELECT id, name, kind, line_start, line_end, signature, in_degree FROM symbols "
+        "WHERE parent_id = ? ORDER BY line_start",
+        (symbol_id,),
+    ).fetchall()
+
+
 def incoming_edges(conn: sqlite3.Connection, kind: str, node_id: int) -> list[sqlite3.Row]:
     return conn.execute(
         "SELECT id, edge_type, src_kind, src_id, file_id, line, confidence FROM edges "
diff --git a/src/codebase_index/storage/schema.sql b/src/codebase_index/storage/schema.sql
index bed17bb..6b48e1a 100644
--- a/src/codebase_index/storage/schema.sql
+++ b/src/codebase_index/storage/schema.sql
@@ -69,7 +69,10 @@ CREATE TABLE IF NOT EXISTS edges (
     -- name); 'inferred' = a heuristic resolved it (import path-suffix); 'ambiguous'
     -- = a name/import we could not pin to a unique target. Set at build time by the
     -- global graph pass; never guessed by an LLM (the index is fully local).
-    confidence    TEXT NOT NULL DEFAULT 'extracted'
+    confidence    TEXT NOT NULL DEFAULT 'extracted',
+    -- Receiver of a call edge ('TownService' in `TownService.refresh(x)`), NULL for a
+    -- bare call. Lets the graph pass resolve a non-unique method name by its owner.
+    dst_qualifier TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_edges_src  ON edges(src_kind, src_id);
 CREATE INDEX IF NOT EXISTS idx_edges_dst  ON edges(dst_kind, dst_id);
diff --git a/tests/eval/run_eval.py b/tests/eval/run_eval.py
index d022ef7..699d7b3 100644
--- a/tests/eval/run_eval.py
+++ b/tests/eval/run_eval.py
@@ -56,6 +56,8 @@
     "dedup",
     "source_priors",
     "file_agreement",
+    "resource_priors",
+    "stem_match",
 )
 
 # Rows are looked up by label rather than position, so adding a variant cannot
diff --git a/tests/golden/describe_refresh.json b/tests/golden/describe_refresh.json
index 16ec90d..7ec071c 100644
--- a/tests/golden/describe_refresh.json
+++ b/tests/golden/describe_refresh.json
@@ -2,14 +2,18 @@
   "callees": [],
   "callers": [
     {
+      "caller": "AdminUser.renew",
       "confidence": "extracted",
       "line": 11,
-      "path": "src/api/service.py"
+      "path": "src/api/service.py",
+      "target": "refresh_access_token"
     },
     {
+      "caller": "login",
       "confidence": "extracted",
       "line": 11,
-      "path": "src/auth/token.py"
+      "path": "src/auth/token.py",
+      "target": "refresh_access_token"
     }
   ],
   "definitions": [
diff --git a/tests/golden/impact_user_model.json b/tests/golden/impact_user_model.json
index a5107f6..17a8ca2 100644
--- a/tests/golden/impact_user_model.json
+++ b/tests/golden/impact_user_model.json
@@ -16,6 +16,7 @@
     "head_commit": "<SHA>",
     "stale": false
   },
+  "modules": [],
   "nodes": [
     {
       "distance": 1,
diff --git a/tests/golden/mcp_describe_symbol.json b/tests/golden/mcp_describe_symbol.json
index f56684d..a8f2ab4 100644
--- a/tests/golden/mcp_describe_symbol.json
+++ b/tests/golden/mcp_describe_symbol.json
@@ -2,14 +2,18 @@
   "callees": [],
   "callers": [
     {
+      "caller": "AdminUser.renew",
       "confidence": "extracted",
       "line": 11,
-      "path": "src/api/service.py"
+      "path": "src/api/service.py",
+      "target": "refresh_access_token"
     },
     {
+      "caller": "login",
       "confidence": "extracted",
       "line": 11,
-      "path": "src/auth/token.py"
+      "path": "src/auth/token.py",
+      "target": "refresh_access_token"
     }
   ],
   "definitions": [
diff --git a/tests/golden/mcp_find_refs.json b/tests/golden/mcp_find_refs.json
index 13208fa..7da480e 100644
--- a/tests/golden/mcp_find_refs.json
+++ b/tests/golden/mcp_find_refs.json
@@ -15,22 +15,31 @@
   "schema_version": 1,
   "sites": [
     {
+      "caller": "AdminUser.renew",
       "confidence": "extracted",
       "kind": "call",
       "line": 11,
-      "path": "src/api/service.py"
+      "path": "src/api/service.py",
+      "receiver": null,
+      "target": "refresh_access_token"
     },
     {
+      "caller": null,
       "confidence": "extracted",
       "kind": "definition",
       "line": 4,
-      "path": "src/auth/token.py"
+      "path": "src/auth/token.py",
+      "receiver": null,
+      "target": "refresh_access_token"
     },
     {
+      "caller": "login",
       "confidence": "extracted",
       "kind": "call",
       "line": 11,
-      "path": "src/auth/token.py"
+      "path": "src/auth/token.py",
+      "receiver": null,
+      "target": "refresh_access_token"
     }
   ],
   "tool": "find_refs"
diff --git a/tests/golden/mcp_find_symbol.json b/tests/golden/mcp_find_symbol.json
index 697368d..173b4b8 100644
--- a/tests/golden/mcp_find_symbol.json
+++ b/tests/golden/mcp_find_symbol.json
@@ -6,6 +6,7 @@
     "head_commit": "<SHA>",
     "stale": false
   },
+  "more_prefix_matches": 0,
   "query": "User",
   "schema_version": 1,
   "symbols": [
diff --git a/tests/golden/mcp_impact_of.json b/tests/golden/mcp_impact_of.json
index 1ce4815..e493828 100644
--- a/tests/golden/mcp_impact_of.json
+++ b/tests/golden/mcp_impact_of.json
@@ -16,6 +16,7 @@
     "head_commit": "<SHA>",
     "stale": false
   },
+  "modules": [],
   "nodes": [
     {
       "distance": 1,
diff --git a/tests/golden/mcp_search_code.json b/tests/golden/mcp_search_code.json
index 247be25..42b2f8d 100644
--- a/tests/golden/mcp_search_code.json
+++ b/tests/golden/mcp_search_code.json
@@ -25,8 +25,8 @@
       "line_start": 4,
       "path": "src/auth/token.py",
       "rank": 1,
-      "reason": "in src/auth/ · 2 callers · source prior +0.08",
-      "score": 2.313,
+      "reason": "in src/auth/ · file named after a query term · 2 callers · source prior +0.08",
+      "score": 2.513,
       "skeletonized": false,
       "snippet": "def refresh_access_token(refresh_token: str) -> str:",
       "symbols": [
diff --git a/tests/golden/refs_refresh_access_token.json b/tests/golden/refs_refresh_access_token.json
index 1ce827e..8c996d6 100644
--- a/tests/golden/refs_refresh_access_token.json
+++ b/tests/golden/refs_refresh_access_token.json
@@ -14,22 +14,31 @@
   "query": "refresh_access_token",
   "sites": [
     {
+      "caller": "AdminUser.renew",
       "confidence": "extracted",
       "kind": "call",
       "line": 11,
-      "path": "src/api/service.py"
+      "path": "src/api/service.py",
+      "receiver": null,
+      "target": "refresh_access_token"
     },
     {
+      "caller": null,
       "confidence": "extracted",
       "kind": "definition",
       "line": 4,
-      "path": "src/auth/token.py"
+      "path": "src/auth/token.py",
+      "receiver": null,
+      "target": "refresh_access_token"
     },
     {
+      "caller": "login",
       "confidence": "extracted",
       "kind": "call",
       "line": 11,
-      "path": "src/auth/token.py"
+      "path": "src/auth/token.py",
+      "receiver": null,
+      "target": "refresh_access_token"
     }
   ]
 }
diff --git a/tests/golden/search_token.json b/tests/golden/search_token.json
index dd69cdd..68435d6 100644
--- a/tests/golden/search_token.json
+++ b/tests/golden/search_token.json
@@ -25,8 +25,8 @@
       "line_start": 4,
       "path": "src/auth/token.py",
       "rank": 1,
-      "reason": "in src/auth/ · 2 callers · source prior +0.08",
-      "score": 2.313,
+      "reason": "in src/auth/ · file named after a query term · 2 callers · source prior +0.08",
+      "score": 2.513,
       "skeletonized": false,
       "snippet": "def refresh_access_token(refresh_token: str) -> str:",
       "symbols": [
diff --git a/tests/golden/symbol_user.json b/tests/golden/symbol_user.json
index d5d1c6f..9be320d 100644
--- a/tests/golden/symbol_user.json
+++ b/tests/golden/symbol_user.json
@@ -6,6 +6,7 @@
     "head_commit": "<SHA>",
     "stale": false
   },
+  "more_prefix_matches": 0,
   "query": "User",
   "symbols": [
     {
diff --git a/tests/test_agent_ergonomics.py b/tests/test_agent_ergonomics.py
new file mode 100644
index 0000000..15c1b96
--- /dev/null
+++ b/tests/test_agent_ergonomics.py
@@ -0,0 +1,227 @@
+"""What an agent needs from refs/symbol/describe without falling back to Grep.
+
+Each case comes from a benchmark run in which an agent using the skill had to leave
+the index: enum variants handled in a Rust `match`, a class card with no members,
+twenty prefix matches around the one symbol it asked for, test sites mixed into a
+"production callers" question, Kotlin files with no call edges at all.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from codebase_index.cli import app
+from codebase_index.config import Config
+from codebase_index.graph.navigate import describe_payload
+from codebase_index.indexer.pipeline import build_index, update_index
+from codebase_index.parsers.treesitter import parse_file
+from codebase_index.retrieval.searchers import refs_lookup, symbol_lookup
+from codebase_index.storage.db import Database
+
+FILES = {
+    "launcher/src/error.rs": """\
+pub enum CoreError {
+    ObjectDamaged(String),
+    Gone,
+}
+""",
+    "launcher/src/engine.rs": """\
+use crate::error::CoreError;
+
+pub fn prepare(r: Result<(), CoreError>) -> u8 {
+    match r {
+        Err(CoreError::ObjectDamaged(_)) => 1,
+        Err(CoreError::Gone) => 2,
+        _ => 0,
+    }
+}
+""",
+    "launcher/src/activation.rs": """\
+use crate::error::CoreError;
+
+pub fn place(ok: bool) -> Result<(), CoreError> {
+    if ok { Ok(()) } else { Err(CoreError::ObjectDamaged(String::new())) }
+}
+""",
+    "polity/treasury/Treasury.java": """\
+package treasury;
+
+public final class Treasury {
+    public void touched() {
+        save();
+    }
+
+    private void save() {
+    }
+}
+""",
+    "polity/treasury/TreasuryService.java": """\
+package treasury;
+
+public final class TreasuryService {
+    static void deposit(Treasury treasury) {
+        Treasury.touched();
+    }
+}
+""",
+    "polity/treasury/TreasuryRules.java": """\
+package treasury;
+
+public final class TreasuryRules {
+    static boolean mayDeposit() {
+        return true;
+    }
+}
+""",
+    "polity/src/test/java/treasury/TreasuryTest.java": """\
+package treasury;
+
+class TreasuryTest {
+    void deposits() {
+        TreasuryService.deposit(null);
+    }
+}
+""",
+    "polity/src/main/kotlin/Hooks.kt": """\
+object Hooks {
+    fun run() {
+        TreasuryService.deposit(null)
+    }
+}
+""",
+}
+
+
+@pytest.fixture
+def repo_root(tmp_path: Path) -> Path:
+    root = tmp_path / "repo"
+    for rel, text in FILES.items():
+        path = root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+    return root
+
+
+@pytest.fixture
+def db(repo_root: Path, tmp_path: Path):
+    cfg = Config()
+    cfg.root = str(repo_root)
+    database = Database(tmp_path / "index.sqlite").open()
+    build_index(cfg, database, root=repo_root)
+    yield database
+    database.close()
+
+
+def _sites(resp, kind=None):
+    return [(s.path, s.line) for s in resp.sites if kind is None or s.kind == kind]
+
+
+def test_kotlin_calls_are_extracted_with_their_receiver():
+    edges = parse_file("kotlin", FILES["polity/src/main/kotlin/Hooks.kt"]).edges
+    assert [(e.callee_name, e.receiver) for e in edges if e.edge_type == "call"] == [
+        ("deposit", "TreasuryService")
+    ]
+
+
+def test_rust_enum_variants_are_symbols(db):
+    resp = symbol_lookup(db.conn, "CoreError.ObjectDamaged", kind=None, exact=True)
+    assert [(s.kind, s.path, s.line_start) for s in resp.symbols] == [
+        ("variant", "launcher/src/error.rs", 2)
+    ]
+
+
+def test_refs_finds_where_a_rust_variant_is_matched(db):
+    resp = refs_lookup(db.conn, "CoreError::ObjectDamaged", kind="all")
+    assert ("launcher/src/engine.rs", 5) in _sites(resp, "reference")
+    assert ("launcher/src/activation.rs", 4) in _sites(resp, "call")
+    assert ("launcher/src/error.rs", 2) in _sites(resp, "definition")
+    matched = next(s for s in resp.sites if s.kind == "reference")
+    assert matched.caller == "prepare" and matched.target == "CoreError.ObjectDamaged"
+
+
+def test_refs_callers_leaves_out_non_call_references(db):
+    resp = refs_lookup(db.conn, "CoreError::ObjectDamaged", kind="callers")
+    assert {s.kind for s in resp.sites} == {"call"}
+
+
+def test_refs_filters_tests_and_paths(db):
+    every = _sites(refs_lookup(db.conn, "TreasuryService.deposit", kind="callers"))
+    assert ("polity/src/test/java/treasury/TreasuryTest.java", 5) in every
+    prod = refs_lookup(db.conn, "TreasuryService.deposit", kind="callers", exclude_tests=True)
+    assert _sites(prod) == [("polity/src/main/kotlin/Hooks.kt", 3)]
+    only = refs_lookup(db.conn, "TreasuryService.deposit", kind="callers",
+                       paths=["polity/src/test"])
+    assert _sites(only) == [("polity/src/test/java/treasury/TreasuryTest.java", 5)]
+
+
+def test_symbol_returns_exact_matches_alone_and_counts_the_rest(db):
+    resp = symbol_lookup(db.conn, "Treasury", kind=None, exact=False)
+    assert [s.qualified for s in resp.symbols] == ["Treasury"]
+    assert resp.more_prefix_matches == 3        # TreasuryService, TreasuryRules, TreasuryTest
+    prefix = symbol_lookup(db.conn, "TreasuryR", kind=None, exact=False)
+    assert [s.name for s in prefix.symbols] == ["TreasuryRules"]
+
+
+def test_describe_a_class_lists_members_and_who_uses_them(db):
+    card = describe_payload(db.conn, "Treasury")
+    assert [m["name"] for m in card["members"]] == ["touched", "save"]
+    assert card["used_by"] == [{
+        "member": "touched", "caller": "deposit",
+        "path": "polity/treasury/TreasuryService.java", "line": 5,
+        "confidence": "extracted",
+    }]
+    assert card["used_by_total"] == 1
+
+
+def test_describe_accepts_owner_member_and_names_callers(db):
+    card = describe_payload(db.conn, "Treasury.touched")
+    assert card["found"] is True
+    assert [(c["path"], c["caller"]) for c in card["callers"]] == [
+        ("polity/treasury/TreasuryService.java", "TreasuryService.deposit")
+    ]
+
+
+def test_refs_cli_compact_and_session(repo_root: Path, db):
+    runner = CliRunner()
+    db.close()  # the CLI builds its own index under the repo
+    result = runner.invoke(app, [
+        "--root", str(repo_root), "refs", "TreasuryService.deposit", "--kind", "callers",
+        "--exclude-tests", "--compact", "--session", "bench",
+    ])
+    assert result.exit_code == 0, result.output
+    lines = [ln for ln in result.output.splitlines() if not ln.startswith("[codebase-index]")]
+    assert lines == [
+        "# TreasuryService.deposit: 1 call",
+        "polity/src/main/kotlin/Hooks.kt:3 call Hooks.run -> TreasuryService.deposit",
+    ]
+    for cmd in (["symbol", "Treasury"], ["impact", "Treasury"], ["refs", "Treasury"]):
+        res = runner.invoke(app, ["--root", str(repo_root), *cmd, "--session", "bench",
+                                  "--json"])
+        assert res.exit_code == 0, res.output
+        json.loads(res.output)
+
+
+def test_update_parses_a_large_change_set_like_a_full_build(repo_root: Path, tmp_path: Path):
+    cfg = Config()
+    cfg.root = str(repo_root)
+    for i in range(60):  # past the parallel-parse threshold
+        (repo_root / "gen").mkdir(exist_ok=True)
+        (repo_root / "gen" / f"M{i}.java").write_text(
+            f"class M{i} {{ void f() {{ TreasuryService.deposit(null); }} }}\n", encoding="utf-8"
+        )
+    with Database(tmp_path / "a.sqlite") as full:
+        build_index(cfg, full, root=repo_root)
+        want = full.conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0]
+    with Database(tmp_path / "b.sqlite") as inc:
+        for i in range(60):
+            (repo_root / "gen" / f"M{i}.java").rename(repo_root / "gen" / f"M{i}.java.bak")
+        build_index(cfg, inc, root=repo_root)
+        for i in range(60):
+            (repo_root / "gen" / f"M{i}.java.bak").rename(repo_root / "gen" / f"M{i}.java")
+        stats = update_index(cfg, inc, root=repo_root)
+        assert stats.indexed == 60
+        assert inc.conn.execute("SELECT COUNT(*) FROM edges").fetchone()[0] == want
diff --git a/tests/test_compact_output.py b/tests/test_compact_output.py
new file mode 100644
index 0000000..f2d9895
--- /dev/null
+++ b/tests/test_compact_output.py
@@ -0,0 +1,114 @@
+"""Agent text output: ranked locations with numbered lines, and build modules.
+
+The point of `--compact` is to hand an agent what `grep -n` would, already ranked
+and cut to the matches, so it can cite `file:line` without another Read or Grep.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from typer.testing import CliRunner
+
+from codebase_index.cli import app
+from codebase_index.graph.modules import modules_for_paths, owning_module
+
+FILES = {
+    "settings.gradle.kts": 'include("polity")\ninclude("api")\n',
+    "api/build.gradle.kts": "plugins { java }\n",
+    "polity/build.gradle.kts": 'dependencies {\n    implementation(project(":api"))\n}\n',
+    "api/src/main/java/api/Ledger.java": """\
+package api;
+
+/** Where coins are written down. */
+public final class Ledger {
+    public Ledger() {}
+
+    public void record(String line) {
+        lines.add(line);
+    }
+}
+""",
+    "polity/src/main/java/polity/Treasury.java": """\
+package polity;
+
+/** The town treasury: its coins are persisted with the world save. */
+public final class Treasury {
+    public static final String FILE_ID = "polity_treasury";
+
+    public Treasury() {}
+
+    public void deposit(int coins) {
+        balance += coins;
+        new api.Ledger().record("deposit " + coins);
+    }
+
+    public void persist() {
+        save(FILE_ID);
+    }
+}
+""",
+    "polity/src/main/java/polity/Bank.java": """\
+package polity;
+
+public final class Bank {
+    void run(Treasury treasury) {
+        treasury.deposit(5);
+        Treasury t = new Treasury();
+    }
+}
+""",
+}
+
+
+@pytest.fixture
+def repo(tmp_path: Path) -> Path:
+    root = tmp_path / "repo"
+    for rel, text in FILES.items():
+        p = root / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(text, encoding="utf-8")
+    result = CliRunner().invoke(app, ["--root", str(root), "index"])
+    assert result.exit_code == 0, result.output
+    return root
+
+
+def _run(root: Path, *args: str) -> list[str]:
+    result = CliRunner().invoke(app, ["--root", str(root), *args])
+    assert result.exit_code == 0, result.output
+    return [ln for ln in result.output.splitlines() if not ln.startswith("[codebase-index]")]
+
+
+def test_search_compact_gives_numbered_lines_to_cite(repo: Path):
+    out = _run(repo, "search", "how is the treasury persisted", "--compact")
+    assert out[0].startswith("# ")
+    header = next(ln for ln in out if ln.startswith("polity/src/main/java/polity/Treasury.java:"))
+    body = out[out.index(header) + 1:]
+    numbered = [ln for ln in body if ln.startswith("  ") and "| " in ln]
+    assert "  5| public static final String FILE_ID = \"polity_treasury\";" in numbered
+    assert "  14| public void persist() {" in numbered      # "persisted" -> persist
+
+
+def test_class_is_returned_instead_of_its_same_named_constructor(repo: Path):
+    out = _run(repo, "search", "Treasury", "--compact")
+    header = next(ln for ln in out if "polity/Treasury.java:" in ln)
+    assert header.startswith("polity/src/main/java/polity/Treasury.java:4-")
+
+
+def test_impact_compact_names_the_module_and_its_dependents(repo: Path):
+    out = _run(repo, "impact", "Ledger.record", "--compact")
+    assert out[1] == (
+        "# module api: build files depending on it: polity/build.gradle.kts"
+        " · included by settings.gradle.kts:2"
+    )
+    polity = _run(repo, "impact", "Treasury.deposit", "--compact")
+    assert polity[1].startswith("# module polity: build files depending on it: none")
+
+
+def test_owning_module_is_the_nearest_directory_with_a_build_file(repo: Path):
+    assert owning_module(repo, "api/src/main/java/api/Ledger.java") == "api"
+    assert owning_module(repo, "settings.gradle.kts") is None
+    [api] = modules_for_paths(repo, ["api/src/main/java/api/Ledger.java"])
+    assert api["dependents"] == ["polity/build.gradle.kts"]
+    assert {r["kind"] for r in api["referenced_by"]} == {"member", "dependency"}
diff --git a/tests/test_migration_1x.py b/tests/test_migration_1x.py
index 2713d5f..515f2d4 100644
--- a/tests/test_migration_1x.py
+++ b/tests/test_migration_1x.py
@@ -2,8 +2,9 @@
 
 `tests/fixtures/index-1.10.0/index.sqlite` was built by the released 1.10.0 code (commit
 abb67df) over `tests/fixtures/sample_repo`, not synthesised by 2.0, so these tests check the
-upgrade path users actually take. 2.0 leaves the index schema at version 3; evidence memory
-lives in its own `memory.sqlite`, so no reindex is needed.
+upgrade path users actually take. The index is on schema 3 while the code is on 4 (edges
+gained `dst_qualifier`): read commands keep answering from the old index in place, and the
+first `update` rebuilds it. Evidence memory lives in its own `memory.sqlite` and survives.
 """
 
 from __future__ import annotations
@@ -63,9 +64,9 @@ def _cli_json(root: Path, *args: str) -> dict:
     return json.loads(result.output)
 
 
-def test_fixture_is_a_real_1_10_index_on_the_current_schema(upgraded):
+def test_fixture_is_a_real_1_10_index_on_an_older_schema(upgraded):
     _root, db = upgraded
-    assert peek_schema_version(db) == 3 == SCHEMA_VERSION
+    assert peek_schema_version(db) == 3 < SCHEMA_VERSION
     conn = sqlite3.connect(db)
     try:
         assert conn.execute("SELECT COUNT(*) FROM files").fetchone()[0] == 6
@@ -73,15 +74,17 @@ def test_fixture_is_a_real_1_10_index_on_the_current_schema(upgraded):
         conn.close()
 
 
-def test_1x_index_is_used_in_place_without_a_rebuild(upgraded):
+def test_1x_index_answers_in_place_until_update_rebuilds_it(upgraded):
     root, db = upgraded
     built_at = _meta(db, "built_at")
     search = _cli_json(root, "search", "token", "--json")
     assert search["results"] and "memory" not in search
+    refs = _cli_json(root, "refs", "refresh_access_token", "--json")
+    assert any(site["kind"] == "call" for site in refs["sites"])  # no dst_qualifier column
+    assert _meta(db, "built_at") == built_at                       # reads never rebuild
     update = _cli_json(root, "--json", "update")
-    assert update["indexed"] == 0 and update["deleted"] == 0   # same bytes: nothing reparsed
-    assert _meta(db, "built_at") == built_at                     # the 1.x database survived
-    assert peek_schema_version(db) == 3
+    assert update["indexed"] == 6                                  # full rebuild on schema 4
+    assert peek_schema_version(db) == SCHEMA_VERSION
 
 
 def test_memory_attaches_to_an_upgraded_project(upgraded):
diff --git a/tests/test_priors.py b/tests/test_priors.py
index 9a1dd88..7e084da 100644
--- a/tests/test_priors.py
+++ b/tests/test_priors.py
@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import pytest
+
 from codebase_index.retrieval.priors import (
     MAX_ABS_PRIOR,
     SourceRole,
@@ -32,8 +34,11 @@ def test_prior_preserves_order_and_is_bounded():
                 SourceRole.DOCUMENTATION: "docs/search.md",
                 SourceRole.GENERATED_VENDOR_BUILD: "dist/search.min.js",
                 SourceRole.UNKNOWN: "misc/data.bin",
+                SourceRole.LOCALIZATION: "src/i18n/en.json",
+                SourceRole.WORKFLOW_ARTIFACT: ".superpowers/review-1..2.diff",
             }[role],
             query="where is search implemented",
+            extended=True,
         )
         for role in SourceRole
     }
@@ -80,3 +85,26 @@ def test_role_classification_is_path_only_and_deterministic():
     path = r"C:\repo\src\contest\latest.py"
     assert classify_source_role(path) is SourceRole.IMPLEMENTATION
     assert classify_source_role(path) == classify_source_role(path)
+
+
+@pytest.mark.parametrize(
+    ("path", "role"),
+    [
+        ("realism-polity/src/main/resources/assets/realism_polity/lang/en_us.json",
+         SourceRole.LOCALIZATION),
+        ("launcher/app/src/i18n/en.json", SourceRole.LOCALIZATION),
+        ("app/locales/pt-BR/messages.po", SourceRole.LOCALIZATION),
+        (".superpowers/sdd/phase-2/review-e870589..e5bb4a0.diff", SourceRole.WORKFLOW_ARTIFACT),
+        ("patches/fix.patch", SourceRole.WORKFLOW_ARTIFACT),
+        # Kept: CI configuration is sometimes the answer, and data is not demoted.
+        (".github/workflows/release.yml", SourceRole.IMPLEMENTATION),
+        ("src/main/resources/data/realism/crops/wheat.json", SourceRole.IMPLEMENTATION),
+        ("src/lang/Parser.java", SourceRole.IMPLEMENTATION),
+    ],
+)
+def test_extended_roles(path, role):
+    assert classify_source_role(path, extended=True) is role
+
+
+def test_extended_roles_are_opt_in():
+    assert classify_source_role("launcher/app/src/i18n/en.json") is not SourceRole.LOCALIZATION
diff --git a/tests/test_qualified_refs.py b/tests/test_qualified_refs.py
new file mode 100644
index 0000000..754d229
--- /dev/null
+++ b/tests/test_qualified_refs.py
@@ -0,0 +1,320 @@
+"""`Owner.member` targets: refs/impact/symbol on a method name several types share.
+
+Mirrors the case that made refs/impact useless on a large Java repo: three types
+define `refresh`, callers in other files write `TownService.refresh(server)`, and
+both `refs "TownService.refresh"` and `impact "TownService.refresh"` came back empty
+with `partial: false`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from codebase_index.config import Config
+from codebase_index.graph.expand import impact_lookup
+from codebase_index.indexer.pipeline import build_index
+from codebase_index.parsers.treesitter import parse_file
+from codebase_index.retrieval.searchers import refs_lookup, symbol_lookup
+from codebase_index.storage import repo
+from codebase_index.storage.db import Database
+
+FILES = {
+    "town/TownService.java": """\
+package town;
+
+public final class TownService {
+    static void found(Server server) {
+        refresh(server);
+    }
+
+    public static void refresh(Server server) {
+        server.send();
+    }
+
+    public static void refresh(Server server, boolean quiet) {
+        server.send();
+    }
+}
+""",
+    "treasury/TreasuryService.java": """\
+package treasury;
+
+public final class TreasuryService {
+    static void sweep(Server server) {
+        TownService.refresh(server);
+    }
+}
+""",
+    "command/PolityCommand.java": """\
+package command;
+
+public final class PolityCommand {
+    static void rename(Server server) {
+        TownService.refresh(server);
+        PolityTuning.refresh();
+    }
+
+    static void refresh() {
+    }
+}
+""",
+    "treasury/Holdings.java": """\
+package treasury;
+
+public final class Holdings {
+    public List<Item> take(Item kind, int count) {
+        return null;
+    }
+}
+""",
+    "treasury/Withdraw.java": """\
+package treasury;
+
+public final class Withdraw {
+    static void run(Chest chest, Item kind) {
+        chest.holdings().take(kind, 1);
+        ApprenticeService.take(kind);
+    }
+}
+""",
+    "apprentice/ApprenticeService.java": """\
+package apprentice;
+
+public final class ApprenticeService {
+    public static Refusal take(Item kind) {
+        return null;
+    }
+}
+""",
+    "tools/take.py": """\
+def drain(queue, server):
+    queue.take()
+    server.found()
+""",
+    "config/PolityTuning.java": """\
+package config;
+
+public final class PolityTuning {
+    public static void refresh() {
+    }
+}
+""",
+}
+
+
+@pytest.fixture
+def db(tmp_path: Path):
+    root = tmp_path / "repo"
+    for rel, text in FILES.items():
+        path = root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+    cfg = Config()
+    cfg.root = str(root)
+    database = Database(tmp_path / "index.sqlite").open()
+    build_index(cfg, database, root=root)
+    yield database
+    database.close()
+
+
+def _calls(resp) -> list[tuple[str, int]]:
+    return [(s.path, s.line) for s in resp.sites if s.kind == "call"]
+
+
+def test_parser_records_the_call_receiver():
+    edges = parse_file("java", FILES["command/PolityCommand.java"]).edges
+    calls = [(e.callee_name, e.receiver) for e in edges if e.edge_type == "call"]
+    assert calls == [("refresh", "TownService"), ("refresh", "PolityTuning")]
+
+
+@pytest.mark.parametrize(
+    ("query", "expected"),
+    [
+        ("TownService.refresh", ("TownService", "refresh")),
+        ("town.TownService.refresh", ("TownService", "refresh")),
+        ("Foo::new", ("Foo", "new")),
+        ("Foo#bar", ("Foo", "bar")),
+        ("refresh", None),
+        ("src/town/TownService.java", None),
+    ],
+)
+def test_split_member(query, expected):
+    assert repo.split_member(query) == expected
+
+
+def test_refs_by_owner_finds_cross_file_and_same_file_calls(db):
+    resp = refs_lookup(db.conn, "TownService.refresh", kind="callers")
+    assert _calls(resp) == [
+        ("command/PolityCommand.java", 5),
+        ("town/TownService.java", 5),
+        ("treasury/TreasuryService.java", 5),
+    ]
+    assert {s.target for s in resp.sites} == {"TownService.refresh"}
+    assert resp.coverage.partial is False
+
+
+def test_refs_by_owner_excludes_same_named_methods_of_other_types(db):
+    tuning = refs_lookup(db.conn, "PolityTuning.refresh", kind="callers")
+    assert _calls(tuning) == [("command/PolityCommand.java", 6)]
+
+
+def test_foreign_receiver_does_not_bind_to_a_local_method_of_that_name(db):
+    # PolityCommand defines its own `refresh`; `TownService.refresh(...)` there must
+    # not resolve to it.
+    own = refs_lookup(db.conn, "PolityCommand.refresh", kind="callers")
+    assert _calls(own) == []
+
+
+def test_refs_sites_name_their_calling_method(db):
+    resp = refs_lookup(db.conn, "TownService.refresh", kind="callers")
+    callers = {(s.path, s.caller) for s in resp.sites}
+    assert ("treasury/TreasuryService.java", "TreasuryService.sweep") in callers
+    assert ("town/TownService.java", "TownService.found") in callers
+
+
+def test_untyped_receiver_calls_are_listed_as_possible_and_mark_coverage_partial(db):
+    resp = refs_lookup(db.conn, "Holdings.take", kind="callers")
+    possible = [(s.path, s.line, s.caller) for s in resp.sites if s.kind == "possible_call"]
+    # The chained call may hit Holdings.take; ApprenticeService.take names another
+    # type and the Python `queue.take()` cannot call a Java method.
+    assert possible == [("treasury/Withdraw.java", 5, "Withdraw.run")]
+    assert resp.coverage.partial is True
+    assert "1 call(s) to `take`" in resp.coverage.reason
+
+
+def test_calls_do_not_bind_across_languages_or_to_another_types_unique_member(db):
+    # `found` is defined once (TownService.found); the Python `server.found()` is not
+    # a call to it. Nor is `ApprenticeService.take` a call to Holdings.take.
+    assert _calls(refs_lookup(db.conn, "TownService.found", kind="callers")) == []
+    take = refs_lookup(db.conn, "ApprenticeService.take", kind="callers")
+    assert _calls(take) == [("treasury/Withdraw.java", 6)]
+
+
+def test_bare_name_refs_label_each_site_with_its_target(db):
+    resp = refs_lookup(db.conn, "refresh", kind="callers")
+    targets = {(s.path, s.line): s.target for s in resp.sites}
+    assert targets[("command/PolityCommand.java", 6)] == "PolityTuning.refresh"
+    assert targets[("treasury/TreasuryService.java", 5)] == "TownService.refresh"
+
+
+def test_impact_accepts_owner_member(db):
+    resp = impact_lookup(db.conn, "TownService.refresh", depth=1, direction="up")
+    callers = {(n.path, n.name) for n in resp.nodes}
+    assert ("treasury/TreasuryService.java", "sweep") in callers
+    assert ("command/PolityCommand.java", "rename") in callers
+    assert ("town/TownService.java", "found") in callers
+    assert resp.coverage.partial is False
+
+
+def test_symbol_accepts_owner_member(db):
+    resp = symbol_lookup(db.conn, "TownService.refresh", kind=None, exact=True)
+    assert [s.line_start for s in resp.symbols] == [8, 12]
+
+
+def test_unknown_target_is_reported_as_inconclusive(db):
+    for resp in (
+        refs_lookup(db.conn, "Nowhere.refresh", kind="all"),
+        impact_lookup(db.conn, "Nowhere.refresh", depth=2, direction="up"),
+    ):
+        assert resp.coverage.partial is True
+        assert "Nowhere.refresh" in resp.coverage.reason
+
+
+RUST_AND_JAVA = {
+    "launcher/src/activation.rs": """\
+pub fn place(store: &Store, target: &Path) -> Result<()> {
+    Ok(())
+}
+
+pub fn activate(store: &Store, target: &Path) -> Result<()> {
+    place(store, target)?;
+    Ok(())
+}
+""",
+    "launcher/src/presets.rs": """\
+use crate::activation::place;
+
+pub fn apply(store: &Store, target: &Path) -> Result<()> {
+    place(store, target)?;
+    crate::activation::place(store, target)
+}
+
+struct Cache;
+
+impl Cache {
+    fn new() -> Self {
+        Cache
+    }
+    fn fresh() -> Self {
+        Self::new()
+    }
+}
+""",
+    "mod/Varieties.java": """\
+public final class Varieties {
+    static void place(Block block) {
+    }
+
+    static String describe() {
+        return "";
+    }
+
+    static void harvest(Block block) {
+        Kind.WOOD.describe();
+    }
+}
+""",
+}
+
+
+@pytest.fixture
+def mixed_db(tmp_path: Path):
+    root = tmp_path / "mixed"
+    for rel, text in RUST_AND_JAVA.items():
+        path = root / rel
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, encoding="utf-8")
+    cfg = Config()
+    cfg.root = str(root)
+    database = Database(tmp_path / "mixed.sqlite").open()
+    build_index(cfg, database, root=root)
+    yield database
+    database.close()
+
+
+def test_a_name_unique_within_its_language_resolves_despite_other_languages(mixed_db):
+    # Java also defines `place`; the Rust calls still resolve to the Rust one.
+    resp = refs_lookup(mixed_db.conn, "activation::place", kind="callers")
+    assert _calls(resp) == [
+        ("launcher/src/activation.rs", 6),
+        ("launcher/src/presets.rs", 4),
+        ("launcher/src/presets.rs", 5),
+    ]
+    assert {s.confidence for s in resp.sites} <= {"extracted", "inferred"}
+
+
+def test_module_qualified_symbol_lookup(mixed_db):
+    resp = symbol_lookup(mixed_db.conn, "activation::place", kind=None, exact=True)
+    assert [(s.path, s.line_start) for s in resp.symbols] == [("launcher/src/activation.rs", 1)]
+
+
+def test_self_and_constant_receivers_keep_resolving(mixed_db):
+    assert _calls(refs_lookup(mixed_db.conn, "Cache.new", kind="callers")) == [
+        ("launcher/src/presets.rs", 15)
+    ]
+    assert _calls(refs_lookup(mixed_db.conn, "Varieties.describe", kind="callers")) == [
+        ("mod/Varieties.java", 10)
+    ]
+
+
+@pytest.mark.parametrize(
+    ("path", "module"),
+    [("src/activation.rs", "activation"), ("auth/__init__.py", "auth"),
+     ("auth/mod.rs", "auth"), ("web/index.ts", "web"), ("token.py", "token")],
+)
+def test_module_name(path, module):
+    from codebase_index.parsers.base import module_name
+
+    assert module_name(path) == module

From 9417e92723afe5f1669be78640210d374f5072aa Mon Sep 17 00:00:00 2001
From: denfry <dabinayo@pm.me>
Date: Thu, 24 Sep 2026 21:54:00 +0300
Subject: [PATCH 2/2] =?UTF-8?q?release:=20v2.1.0=20=E2=80=94=20agent=20eff?=
 =?UTF-8?q?iciency?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Version bump with every mirror synced (plugin.json, requirements.lock,
skill stamps), release notes, and the logged runs behind them: the agent
pilot (skill vs Grep/Read, three runs per arm: -19% tokens, -25% tool
calls, all answers correct) and the 2.1.0 retrieval eval.
---
 .claude-plugin/plugin.json                    |  2 +-
 .claude/skills/codebase-index/.skill_version  |  2 +-
 .codex/skills/codebase-index/.skill_version   |  2 +-
 .../skills/codebase-index/.skill_version      |  2 +-
 CHANGELOG.md                                  | 98 ++++++++++++++++++-
 README.md                                     | 19 ++--
 docs/BENCHMARKS.md                            | 32 ++++--
 docs/installer.md                             |  2 +-
 requirements.lock                             |  2 +-
 src/codebase_index/__init__.py                |  2 +-
 tests/eval/results/2026-09-24-agent-pilot.md  | 72 ++++++++++++++
 .../results/2026-09-24-retrieval-2.1.0.txt    | 47 +++++++++
 .../results/2026-09-24-terra-nl-queries.yml   | 75 ++++++++++++++
 13 files changed, 336 insertions(+), 21 deletions(-)
 create mode 100644 tests/eval/results/2026-09-24-agent-pilot.md
 create mode 100644 tests/eval/results/2026-09-24-retrieval-2.1.0.txt
 create mode 100644 tests/eval/results/2026-09-24-terra-nl-queries.yml

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 2a30b5b..8f6dd3c 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -3,7 +3,7 @@
   "name": "codebase-index",
   "displayName": "Codebase Index",
   "description": "Give Claude a precise local map of your codebase: find implementations, trace behavior, and predict change impact with file-line evidence.",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "author": {
     "name": "codebase-index contributors"
   },
diff --git a/.claude/skills/codebase-index/.skill_version b/.claude/skills/codebase-index/.skill_version
index 227cea2..7ec1d6d 100644
--- a/.claude/skills/codebase-index/.skill_version
+++ b/.claude/skills/codebase-index/.skill_version
@@ -1 +1 @@
-2.0.0
+2.1.0
diff --git a/.codex/skills/codebase-index/.skill_version b/.codex/skills/codebase-index/.skill_version
index 227cea2..7ec1d6d 100644
--- a/.codex/skills/codebase-index/.skill_version
+++ b/.codex/skills/codebase-index/.skill_version
@@ -1 +1 @@
-2.0.0
+2.1.0
diff --git a/.opencode/skills/codebase-index/.skill_version b/.opencode/skills/codebase-index/.skill_version
index 227cea2..7ec1d6d 100644
--- a/.opencode/skills/codebase-index/.skill_version
+++ b/.opencode/skills/codebase-index/.skill_version
@@ -1 +1 @@
-2.0.0
+2.1.0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1e6a1f1..442ed6c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,101 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-09-24
+
+Agent-efficiency release. An agent answering five code questions on a 5.9k-file
+Java/Rust monorepo spent **19% fewer tokens (83.5k vs 103.0k) and 25% fewer tool calls
+(9 vs 12)** with the skill than with Grep/Read alone, three runs per arm, with no
+overlap between the arms' ranges; before this release the two were at parity. The
+gain comes from answer-ready output (`--compact`: ranked files with numbered matching
+lines), `refs`/`impact` that resolve `Owner.member` targets exactly and say when a list
+may be incomplete, build-module awareness in `impact`, and ranking measured over 342
+queries (MRR +0.010, p=0.031). Index schema 4: the first `update` rebuilds the index
+once.
+
+### Fixed
+
+- `refs`, `impact` and `symbol` accept a qualified `Owner.member` target
+  (`TownService.refresh`, also `pkg.Owner.member`, `Owner::member`, `Owner#member`),
+  where the owner is a type or a module (`activation::place`). Before, a qualified name
+  matched nothing and a bare name that several types share (`refresh`) returned every
+  same-named method's callers mixed together.
+- Calls written against a type or module (`TownService.refresh(server)`, `Foo::new()`,
+  `activation::place(..)`) now resolve across files when exactly one type or module of
+  that name defines the callee, so `impact` walks them. These edges are marked
+  `inferred`.
+- Call resolution no longer invents edges: a call never binds across languages (a
+  Python `queue.take()` to a Java `take`), a call on another type
+  (`ApprenticeService.take`) no longer binds to the repo's only `take` when that one
+  belongs to a different type, and a call on a type the file does not define no
+  longer binds to a same-named method in the calling file. Name uniqueness is now
+  judged per language family (JVM, JS/TS, C/C++), so a Rust `place` resolves even
+  when Java also defines one.
+- `refs "Owner.member"` no longer reports a confident empty answer when calls it
+  cannot type exist (`chest.holdings().take(..)`): they are listed as
+  `possible_call`, nearest to the definition first, and `coverage.partial` is true.
+- `refs` and `impact` report `coverage.partial: true` with a reason when the target
+  matches no indexed definition or call site, instead of an empty answer that looked
+  like "no callers".
+- `update` parses changed files in a process pool, like a full build. It used to parse
+  them one at a time, so a large change set was slower to update than to rebuild
+  (2009 changed files: 149 s, against 13 s for a full build of all 5904).
+- A class is returned instead of its same-named constructor. The constructor's
+  `new X()` callers gave it the higher in-degree, so it took the file's one slot on
+  the page with a one-line body while the class never appeared.
+- Kotlin call sites are extracted (with their receiver). Kotlin's `call_expression`
+  has no named fields, so no Kotlin call edge was ever recorded.
+
+### Added
+
+- Rust enum variants, Java enum constants and C# enum members are indexed as
+  `variant` symbols (`CoreError.ObjectDamaged`), and a Rust `Owner::name` path used in a
+  pattern or as a value (`Err(CoreError::ObjectDamaged(_)) =>`, `if let Kind::A = ..`)
+  is recorded as a `reference` edge. `refs` reports these as `kind: "reference"`, so it
+  finds where a variant is handled, not only where it is constructed.
+- `refs --exclude-tests`, `refs --path <prefix>` (repeatable; also on the MCP
+  `find_refs` tool) and `refs --compact`, which prints one line per site:
+  `path:line kind caller -> target [confidence]`.
+- `describe` on a class, enum, struct or trait lists its `members` and folds their
+  edges from and to code outside the type into `used_by` / `uses`. It used to report
+  zero callers and callees for a class, whose methods, not the class, are called.
+- `--session` is accepted by `symbol`, `refs` and `impact`, so one tag can be passed to
+  every read command.
+- `search --compact` / `explain --compact`: agent text instead of JSON. Each result is
+  `path:start-end symbols` with up to eight numbered lines underneath that carry the
+  match (rarer query words first), so an agent can cite `file:line` without a Read or
+  a `grep -n`. On a benchmark query the packet went from 9.6 KB of JSON to 3.7 KB.
+  Evidence already sent to the session prints as `(already sent)`.
+- `impact --compact`, and a `modules` field on `impact`: the build-system module the
+  target lives in (Gradle, Maven, Cargo, npm, Go, Python) and the lines of other
+  build files that name it, split into workspace membership and dependencies. "Does
+  another module depend on this?" no longer needs a grep over build files.
+- The skill routes every question through `--compact` and is 40% shorter.
+
+### Changed
+
+- Ranking, measured over 342 queries on six query sets (five repositories, including
+  24 natural-language "how does X work" questions): MRR +0.010 (p=0.036), recall@10
+  +0.015 (p=0.038), nDCG@10 +0.009 (p=0.018), useful@budget +0.020 (p=0.015), 15 fewer
+  snippet tokens per query; no corpus regressed. On the natural-language questions MRR
+  went 0.428 → 0.475 and recall@10 0.708 → 0.833. Three signals, each ablatable:
+  - `resource_priors`: localisation catalogues (`lang/en_us.json`, `i18n/*.json`,
+    `.po`) and workflow artifacts (review `.diff`/`.patch` files, agent scratch
+    directories such as `.superpowers/`) are demoted like generated code;
+  - `stem_match`: a file named after a query term (`Treasury.java` for a question
+    about the treasury) gets a small bonus;
+  - `question_pool_floor`: a question-form query ("how is a crop loaded") gets a
+    40-deep candidate pool, so the class it paraphrases reaches the reranker.
+- `symbol` returns exact matches alone when there are any, with a count of the prefix
+  matches it left out (`more_prefix_matches`), instead of burying the one symbol asked
+  for among twenty `TreasuryX` prefix matches.
+
+- Every `refs` site carries `caller` (the function it sits in), `target` (the
+  definition it resolved to) and `receiver` (what the call was made on), so callers can
+  be named and same-named methods told apart without reading each file.
+- Index schema 4: call edges store their receiver. The first `update` after upgrading
+  rebuilds the index once; read commands keep working on an older index until then.
+
 ## [2.0.0] - 2026-09-14
 
 Evidence release. Everything an agent reads through `codebase-index` is now identified
@@ -773,7 +868,8 @@ Pooled over 305 queries (Python, Java, TypeScript), v1.8.0 → 1.9.0:
 - Hooks example + `watch` mode for keeping the index fresh without blocking the edit loop (M8).
 - `doctor`, `stats`, `clean` diagnostics/maintenance commands.
 
-[Unreleased]: https://github.com/denfry/codebase-index/compare/v2.0.0...HEAD
+[Unreleased]: https://github.com/denfry/codebase-index/compare/v2.1.0...HEAD
+[2.1.0]: https://github.com/denfry/codebase-index/compare/v2.0.0...v2.1.0
 [2.0.0]: https://github.com/denfry/codebase-index/compare/v1.9.0...v2.0.0
 [1.10.0]: https://github.com/denfry/codebase-index/compare/v1.9.0...abb67df
 [1.9.0]: https://github.com/denfry/codebase-index/compare/v1.8.0...v1.9.0
diff --git a/README.md b/README.md
index 5271de0..ba3aa4d 100644
--- a/README.md
+++ b/README.md
@@ -130,13 +130,16 @@ affected files (8): src/flask/app.py, src/flask/ctx.py, src/flask/globals.py, ..
 
 More: `explain "how are blueprints registered"`, `describe dispatch_request`,
 `architecture` (modules, god nodes, surprising links), `graph User --output graph.html`.
-Add `--json` to any command for the machine-readable packet.
+Name a method as `Owner.member` (`SessionInterface.open_session`) to leave out
+same-named methods of other types. Add `--json` to any command for the
+machine-readable packet, or `--compact` (search, explain, refs, impact) for the
+agent format: `path:start-end symbol` with the matching lines numbered underneath.
 
 ## Agent integrations
 
 | Agent | Setup | What it gets |
 |---|---|---|
-| **Claude Code** | `codebase-index init --target claude`, or the plugin: `/plugin marketplace add denfry/codebase-index` then `/plugin install codebase-index@codebase-index` | A skill that routes repository questions to the index and reads only `recommended_reads` ranges; optional PostToolUse hook keeps the index fresh |
+| **Claude Code** | `codebase-index init --target claude`, or the plugin: `/plugin marketplace add denfry/codebase-index` then `/plugin install codebase-index@codebase-index` | A skill that routes repository questions to the index and answers from `--compact` output (ranked files with numbered matching lines, `refs` with the calling function per site); optional PostToolUse hook keeps the index fresh |
 | **Codex CLI** | `codebase-index init --target codex` | A managed block in `AGENTS.md` plus the skill resources |
 | **OpenCode** | `codebase-index init --target opencode` | `/codebase-index` command, agent file, skill resources |
 | **Any MCP client** (Claude Desktop, Cursor, VS Code, Zed, Windsurf, ...) | `pip install "codebase-index[mcp]"` then `codebase-index mcp --root /path/to/repo` | 11 tools (`search_code`, `find_refs`, `impact_of`, `impact_of_diff`, `path_between`, ...) with a versioned JSON envelope |
@@ -172,10 +175,14 @@ significant on a pooled multi-language query set
 ([tests/eval](tests/eval/README.md)). 1.9.0 removed two signals that could not
 show a benefit and rejected five plausible ones.
 
-**What is not measured yet**: whether an *agent* completes tasks better with the
-index. That needs model calls and a rubric and is the top item in
-[BENCHMARKS.md](docs/BENCHMARKS.md#future-work-in-priority-order). Please do not
-quote task-success numbers for this project; there are none.
+**Agent pilot (2.1.0).** The same five code questions on a 5.9k-file Java/Rust
+monorepo, answered by a coding agent three times with the skill and three times with
+Grep/Read only: **19% fewer tokens and 25% fewer tool calls** with the skill, all
+answers correct in both arms, no overlap between the arms' token ranges. It is one
+private repository and five questions, so read it as a direction:
+[raw runs and caveats](tests/eval/results/2026-09-24-agent-pilot.md). A broader
+task-level evaluation is still the top item in
+[BENCHMARKS.md](docs/BENCHMARKS.md#future-work-in-priority-order).
 
 ## How it works
 
diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md
index 4b3c80f..2cfa975 100644
--- a/docs/BENCHMARKS.md
+++ b/docs/BENCHMARKS.md
@@ -178,6 +178,25 @@ Every ranking signal that ships has an ablation row. 1.9.0 removed two signals
 that could not demonstrate a benefit and rejected several plausible ones
 (IDF-weighted coverage, stemming, graph propagation, MMR, a file-length prior).
 
+## Agent pilot (2.1.0)
+
+The first task-level measurement: five code questions on one private 5.9k-file
+Java/Rust monorepo, a Claude Code subagent answering each set three times with the
+skill and three times with Grep/Read only
+([raw runs, questions, ground truth, caveats](../tests/eval/results/2026-09-24-agent-pilot.md)).
+
+| arm | mean tokens | range | mean tool calls | correct |
+|---|---:|---|---:|---|
+| skill 2.1.0 | **83.5k** | 82.1k–85.0k | **9.0** | 15/15 |
+| Grep/Read only | 103.0k | 98.7k–107.1k | 12.0 | 15/15 |
+| skill, pre-2.1.0 template | 100.6k | 96.1k–103.5k | 16.7 | 15/15 |
+
+The 2.1.0 ranking changes were gated separately over 342 queries (six query sets,
+five repositories, 24 of them natural-language questions): MRR +0.010 (p=0.031),
+recall@10 +0.019 (p=0.017), nDCG@10 +0.011 (p=0.005), useful@budget +0.022
+(p=0.008), no corpus regressing
+([log](../tests/eval/results/2026-09-24-retrieval-2.1.0.txt)).
+
 ## Evidence memory
 
 `tests/eval/memory_eval.py` replays a repository's own history: for every git-derived
@@ -223,16 +242,15 @@ Do not write, imply, or ship any of these until a run with published logs exists
 - Any *token savings* multiplier without naming the read model. Under
   symmetric accounting the index costs about the same as disciplined grep.
 - Latency comparisons against external tools.
-- Any statement about *LLM agent task success*. The baselines here are
-  retrieval metrics; nobody has measured whether an agent with the index
-  finishes tasks faster or better. That is the most important open item.
+- Any general statement about *LLM agent task success* or savings beyond the
+  pilot above (one private repository, five questions, one model). Quote the
+  pilot with its scope or not at all.
 
 ## Future work, in priority order
 
-1. **Agent task-level evaluation**: the same questions, an actual coding agent
-   (Claude Code or Codex CLI) with and without the skill, measuring answer
-   correctness, files read, tokens, and wall time. Needs model calls and a
-   grading rubric; not started.
+1. **Agent task-level evaluation**: the pilot above covers one repository and
+   five questions. Next: public repositories, natural-language and debugging
+   tasks, more runs per arm, and a second agent (Codex CLI).
 2. **Large repository run**: a 500k–1M LOC monorepo, reporting index build
    time, incremental update latency, memory, and the same retrieval metrics.
 3. **Graph task benchmark**: hand-labelled `refs`, `impact`, and
diff --git a/docs/installer.md b/docs/installer.md
index abf2c1f..458c3b5 100644
--- a/docs/installer.md
+++ b/docs/installer.md
@@ -110,7 +110,7 @@ pwsh ./install.ps1 -Target claude -InstallDir "D:\skills\codebase-index"
 **Pin to a branch or tag** (reproducibility and safety):
 
 ```sh
-sh install.sh --branch v2.0.0
+sh install.sh --branch v2.1.0
 ```
 
 ---
diff --git a/requirements.lock b/requirements.lock
index eb8619a..084a720 100644
--- a/requirements.lock
+++ b/requirements.lock
@@ -1,3 +1,3 @@
-codebase-index @ https://github.com/denfry/codebase-index/archive/refs/tags/v2.0.0.tar.gz
+codebase-index @ https://github.com/denfry/codebase-index/archive/refs/tags/v2.1.0.tar.gz
 tree-sitter==0.25.2
 tree-sitter-language-pack==1.8.1
diff --git a/src/codebase_index/__init__.py b/src/codebase_index/__init__.py
index 61ed905..40ce013 100644
--- a/src/codebase_index/__init__.py
+++ b/src/codebase_index/__init__.py
@@ -4,4 +4,4 @@
 See docs/ARCHITECTURE.md for the module map.
 """
 
-__version__ = "2.0.0"
+__version__ = "2.1.0"
diff --git a/tests/eval/results/2026-09-24-agent-pilot.md b/tests/eval/results/2026-09-24-agent-pilot.md
new file mode 100644
index 0000000..1a06eb8
--- /dev/null
+++ b/tests/eval/results/2026-09-24-agent-pilot.md
@@ -0,0 +1,72 @@
+# Agent pilot: the same questions with and without the skill (2.1.0)
+
+A first task-level measurement: a coding agent answers code questions once with the
+`codebase-index` skill and once with Grep/Read/shell only, and we count what it spent.
+It is a **pilot**, not a benchmark result: one repository, five questions, three runs
+per arm, one model. Treat the numbers as a direction, not a general claim.
+
+## Setup
+
+- **Repository:** `terra-incognita` (private): a Minecraft mod monorepo, 5,904 indexed
+  files (985 Java in 18 Gradle modules, a Rust launcher workspace, Python tools).
+- **Agent:** Claude Code `general-purpose` subagents, model `claude-opus-5-5`, run in
+  parallel, each in a fresh context. Token counts are the harness's per-subagent
+  totals; tool output is the character count of every tool result in the transcript.
+- **Skill arm:** must invoke the `codebase-index` skill (2.1.0 template, user-level copy)
+  and use the CLI first; Grep only as a fallback; a unique `--session` tag per run.
+- **Control arm:** must not use `codebase-index`; Grep, Glob, Read, grep/sed/find only.
+- Both arms: the index was fresh; graphify was forbidden; no edits.
+
+### Questions (ground truth verified by hand against the tree)
+
+1. How does the town treasury work: storage and persistence, deposit, withdraw, who may
+   withdraw? (`Treasury.java`, `TreasuryService.java`, `TreasuryRules.java`)
+2. Every production call site of `TreasuryService.treasurerDeparted`. (7 sites)
+3. What breaks if `TownService.refresh(MinecraftServer)` changes signature, and does any
+   other Gradle module depend on it? (14 call sites incl. 6 unqualified; no dependent
+   module; `settings.gradle.kts:40` only includes it)
+4. Every production call site of `Holdings.take(ItemStack, int)`. (2 sites, both
+   through `chest.holdings().take(..)`; other `take` methods excluded)
+5. Rust launcher: what `place` does on a hash mismatch, the verifying function, the
+   error, every caller, and where the error is handled. (`fsx::copy_verified`,
+   `CoreError::ObjectDamaged`, callers `activation.rs:236,248`, `presets.rs:75`,
+   handled at `engine.rs:470,644`)
+
+## Results
+
+| arm | run | tokens | tool calls | tool output (chars) | wall time | correct |
+|---|---|---:|---:|---:|---:|---|
+| skill 2.1.0 | A | 82,092 | 9 | 50,565 | 78 s | 5/5 (said "15" for 14 listed sites) |
+| skill 2.1.0 | B | 83,473 | 11 | 52,584 | 85 s | 5/5 |
+| skill 2.1.0 | C | 85,017 | 7 | 57,785 | 266 s | 5/5 |
+| grep only | A | 103,238 | 11 | 107,592 | 78 s | 5/5 |
+| grep only | B | 107,099 | 12 | 113,460 | 271 s | 5/5 (said "15" for 14 listed sites) |
+| grep only | C | 98,657 | 13 | 92,981 | 96 s | 5/5 |
+
+| arm | mean tokens | range | mean tool calls | median wall time |
+|---|---:|---|---:|---:|
+| **skill 2.1.0** | **83,527** | 82,092–85,017 | **9.0** | 85 s |
+| grep only | 103,000 | 98,657–107,099 | 12.0 | 96 s |
+| Δ | **−18.9%** | ranges do not overlap | **−25%** | |
+
+Wall time is dominated by queueing when six agents run at once (one run per arm took
+over four minutes), so it is reported but not compared.
+
+### Before this release
+
+The same five questions with the previous skill (2.0.0-era template, `--json`
+everywhere) cost 96,102 / 102,248 / 103,528 tokens and 15 / 19 / 16 tool calls: parity
+with grep on tokens and more tool calls. The difference between the two skill runs is
+the 2.1.0 work: `--compact` output with numbered lines (agents stopped re-reading files
+or grepping for line numbers), exact `Owner.member` refs with counts, build-module
+information in `impact`, and a shorter skill.
+
+## Caveats
+
+- One private repository and five questions, four of them lookups by an exact name,
+  which is where Grep is strongest. Natural-language questions are measured by the
+  retrieval eval instead (see `2026-09-24-retrieval-2.1.0.txt`).
+- Three runs per arm; the control arm's token range across earlier rounds was
+  91.8k–108.5k, so single-run comparisons are noise.
+- Both arms made one counting slip in the prose around a correct list; `refs --compact`
+  now prints the total in its header.
diff --git a/tests/eval/results/2026-09-24-retrieval-2.1.0.txt b/tests/eval/results/2026-09-24-retrieval-2.1.0.txt
new file mode 100644
index 0000000..8ac2b83
--- /dev/null
+++ b/tests/eval/results/2026-09-24-retrieval-2.1.0.txt
@@ -0,0 +1,47 @@
+# Retrieval eval, 2.1.0 ranking vs 2.0.0 ranking (resource_priors, stem_match, question_pool_floor off)
+# 342 queries: git-mined sets over Civitas (76), PoliternalSite (80), PoliternalParkour (65), TerraForge (17), terra-incognita (80),
+# plus 24 hand-written natural-language questions over terra-incognita (2026-09-24-terra-nl-queries.yml). tests/eval/harness.py, 2000 resamples.
+
+| label | recall@5 | recall@10 | MRR | oracle | eff | nDCG@10 | hit@3 | P@5 | MAP | useful@budget | tokens | dup% | p50_ms | p95_ms |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| old | 0.541 | 0.635 | 0.521 | 0.868 | 0.600 | 0.502 | 0.599 | 0.169 | 0.426 | 0.557 | 966.8 | 0.0 | 50.5 | 92.3 |
+| new | 0.557 (+0.016) | 0.653 (+0.019) | 0.531 (+0.010) | 0.877 (+0.009) | 0.606 (+0.006) | 0.513 (+0.011) | 0.605 (+0.006) | 0.173 (+0.004) | 0.434 (+0.007) | 0.579 (+0.022) | 951.5 (-15.4) | 0.0 | 51.4 (+0.9) | 101.8 (+9.5) |
+
+paired comparison: new vs old (n=342)
+| metric        |    delta |              95% CI |      p | sig |
+|---|---|---|---|---|
+| recall@5      |  +0.0156 | [+0.0012,+0.0327] |  0.044 | yes |
+| recall@10     |  +0.0185 | [+0.0039,+0.0356] |  0.017 | yes |
+| MRR           |  +0.0104 | [+0.0011,+0.0208] |  0.031 | yes |
+| nDCG@10       |  +0.0110 | [+0.0032,+0.0200] |  0.005 | yes |
+| hit@3         |  +0.0058 | [-0.0088,+0.0205] |  0.697 | no  |
+| P@5           |  +0.0041 | [+0.0000,+0.0088] |  0.131 | no  |
+| MAP           |  +0.0075 | [+0.0004,+0.0150] |  0.041 | yes |
+| useful@budget |  +0.0224 | [+0.0066,+0.0404] |  0.008 | yes |
+| oracle        |  +0.0088 | [+0.0000,+0.0205] |  0.247 | no  |
+| cand_recall   |  +0.0073 | [+0.0000,+0.0175] |  0.247 | no  |
+
+| label | recall@5 | recall@10 | MRR | oracle | eff | nDCG@10 | hit@3 | P@5 | MAP | useful@budget | tokens | dup% | p50_ms | p95_ms |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| Civitas:old | 0.452 | 0.567 | 0.524 | 0.868 | 0.604 | 0.475 | 0.566 | 0.147 | 0.409 | 0.502 | 937.4 | 0.0 | 39.3 | 112.9 |
+| Civitas:new | 0.455 | 0.583 | 0.545 | 0.868 | 0.628 | 0.492 | 0.579 | 0.150 | 0.424 | 0.519 | 920.2 | 0.0 | 40.9 | 112.9 |
+| label | recall@5 | recall@10 | MRR | oracle | eff | nDCG@10 | hit@3 | P@5 | MAP | useful@budget | tokens | dup% | p50_ms | p95_ms |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| PoliternalSite:old | 0.498 | 0.585 | 0.529 | 0.825 | 0.641 | 0.492 | 0.600 | 0.179 | 0.425 | 0.562 | 977.6 | 0.0 | 55.0 | 81.7 |
+| PoliternalSite:new | 0.502 | 0.582 | 0.528 | 0.825 | 0.639 | 0.490 | 0.588 | 0.182 | 0.423 | 0.567 | 947.2 | 0.0 | 52.5 | 79.0 |
+| label | recall@5 | recall@10 | MRR | oracle | eff | nDCG@10 | hit@3 | P@5 | MAP | useful@budget | tokens | dup% | p50_ms | p95_ms |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| PoliternalPark:old | 0.700 | 0.796 | 0.486 | 0.892 | 0.545 | 0.557 | 0.585 | 0.147 | 0.478 | 0.669 | 898.1 | 0.0 | 43.7 | 83.7 |
+| PoliternalPark:new | 0.700 | 0.796 | 0.485 | 0.892 | 0.543 | 0.556 | 0.569 | 0.147 | 0.476 | 0.669 | 897.9 | 0.0 | 49.3 | 92.3 |
+| label | recall@5 | recall@10 | MRR | oracle | eff | nDCG@10 | hit@3 | P@5 | MAP | useful@budget | tokens | dup% | p50_ms | p95_ms |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| TerraForge:old | 0.750 | 0.770 | 0.662 | 1.000 | 0.662 | 0.657 | 0.824 | 0.306 | 0.580 | 0.578 | 978.9 | 0.0 | 71.1 | 98.2 |
+| TerraForge:new | 0.750 | 0.799 | 0.680 | 1.000 | 0.680 | 0.677 | 0.824 | 0.306 | 0.594 | 0.608 | 978.9 | 0.0 | 45.9 | 79.6 |
+| label | recall@5 | recall@10 | MRR | oracle | eff | nDCG@10 | hit@3 | P@5 | MAP | useful@budget | tokens | dup% | p50_ms | p95_ms |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| terra-incognit:old | 0.457 | 0.566 | 0.535 | 0.875 | 0.612 | 0.462 | 0.613 | 0.180 | 0.369 | 0.486 | 1014.2 | 0.0 | 57.5 | 91.5 |
+| terra-incognit:new | 0.479 | 0.589 | 0.545 | 0.887 | 0.614 | 0.470 | 0.625 | 0.185 | 0.372 | 0.506 | 986.7 | 0.0 | 57.9 | 115.4 |
+| label | recall@5 | recall@10 | MRR | oracle | eff | nDCG@10 | hit@3 | P@5 | MAP | useful@budget | tokens | dup% | p50_ms | p95_ms |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| terra-nl:old | 0.667 | 0.708 | 0.428 | 0.833 | 0.514 | 0.496 | 0.542 | 0.133 | 0.428 | 0.625 | 1043.6 | 0.0 | 51.3 | 83.9 |
+| terra-nl:new | 0.792 | 0.833 | 0.476 | 0.917 | 0.519 | 0.564 | 0.625 | 0.158 | 0.476 | 0.792 | 1073.0 | 0.0 | 69.5 | 138.1 |
diff --git a/tests/eval/results/2026-09-24-terra-nl-queries.yml b/tests/eval/results/2026-09-24-terra-nl-queries.yml
new file mode 100644
index 0000000..589e390
--- /dev/null
+++ b/tests/eval/results/2026-09-24-terra-nl-queries.yml
@@ -0,0 +1,75 @@
+# Natural-language "how does X work" questions over terra-incognita, the kind an
+# agent asks. Expected files are the classes whose javadoc answers them; the
+# wording is paraphrased so the doc comment is not a verbatim lexical hit.
+- query: "how does the town treasury store and persist its items"
+  category: concept
+  expected_files: [realism-polity/src/main/java/dev/terraincognita/realism/polity/treasury/Treasury.java]
+- query: "who is allowed to withdraw from the town treasury"
+  category: concept
+  expected_files: [realism-polity/src/main/java/dev/terraincognita/realism/polity/treasury/TreasuryRules.java]
+- query: "what happens when a stored object's hash does not match while placing it"
+  category: concept
+  expected_files: [launcher/crates/terra-launcher-core/src/activation.rs]
+- query: "how are planted crops saved per dimension"
+  category: concept
+  expected_files: [realism-agriculture/src/main/java/dev/terraincognita/realism/agriculture/persistence/AgricultureData.java]
+- query: "how is a crop definition loaded from the datapack"
+  category: concept
+  expected_files: [realism-agriculture/src/main/java/dev/terraincognita/realism/agriculture/crop/CropReloadListener.java]
+- query: "how long does the air in a diving bell stay breathable"
+  category: concept
+  expected_files: [realism-hydrosphere/src/main/java/dev/terraincognita/realism/hydrosphere/block/DivingBellBlockEntity.java]
+- query: "how does the deep scattering layer move between day and night"
+  category: concept
+  expected_files: [realism-hydrosphere/src/main/java/dev/terraincognita/realism/hydrosphere/depth/ScatteringLayer.java]
+- query: "how strong is a herbal dose in this world"
+  category: concept
+  expected_files: [realism-medicine/src/main/java/dev/terraincognita/realism/medicine/Potency.java]
+- query: "how does the body fight an infection by a pathogen"
+  category: concept
+  expected_files: [realism-medicine/src/main/java/dev/terraincognita/realism/medicine/illness/Infection.java]
+- query: "which planted positions are in loaded chunks"
+  category: concept
+  expected_files: [realism-agriculture/src/main/java/dev/terraincognita/realism/agriculture/field/PlotIndex.java]
+- query: "how are ecological signals broadcast on the server"
+  category: concept
+  expected_files: [realism-api/src/main/java/dev/terraincognita/realism/api/signal/SignalBus.java]
+- query: "where does game time, season and day length come from"
+  category: concept
+  expected_files: [realism-api/src/main/java/dev/terraincognita/realism/api/environment/CalendarSource.java]
+- query: "how does a building teach the player what it knows"
+  category: concept
+  expected_files: [realism-institutions/src/main/java/dev/terraincognita/realism/institutions/effect/Unlocks.java]
+- query: "how is a map sheet rendered like a printed map"
+  category: concept
+  expected_files: [realism-cartography/src/main/java/dev/terraincognita/realism/cartography/client/SheetRenderer.java]
+- query: "how does the tripod hold a cauldron over the fire"
+  category: concept
+  expected_files: [realism-cuisine/src/main/java/dev/terraincognita/realism/cuisine/block/TripodBlock.java]
+- query: "how is a command run on the server thread and its output captured"
+  category: concept
+  expected_files: [realism-agent/src/main/java/dev/terraincognita/realism/agent/CommandBridge.java]
+- query: "how are the weather conditions at a player's position sent to the client"
+  category: concept
+  expected_files: [realism-atmosphere/src/main/java/dev/terraincognita/realism/atmosphere/network/LocalWeatherPayload.java]
+- query: "which books can be bought and from whom"
+  category: concept
+  expected_files: [realism-institutions/src/main/java/dev/terraincognita/realism/institutions/source/BookTrades.java]
+- query: "how does a pet rat remember its owner's habits"
+  category: concept
+  expected_files: [realism-compat/src/main/java/dev/terraincognita/realism/compat/naturalist/RatCompanion.java]
+- query: "where do changes to the land get reported"
+  category: concept
+  expected_files: [realism-api/src/main/java/dev/terraincognita/realism/api/ecology/LandUseSink.java]
+- query: "how does the player fill in an atlas"
+  category: concept
+  expected_files: [realism-cartography/src/main/java/dev/terraincognita/realism/cartography/document/AtlasItem.java]
+- query: "what skills can a pair of hands improve at in medicine"
+  category: concept
+  expected_files: [realism-medicine/src/main/java/dev/terraincognita/realism/medicine/hands/Procedure.java]
+- query: "how does a town get founded at its hall"
+  category: concept
+  expected_files: [realism-polity/src/main/java/dev/terraincognita/realism/polity/town/TownService.java]
+- query: "how are damaged launcher downloads retried"
+  category: concept
+  expected_files: [launcher/crates/terra-launcher-core/src/engine.rs]