sync docs and agent files with landed hints and ontology 13

Move HINTS propose/plan to completed, refresh AGENT-GUIDE, README,
verification checklist, exploration skill, and architecture paper
(five tools, ten edges, no Karpathy cite); rebuild paper.pdf.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

.cursor/rules/project-overview.mdc

@@ -19,7 +19,8 @@ when needed.
 ## Where to look
 
 - `README.md` — feature surface, env vars, ranking, capabilities,
-  MCP tools (`search` / `find` / `describe` / `neighbors` / `resolve`), `java-codebase-rag` CLI,
+  MCP tools (`search` / `find` / `describe` / `neighbors` / `resolve`; response
+  `hints` + pagination echo on locate tools — see README), `java-codebase-rag` CLI,
   "Re-index required" callouts. The current
   `ontology_version` is **13** (material `OVERRIDES` Symbol→Symbol edges: subtype
   instance method → supertype declaration with matching `signature`, one
@@ -57,6 +58,7 @@ when needed.
 | `graph_enrich.py` | `module` / `microservice` resolution, `BrownfieldOverrides` (route + role + capability + http client + async producer), meta-annotation walk, `resolve_routes_for_method` / `resolve_http_client_for_method` / `resolve_async_producer_for_method`. |
 | `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`). |
 | `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. |

AGENTS.md

@@ -8,7 +8,8 @@ for tools that don't read `.cursor/rules/`.
 ## Where to look
 
 - `README.md` — feature surface, env vars, ranking, capabilities,
- MCP tool list (`search` / `find` / `describe` / `neighbors` / `resolve`),
+ MCP tool list (`search` / `find` / `describe` / `neighbors` / `resolve`;
+ response `hints` + pagination echo — see README),
  CLI ops (`java-codebase-rag --help`), and "Re-index required" callouts.
  **`ontology_version` is currently 13** (stored `OVERRIDES` method→method edges traversable via `neighbors`; plus v12 HTTP brownfield rename, `CodebaseHttpMethod` enum, inbound HTTP layer-C replace — see README graph section).
 - [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) — operator guide for the `java-codebase-rag` CLI (`init` / `increment` / `reprocess` / `erase`, `meta`, `tables`, `diagnose-ignore`, `analyze-pr`; hidden `refresh` alias → `reprocess` — see that doc).

README.md

@@ -261,7 +261,7 @@ Example:
 {"kind":"symbol","filter":{"microservice":"chat-core","symbol_kind":"interface"}}
 ```
 
-**MCP v2 response extras (`hints`, pagination echo):** On success, `search`, `find`, `describe`, and `neighbors` return a `hints` field (`list[str]`, capped at five unique strings) with short, templated suggestions for likely next tool calls; hints are advisory. `hints` is always empty when `success` is false. `search` and `find` additionally echo the request’s `limit` and `offset` on success; on failure those echoed fields are omitted (`null` in JSON). The find page-full hint fires only when another page may exist (handler over-fetches by one row; not exposed on the output model). `neighbors` echoes `requested_edge_types` (deduped edge labels from the request) on success for empty-result hints and diagnostics. See [`propose/HINTS-ROAD-SIGNS-PROPOSE.md`](./propose/HINTS-ROAD-SIGNS-PROPOSE.md) Appendix A for the locked v1 template catalog.
+**MCP v2 response extras (`hints`, pagination echo):** On success, `search`, `find`, `describe`, and `neighbors` return a `hints` field (`list[str]`, capped at five unique strings) with short, templated suggestions for likely next tool calls; hints are advisory. `hints` is always empty when `success` is false. `search` and `find` additionally echo the request’s `limit` and `offset` on success; on failure those echoed fields are omitted (`null` in JSON). The find page-full hint fires only when another page may exist (handler over-fetches by one row; not exposed on the output model). `neighbors` echoes `requested_edge_types` (deduped edge labels from the request) on success for empty-result hints and diagnostics. See [`propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md`](./propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md) Appendix A for the locked v1 template catalog.
 
 ---
 

docs/AGENT-GUIDE.md

@@ -20,7 +20,7 @@
 > replace same-method built-in rows). **Design rationale:** navigation surface and tools —
 > [`propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md`](../propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md);
 > HTTP brownfield rename, `CodebaseHttpMethod`, and exclusivity —
