update docs for trace tool (PR-TRACE-4) (#249)

* update docs for trace tool (PR-TRACE-4)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* update skills/ for six-tool trace surface

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: HumanBean17

AGENTS.md

@@ -19,7 +19,7 @@ gitignored).
 
 `.agents/` skills are loaded by the agent working *on* java-codebase-rag source
 code. `skills/` and `agents/` are shipped to consumers — they instruct an agent
-to call the MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`)
+to call the MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`, `trace`)
 against an indexed Java codebase. Do not mix the two: never import consumer
 skills/agents into `.agents/skills/` or vice versa.
 
@@ -37,7 +37,7 @@ when needed.
 
 - `README.md` — pip-first landing page: install, 5-minute walkthrough on the
   bank-chat fixture, MCP host wiring (Claude Code / Claude Desktop), the
-  five-tool cheat sheet (`search` / `find` / `describe` / `neighbors` / `resolve`),
+  six-tool cheat sheet (`search` / `find` / `describe` / `neighbors` / `resolve` / `trace`),
   and the CLI cheat sheet. Pointers out to other docs for depth.
 - [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) — environment
   variables, full `.java-codebase-rag.yml` reference, **graph layer**
@@ -56,7 +56,7 @@ when needed.
 - `docs/CODEBASE_REQUIREMENTS.md` — Java-repo assumptions and per-file map of
   what to edit when a target tree doesn't match defaults.
 - `tests/README.md` — testing philosophy.
-- **`skills/explore-codebase/`** — user-facing skill shipped to java-codebase-rag consumers. Single self-contained operating manual for the 5-tool MCP. Developer workflow skills live in **`.agents/skills/`**, not here.
+- **`skills/explore-codebase/`** — user-facing skill shipped to java-codebase-rag consumers. Single self-contained operating manual for the 6-tool MCP. Developer workflow skills live in **`.agents/skills/`**, not here.
 - **`agents/java-codebase-rag-explorer.md`** — user-facing Claude Code subagent shipped to consumers. Contains the same MCP guide content as `docs/AGENT-GUIDE.md` (the single source of truth).
 - **`propose/`** — design proposes. **In-flight** proposes live in
   **`propose/active/`**. **`propose/completed/`** — landed work and rationale.
@@ -81,6 +81,7 @@ when needed.
 | `java_ontology.py` | Source of truth for `VALID_ROLES`, `VALID_CAPABILITIES`, `VALID_CLIENT_KINDS`, `VALID_HTTP_CALL_STRATEGIES`, `VALID_ASYNC_CALL_STRATEGIES`, `VALID_HTTP_CALL_MATCHES`. |
 | `chunk_heuristics.py` | Query-time chunk hints (no AST / no re-index). |
 | `mcp_hints.py` | MCP v2 road-sign `hints` catalog (`generate_hints`; locked v1 templates in `propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md`). |
+| `mcp_trace.py` | Multi-hop BFS traversal engine (`trace` MCP tool). |
 | `index_common.py` | Embedding config (no CocoIndex dep). |
 | `java_index_flow_lancedb.py` | CocoIndex flow (used by `java-codebase-rag init` / `increment` / `reprocess` / `erase`). |
 | `java_index_v1_common.py` | Shared file walker / exclude patterns. |

README.md

@@ -2,7 +2,7 @@
 
 A graph-native code intelligence layer for Java microservice estates, exposed to LLM agents via the **Model Context Protocol (MCP)**.
 
-The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **Kuzu** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **five tools**: `search`, `find`, `describe`, `neighbors`, `resolve` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
+The system extracts a deterministic property graph from Java source (tree-sitter), stores it in **Kuzu** (graph) alongside a **LanceDB** vector index (chunks), and exposes a deliberately small MCP surface — **six tools**: `search`, `find`, `describe`, `neighbors`, `resolve`, `trace` — that collapse onto three primitive agent operations: **locate**, **inspect**, **walk**.
 
 > **What this MCP is:** a **GPS for code navigation**, not a reasoning engine.
 > Agents use a simple loop:
@@ -78,7 +78,7 @@ JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/bank-chat-index \
     --graph-expand --expand-depth 2
 ```
 
-If vector hits come back and graph expansion adds neighbor symbols, the install works end-to-end. Wire it into your agent next — the five MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`) are reachable over stdio.
+If vector hits come back and graph expansion adds neighbor symbols, the install works end-to-end. Wire it into your agent next — the six MCP tools (`search`, `find`, `describe`, `neighbors`, `resolve`, `trace`) are reachable over stdio.
 
 ---
 
