docs: agent guide + manual verification checklist (calibrated on bank-chat-system) (#35)

* docs: agent guide + manual verification checklist (calibrated on bank-chat-system)

Two new docs targeting real-world rollout on enterprise Java projects:

docs/AGENT-GUIDE.md — copy-paste-into-QWEN.md/CLAUDE.md block.
  - Forced reasoning preamble (Q-class + Pick + Why on every call)
  - Decision tree mapping user intent to first tool
  - Full reference for all 22 MCP tools with required args, common
    mistakes, minimal examples
  - Ontology glossary (v9) with verbatim enum values for roles,
    capabilities, route_framework, route_kind, client_kind, call_match
  - Recovery playbook (7 common failure modes -> fix)
  - Slash-style prompt aliases (/who-calls, /flow, /impact, /diff-risk, …)

  Engineered for weak / mid models that otherwise pick the wrong tool
  (e.g. semantic search for exact-call-graph questions, simple names
  where FQNs are required).

docs/MANUAL-VERIFICATION-CHECKLIST.md — agent-driven manual test plan.
  - 7 phases: index health, roles & capabilities, routes, call graph,
    cross-service edges, semantic search, brownfield overrides
  - Each item: ☐ checkbox · copy-paste verification prompt · expected
    output (calibrated on tests/bank-chat-system, ontology v9) · fix
  - Pre-flight build instructions and post-completion guidance
  - Calibration source pinned: master @ d62b48c, 84 files / 92 types /
    17 routes / 793 calls / 2 HTTP_CALLS / 5 ASYNC_CALLS

README.md — added 'Driving this MCP from an agent' callout linking
both docs.

Test baseline unchanged: 290 passed, 4 skipped.

* docs(agent-guide): add 'Argument shapes' section + overload guidance

Per real-world feedback: weak models burn calls on argument-shape
mistakes more than tool-selection mistakes. Two specific failures
observed in the wild:

1. Stringified arrays. Agent passes "[\"DTO\",\"ENTITY\"]" instead of
   ["DTO","ENTITY"] for exclude_roles (and similar list params),
   tripping FastMCP/Pydantic validation.

2. Overloaded method needles. Agent passes Foo#bar() for an overloaded
   method that has Foo#bar(String) too, and gets back only the no-arg
   match — interpreting empty/short results as 'method not used'.

New section 'Argument shapes — what the parser actually wants' inserted
between the forced reasoning preamble and the decision tree, covering:

  §A. JSON, not stringified JSON. Right vs wrong table for every list
      and primitive param. One-line rule: if the schema says list[str],
      send a JSON array; if it says str, send a JSON string.

  §B. Method needles. Exact FQN format spec (simple type names only,
      generics erased, no spaces, <init> for ctors, dot-separated nested
      types). Verbatim examples copied from the bank-chat-system index.
      Three needle shapes ranked by precision. Explicit overload-recovery
      recipe (drop parens to list overloads, or use type FQN to fan out
      via DECLARES, or recover the FQN via codebase_search).

  §C. Path templates. The normalised servlet form vs the raw annotation
      value. With a fallback recipe (list_routes path_prefix → copy path).

Also:
- Forced reasoning preamble now nudges 'sanity-check arguments before
  issuing the call'.
- find_callers / find_callees tool reference: corrected the example
  (was com.foo.Bar#baz(java.lang.String) — wrong, parens take simple
  type names) and cross-linked to §B.
- Recovery playbook: 3 new rows (overload mismatch, stringified JSON,
  raw path_template).
- Slash aliases: /who-calls and /calls-from now explicitly require
  fqn-with-sig and document the simple-name fallback.

Test baseline unchanged: 290 passed, 4 skipped.

Author: HumanBean17

README.md

@@ -12,6 +12,17 @@ The product vision for this tooling is proposed in [`propose/PRODUCT-VISION.md`]
 > for the assumptions this MCP makes about a Java repo (annotations, DI patterns,
 > service layout, naming) and a per-file map of where to edit the bundle if you
 > can't or don't want to refactor your codebase to match.
+>
+> **Driving this MCP from an agent:**
+> - [`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md) — copy-paste-into-`QWEN.md` /
+>   `CLAUDE.md` block. Forced reasoning preamble, decision tree, full
+>   reference for all 22 tools, ontology glossary (v9), recovery playbook,
+>   slash-style aliases. Engineered for weak / mid models that otherwise
+>   pick the wrong tool.
+> - [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)
+>   — 7-phase agent-driven verification you run after indexing your real
+>   project. Each item has a copy-paste prompt and calibration data from
+>   `tests/bank-chat-system`.
 
 ## 1. Install