-> [`propose/HTTP-ROUTE-METHOD-ENUM-PROPOSE.md`](../propose/HTTP-ROUTE-METHOD-ENUM-PROPOSE.md).
+> [`propose/completed/HTTP-ROUTE-METHOD-ENUM-PROPOSE.md`](../propose/completed/HTTP-ROUTE-METHOD-ENUM-PROPOSE.md).
 
 ---
 
@@ -35,6 +35,8 @@ This MCP indexes Java enterprise projects into two stores:
 
 **MCP surface (navigation only):** `search`, `find`, `describe`, `neighbors`, `resolve`.
 
+**Response extras (advisory):** On success, `search`, `find`, `describe`, and `neighbors` include a top-level `hints` list (≤5 templated next-call strings). `search` and `find` also echo `limit` / `offset`. Hints are safe to ignore; they are empty when `success` is false. Locked catalog: [`propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md`](../propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md) Appendix A.
+
 **Operator / diagnostics (not MCP):** use the **`java-codebase-rag`** CLI — lifecycle (`init`, `increment`, `reprocess`, `erase`) plus `meta`, `tables`, `diagnose-ignore`, `analyze-pr`. Rebuilds are slow; the coding agent should not pretend it can reindex via MCP. For lifecycle commands, subprocess progress is written to **stderr** (use **`--quiet`** to suppress it); **stdout** is only the structured result payload.
 
 **Use this MCP when** you need whole-codebase context: who calls what, what handles a route, what a method invokes, where clients point, or fuzzy “where is concept X” entry points.

docs/MANUAL-VERIFICATION-CHECKLIST.md

@@ -13,15 +13,15 @@ Each item has:
 - a **Verification prompt** — paste verbatim into your agent (or run the
   shell snippet yourself)
 - **Expected (calibration)** — what the same prompt produces on
-  `tests/bank-chat-system` (ontology **11**). If your numbers diverge wildly,
+  `tests/bank-chat-system` (ontology **13**). If your numbers diverge wildly,
   that's a signal, not a verdict — what matters is the **shape** (proportions,
   error rates, presence of expected edges).
 - **If failing → fix** — concrete next step
 
 Calibration was captured against `tests/bank-chat-system` on
-`master @ e90cbecc` (ontology version **11**): 84 files, 92 types, 474
-members, 0 parse errors, 17 routes, 11 `EXPOSES`, 793 `CALLS`, 2 `HTTP_CALLS`,
-5 `ASYNC_CALLS`, 2 `Client` rows, microservices = `chat-core` + `chat-assign`.
+`chore/docs-sync @ 1fa1b28` (ontology version **13**): 84 files, 92 types, 474
+members, 0 parse errors, 17 routes, 11 `EXPOSES`, 793 `CALLS`, 24 `OVERRIDES`,
+2 `HTTP_CALLS`, 5 `ASYNC_CALLS`, 2 `Client` rows, microservices = `chat-core` + `chat-assign`.
 
 **Convention:** Graph ops use MCP. Index health / rebuild / PR analysis use
 **`java-codebase-rag`** (see README **CLI reference**). Example:
@@ -83,16 +83,16 @@ export JAVA_CODEBASE_RAG_INDEX_DIR=/tmp/verify_index
 
 ## Phase 1 — Index health (4 items)
 
-### 1.1 ☐ Ontology version is 11
+### 1.1 ☐ Ontology version is 13
 
 **Verification prompt:**
 
 > In a shell with `JAVA_CODEBASE_RAG_INDEX_DIR` and `JAVA_CODEBASE_RAG_SOURCE_ROOT`
 > set for your graph, run `java-codebase-rag meta` (JSON output if piped). Report
 > `ontology_version`, `built_at`, `source_root`, and `parse_errors`. Does
-> `ontology_version` equal `11`?
+> `ontology_version` equal `13`?
 
-**Expected (calibration):** `ontology_version: 11`,
+**Expected (calibration):** `ontology_version: 13`,
 `parse_errors: 0`.
 
 **If failing → fix:** older ontology means a stale graph file. Re-pull the
