chore docs: standalone MCP-only AGENT-GUIDE

[HumanBean17]

Summary

• Rewrites docs/AGENT-GUIDE.md copy-paste block as a standalone MCP operating manual: no LanceDB/Kuzu framing, no CLI commands, no links to other repo docs, no ontology migration notes.
• Documents current MCP surface: Producer node kind, DECLARES_PRODUCER edge, producer: / p: ids, and producer NodeFilter keys.
• Aligns README “Driving the MCP” bullet and MCP tool table (find / resolve) with the same surface.

Test plan

• Docs-only change; no code or tests touched.
• Verified copy block is self-contained between <!-- BEGIN / <!-- END markers.

Made with Cursor

[HumanBean17]

Review summary

Verdict: Approve direction; suggest a few small fixes before merge (or as immediate follow-up).

The README find/resolve producer kinds are clearly correct and match server.py. The AGENT-GUIDE rewrite fixes real staleness in the copy block (master still listed three node kinds / omitted Producer). Dropping aspirational edge_filter from the paste block is correct — it is not on the MCP surface yet.

---

What works well

• Producer surface documented end-to-end: DECLARES_PRODUCER, producer:/p: ids, producer_kind / topic_prefix, /producers, decision-tree row.
• Edge taxonomy matches implementation (HTTP_CALLS Client→Route, ASYNC_CALLS Producer→Route, composed keys, virtual keys describe-only).
• Standalone goal achieved: no Lance/Kuzu framing, no CLI commands inside the copy block.

---

Requested changes (before or right after merge)

1. Restore maintenance section outside the copy markers — master had repo-only guidance (bump ontology version, sync README when NodeFilter/MCP changes). The file now ends at <!-- END -->; that hurts maintainers and is not a “CLI dependency” for pasted agents.

2. Brownfield section is HTTP-only — please mention @CodebaseAsyncRoute / @CodebaseProducer with the same exclusivity rule as HTTP stubs (framework listener/producer inference on the same method is not merged). README already treats these as first-class.

3. Ontology version stamp inside the copy block — old guide said “calibrated against v15”; standalone agents cannot detect guide/index drift. One line is enough, e.g. Ontology: 15 — re-pull when your index ontology_version changes (no repo links required).

---

Strongly recommended (minimal scope)

4. Staleness / empty index — one recovery line without CLI names: if results are empty across tools, the index may be missing or stale; agents cannot reindex via MCP — ask the operator. Old guide’s meta check was valuable for pasted-only setups; java-codebase-explore covers CLI but many users paste only this block.

5. resolve when hint_kind omitted — state explicitly that omission searches all four kinds (symbol, route, client, producer). Master incorrectly said “three”.

6. Optional: one line under search that table supports sql / yaml / all (old “indexes Java, SQL, YAML” framing was removed).

---

Accepted trade-offs

• Compressed describe / override-axis detail — OK if neighbors(..., ["OVERRIDES"]) + edge_summary suffice for most cases.
• Removing CLI rows from decision tree and /health — fine given standalone scope; pair with (4) above.

---

CI green; docs-only scope is appropriate. Happy to re-review after the maintenance + async brownfield + ontology stamp tweaks.