@@ -118,15 +118,15 @@ See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (
 
 Pick **one** of two options (not both — they cover the same navigation intents):
 
-1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and navigation patterns. Self-contained — no external file dependencies.
+1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: six-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and navigation patterns. Self-contained — no external file dependencies.
 
 2. **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** (for hosts with skill discovery) — single self-contained skill with the complete operating manual. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), load `/explore-codebase` to get the full tool reference, edge taxonomy, decision tree, and recovery playbook in one shot.
 
 Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
 
 ---
 
-## The five tools, at a glance
+## The six tools, at a glance
 
 | Tool | Purpose | Required args |
 |---|---|---|
@@ -135,12 +135,13 @@ Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHE
 | `describe` | Full record + edge counts for one node. | `id` |
 | `resolve` | Identifier-shaped lookup (FQN-collision-safe). Returns `one` / `many` / `none`. | `identifier` |
 | `neighbors` | Graph walk, one hop. | `ids`, `direction`, `edge_types` |
+| `trace` | Multi-hop BFS traversal with pruning. | `ids`, `direction`, `edge_types` |
 
 Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live in [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md). Edge types and traversal directions are listed in [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md).
 
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skill). The [`/explore-codebase`](./skills/explore-codebase/SKILL.md) skill provides the full operating manual for Layer 2. See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+Layer 1 (storage) → Layer 2 (6 MCP tools) → Layer 3 (skill). The [`/explore-codebase`](./skills/explore-codebase/SKILL.md) skill provides the full operating manual for Layer 2. See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
 
 ---
 

docs/AGENT-GUIDE.md

@@ -1,22 +1,22 @@
 # Agent Guide — `java-codebase-rag` MCP
 
-Copy the block between `<!-- BEGIN` and `<!-- END` into your project's `AGENTS.md`, `CLAUDE.md`, or equivalent. It is self-contained: five MCP tools, shared `NodeFilter`, edge taxonomy, tool-selection rules, and recovery moves.
+Copy the block between `<!-- BEGIN` and `<!-- END` into your project's `AGENTS.md`, `CLAUDE.md`, or equivalent. It is self-contained: six MCP tools, shared `NodeFilter`, edge taxonomy, tool-selection rules, and recovery moves.
 
 ---
 
 <!-- BEGIN java-codebase-rag MCP guide -->
 
 ## java-codebase-rag MCP — operating manual
 
-**Tools:** `search`, `find`, `describe`, `neighbors`, `resolve`.
+**Tools:** `search`, `find`, `describe`, `neighbors`, `resolve`, `trace`.
 
 **Node kinds:** `Symbol` (types and methods), `Route` (HTTP and messaging entry points), `Client` (outbound HTTP call sites), `Producer` (outbound async call sites).
 
 **Indexed content:** Java production sources plus SQL and YAML (use `search` `table`: `java`, `sql`, `yaml`, or `all`).
 
 **Ontology: 16** — if results look structurally wrong or empty across tools, the index may be missing, stale, or built with a different `ontology_version`; you cannot re-index via MCP — ask the operator to rebuild.
 
-**Responses:** On success, `search`, `find`, `describe`, `neighbors`, and `resolve` may include two top-level fields: `hints_structured` (≤5 suggested next-tool calls) and `advisories` (≤5 pure informational strings). Each `hints_structured` entry has `tool`, `args`, `actionable`, `label`, and `reason`. `actionable=true` means you can call the tool directly with `args`; `actionable=false` means partial/advisory — fill missing values or use as guidance. `reason` explains why the hint was emitted. `advisories` carry context education (fuzzy strategy warnings, role collision explanations, etc.) with no tool call suggestion. For `search`/`find`, echoed `limit`/`offset`. Hints are advisory; ignore them when `success` is false.
+**Responses:** On success, `search`, `find`, `describe`, `neighbors`, `resolve`, and `trace` may include two top-level fields: `hints_structured` (≤5 suggested next-tool calls) and `advisories` (≤5 pure informational strings). Each `hints_structured` entry has `tool`, `args`, `actionable`, `label`, and `reason`. `actionable=true` means you can call the tool directly with `args`; `actionable=false` means partial/advisory — fill missing values or use as guidance. `reason` explains why the hint was emitted. `advisories` carry context education (fuzzy strategy warnings, role collision explanations, etc.) with no tool call suggestion. For `search`/`find`, echoed `limit`/`offset`. Hints are advisory; ignore them when `success` is false.
 
 **Use this MCP when** you need whole-codebase structure: callers/callees, route handlers, HTTP/async seams, clients/producers, or fuzzy entry points for a concept.
 