@@ -313,7 +313,7 @@ exact count.
 > with `{"kind":"client","filter":{},"limit":200}`. Rows should include
 > `client_kind`, `target_service`, paths, `source_layer`.
 
-**Expected (calibration):** `ontology_version=11`, `counts.clients=2`, both
+**Expected (calibration):** `ontology_version=13`, `counts.clients=2`, both
 `rest_template` in the fixture.
 
 **If failing → fix:** ontology < 10 → full rebuild. Zero clients when you
@@ -496,7 +496,7 @@ expect Feign → README §3c brownfield.
 If everything is green:
 
 - Commit `.java-codebase-rag.yml` and `@Codebase*` stubs.
-- Record **ontology 11** (or current `java-codebase-rag meta` value) in your team docs.
+- Record **ontology 13** (or current `java-codebase-rag meta` value) in your team docs.
 - Periodically diff `java-codebase-rag meta` `counts` after large refactors.
 
 If something is red:
@@ -522,4 +522,4 @@ java-codebase-rag meta --source-root tests/bank-chat-system --index-dir /tmp/cal
 
 `build_ast_graph.py` still takes `--kuzu-path` (the Kuzu file). Point it at `<index-dir>/code_graph.kuzu` so it matches the layout `java-codebase-rag meta --index-dir` expects under that directory.
 
-Current snapshot: `tests/bank-chat-system`, `master @ e90cbecc`, ontology **11**.
+Current snapshot: `tests/bank-chat-system`, `chore/docs-sync @ 1fa1b28`, ontology **13**.

docs/paper/README.md

@@ -8,8 +8,9 @@ architecture report:
 > May 2026.
 
 The paper describes the three-layer architecture (Extract \& Store / Navigate /
-Reason), the four-tool MCP surface, the GPS metaphor (locate \-- inspect \-- walk),
-the design principles that drove a v1\->v2 collapse from 9 tools to 4, and what
+Reason), the five-tool MCP surface, the GPS metaphor (locate \-- inspect \-- walk),
+the design principles that drove a v1\->v2 collapse from 9 tools to a small fixed
+set (currently five navigation tools), and what
 the system deliberately does not do. It contains no empirical evaluation;
 testing on real legacy codebases is in progress and the data is not yet ready
 to publish.
@@ -19,7 +20,7 @@ to publish.
 | File | Purpose |
 |---|---|
 | `paper.tex` | Main LaTeX source. Single-file paper, ~320 lines. |
-| `references.bib` | BibTeX bibliography (13 entries). |
+| `references.bib` | BibTeX bibliography. |
 | `figures/layers.tex` | TikZ source: three-layer architecture diagram. |
 | `figures/gps.tex` | TikZ source: GPS-metaphor / three-primitive diagram. |
 | `figures/workflow.tex` | TikZ source: canonical agent-interaction trace. |

docs/paper/figures/gps.tex

@@ -24,14 +24,16 @@
 \node[prim, walk, right=of inspect] (walk)   {WALK\\ \footnotesize\itshape where can I go?};
 
 % --- Tools above each primitive ---
-\node[tool, above=0.7cm of locate, xshift=-0.85cm] (s)  {search};
-\node[tool, above=0.7cm of locate, xshift=0.85cm]  (f)  {find};
-\node[tool, above=0.7cm of inspect]                (d)  {describe};
-\node[tool, above=0.7cm of walk]                   (n)  {neighbors};
+\node[tool, above=0.7cm of locate, xshift=-1.15cm] (s)  {search};
+\node[tool, above=0.7cm of locate, xshift=0cm]      (f)  {find};
+\node[tool, above=0.7cm of locate, xshift=1.15cm]   (r)  {resolve};
+\node[tool, above=0.7cm of inspect]                 (d)  {describe};
+\node[tool, above=0.7cm of walk]                    (n)  {neighbors};
 
 % --- Connections tools -> primitives ---
 \draw[arr] (s)  -- (locate.north -| s);
 \draw[arr] (f)  -- (locate.north -| f);
+\draw[arr] (r)  -- (locate.north -| r);
 \draw[arr] (d)  -- (inspect);
 \draw[arr] (n)  -- (walk);