@@ -35,15 +35,15 @@ When MCP disagrees with the open file, **the file wins**; treat the mismatch as
 
 1. **Locate** — `resolve` for identifier-shaped strings; `search` for natural language or code fragments; `find` for structured `NodeFilter` discovery.
 2. **Inspect** — `describe(id)` for the full record and `edge_summary` (per-label `in`/`out` counts).
-3. **Walk** — `neighbors` in a loop with explicit **`direction`** and **`edge_types`**. Multi-hop traces are **your** reasoning, not a separate tool.
+3. **Walk** — `neighbors` in a loop with explicit **`direction`** and **`edge_types`**, or `trace` for multi-hop BFS with server-side pruning in one call.
 
 ### Forced reasoning preamble (every tool call)
 
 Before each MCP call, output one short line:
 
 ```
-Q-class: <semantic | structured | inspect | walk>
-Pick: <search|find|describe|neighbors|resolve>  Why: <≤8 words>
+Q-class: <semantic | structured | inspect | walk | trace>
+Pick: <search|find|describe|neighbors|trace|resolve>  Why: <≤8 words>
 ```
 
 Then use real JSON shapes (see below). If the call fails or returns nothing useful, use the **Recovery playbook** — do not thrash.
@@ -178,7 +178,7 @@ Prefer **`resolve` → `describe(id=…)`** over **`describe(fqn=…)`** when an
 | Handler for route | route id | `neighbors(ids, "in", ["EXPOSES"])` |
 | Who implements interface T? | type symbol id | `neighbors(ids, "in", ["IMPLEMENTS"])` |
 | Who injects type T? | type symbol id | `neighbors(ids, "in", ["INJECTS"])` |
-| Impact / "what breaks if I change X"? | no magic tool | loop `neighbors` `in` with `CALLS`, `INJECTS`, … until bounded |
+| Impact / "what breaks if I change X"? | `trace` or `neighbors` loop | `trace(id, "in", ["CALLS","OVERRIDES"], max_depth=3)` or loop `neighbors` `in` with `CALLS`, `INJECTS` |
 
 **Rules of thumb:**
 
@@ -188,6 +188,14 @@ Prefer **`resolve` → `describe(id=…)`** over **`describe(fqn=…)`** when an
 
 ### Tool reference
 
+#### `trace`
+
+Multi-hop BFS traversal with server-side pruning. Returns structured paths, a node dict, and traversal stats. Use when the question implies a path or chain (3+ hops), needs to cross a service boundary, or a `neighbors` loop has exceeded 2 hops without converging. Args: `ids` (string or array), **`direction`**, **`edge_types`** (stored labels only — no composed dot-keys), `max_depth` (1–5, default 3), `max_paths` (default 20), `max_nodes_discovered` (100–2000, default 500), `filter` (hard gate `NodeFilter`), `edge_filter` (CALLS edge attribute filtering), `prune_roles` (soft gate — edges recorded, frontier stops), `fan_out_cap` (per-node edge limit, default 5), `collapse_trivial` (collapse wrapper chains, default true), `include_unresolved` (interleave unresolved call sites).
+
+Returns `TraceOutput` with `nodes` (dict of `NodeRef`), `edges` (list of `TraceEdge` with `hop`, `parent_edge_id`, `collapsed`, `cross_service_boundary`), `paths` (ranked root-to-leaf), and `stats` (budget, pruning counts). Cross-service edges (`HTTP_CALLS`, `ASYNC_CALLS`) are boundary signals — BFS stops at the service boundary and includes the downstream node for the agent to continue with a separate `trace` call.
+
+**`trace` vs `neighbors`:** Use `neighbors` for single-hop adjacency (full unfiltered result). Use `trace` for multi-hop path questions, impact analysis, or when `neighbors` returns high fan-out (>8 CALLS edges).
+
 #### `search`
 
 Ranked chunk retrieval. Args: `query`, `table` (`java`|`sql`|`yaml`|`all`, default `java`), `hybrid` (bool), `limit` (default 5), `offset`, `path_contains`, optional `filter` (symbol-applicable `NodeFilter` only).
@@ -272,7 +280,7 @@ After two failed attempts on the same intent, stop and report tool name, args, a
 
 ### Common navigation patterns
 
-These patterns combine the five tools above. Use the decision tree to pick the right starting tool.
+These patterns combine the six tools above. Use the decision tree to pick the right starting tool.
 
 | Intent | Tool chain |
 | ------ | ---------- |
@@ -287,7 +295,10 @@ These patterns combine the five tools above. Use the decision tree to pick the r
 | All inbound to route R | `neighbors(route_id, "in", ["HTTP_CALLS","ASYNC_CALLS","EXPOSES"])` |
 | Implementors of interface T | `neighbors(type_id, "in", ["IMPLEMENTS"])` |
 | Where is T injected | `neighbors(type_id, "in", ["INJECTS"])` |
-| Impact of changing X | `resolve` → `describe` → bounded `neighbors(in, ["CALLS","INJECTS","IMPLEMENTS","EXTENDS"])` depth ≤2 |
+| Impact of changing X | `resolve` → `trace(id, "in", ["CALLS","OVERRIDES"], max_depth=3)` or `neighbors` loop depth ≤2 |
+| "What happens when route R is called?" | `find(kind="route")` → `trace(route_id, "out", ["EXPOSES","CALLS"], max_depth=4)` |
+| "Trace from X to database" | `trace(id, "out", ["CALLS"], max_depth=4, prune_roles=["DTO","EXCEPTION"])` |
+| "What calls this across services?" | `trace(id, "out", ["CALLS","HTTP_CALLS","ASYNC_CALLS"], max_depth=5)` |
 
 ### Canonical workflow: "explain feature X"
 
@@ -305,5 +316,5 @@ These patterns combine the five tools above. Use the decision tree to pick the r
 When MCP behaviour, `NodeFilter` keys, edge labels, or node kinds change:
 
 1. Update this file's copy block and bump the **Ontology:** line to match `ast_java.ONTOLOGY_VERSION`.
-2. Update the five-tool cheat sheet in `README.md` and the "Driving the MCP from an agent" bullet there.
+2. Update the six-tool cheat sheet in `README.md` and the "Driving the MCP from an agent" bullet there.
 3. If enrichment semantics changed, add a "Re-index required" callout in [`docs/CONFIGURATION.md`](./CONFIGURATION.md) §3.

propose/active/TRACE-TOOL-PROPOSE.md propose/completed/TRACE-TOOL-PROPOSE.mdpropose/active/TRACE-TOOL-PROPOSE.md renamed to propose/completed/TRACE-TOOL-PROPOSE.md

@@ -1,6 +1,6 @@
 # TRACE-TOOL -- Multi-hop navigation shortcut
 
-**Status**: active (experimental)
+**Status**: completed (merged to `experimental` as PR-TRACE-1a through PR-TRACE-4)
 **Target branch**: `experimental` — not `master`. `trace` is an experiment; it ships on a dedicated branch and is not merged to `master` until validated in production.
 **Author**: Dmitry + Computer
 **Date**: 2026-05-25

skills/README.md

@@ -1,6 +1,6 @@
 # skills/ — RAG navigation skill for the java-codebase-rag MCP
 
-One self-contained skill for navigating indexed Java codebases via the 5-tool MCP (`search` / `find` / `describe` / `neighbors` / `resolve`). Skills are agent-side prompt scaffolding — they are **not** a second MCP API and **not** CLI subcommands.
+One self-contained skill for navigating indexed Java codebases via the 6-tool MCP (`search` / `find` / `describe` / `neighbors` / `resolve` / `trace`). Skills are agent-side prompt scaffolding — they are **not** a second MCP API and **not** CLI subcommands.
 
 ## Layout
 
@@ -14,7 +14,7 @@ skills/
 
 The comprehensive operating manual. Includes:
 
-- **Five-tool reference** — `search`, `find`, `describe`, `neighbors`, `resolve` with full argument shapes
+- **Six-tool reference** — `search`, `find`, `describe`, `neighbors`, `resolve`, `trace` with full argument shapes
 - **Node kinds** — Symbol, Route, Client, Producer
 - **Edge taxonomy** — stored edges, composed dot-keys, direction semantics
 - **NodeFilter reference** — all filter keys by node kind, strict frame rules