feat(mcp): line numbers in explore output + per-file cluster fixes (#188)

* feat(mcp): line numbers in explore output + per-file cluster fixes

Follow-up to #185. Three changes to codegraph_explore:

1. Source sections now carry cat -n style line-number prefixes
   (<num>\t<code>), so the agent can cite file:line straight from the
   payload instead of re-Reading the file just to recover a line number.
   Isolated A/B: the no-line-numbers arm spent 2 Reads + a grep to find a
   line number the line-numbered arm cited with zero follow-up calls.
   Payload cost ~3-5%. Toggle off with CODEGRAPH_EXPLORE_LINENUMS=0.

2. Per-file cluster selection now ranks clusters containing a query entry
   point ahead of dense declaration blocks. Density-only ranking buried
   the relevant methods (perform/didCreateURLRequest/task in Alamofire's
   Session.swift) under the top-of-file class header + property list.

3. Whole-file "envelope" nodes (a class/struct/etc. spanning >50% of the
   file) are excluded from clustering. The Session class spans ~1,400
   lines; keeping it collapsed every method into one giant cluster that
   tail-trimmed down to just the class header, hiding the methods.

Net vs the 0.7.10 baseline, line numbers on: Alamofire -60%, Excalidraw
-32%, VS Code -12% per explore call.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(mcp): language-neutral omission markers in explore output

The gap separator and the two tail-trim markers used C-style `//`
comments, which aren't comments in Python, Ruby, etc. Switch to plain
`... (gap) ...` / `... (trimmed) ...` so they read correctly inside any
language's fenced source block. With line numbers on, the line-number
jump already corroborates a gap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(mcp): language-neutral truncation marker in codegraph_context

Sibling to the explore marker fix: codegraph_context's code-block
truncation used a C-style `// ... truncated ...`. Switch to
`... (truncated) ...` so it reads correctly in any language's fenced
source block.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore(release): bump version to 0.7.11

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -9,6 +9,18 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+- **MCP / explore**: `codegraph_explore` source sections now carry line
+  numbers (cat -n style `<num>\t<code>`, matching the Read tool). This lets
+  the agent cite `file:line` straight from the explore payload instead of
+  re-opening the file just to find a line number — the dominant residual
+  cost on precise-tracing questions. In an isolated A/B (answer a
+  "which exact line" question with the relevant code already in the
+  payload), the no-line-numbers arm spent 2 file Reads + a grep recovering
+  the line number while the line-numbered arm answered with zero follow-up
+  tool calls. Payload cost is small (~3-5%). Set
+  `CODEGRAPH_EXPLORE_LINENUMS=0` to disable.
+
 ### Changed
 - **MCP / explore**: `codegraph_explore` output is now adaptive to project
   size. The tool used to apply a fixed 35KB cap regardless of how large the
@@ -22,12 +34,23 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   (<5,000) caps at ~28KB; large (<15,000) keeps the historical ~35KB; very
   large goes up to ~38KB. A new per-file char cap also prevents a single
   file with many adjacent symbols from collapsing into one whole-file dump
-  (the Alamofire `Session.swift` case from #185). Measured against the
-  same repos used in the README benchmark: Alamofire ~62% smaller per call,
-  Excalidraw ~35%, VS Code ~14%. Agent-trust floor still holds — the
-  Relationships section, scored cluster selection, and structured-source
-  output are all retained. Thanks to
-  [@essopsp](https://github.com/essopsp) for the repro.
+  (the Alamofire `Session.swift` case from #185). Per-file cluster
+  selection ranks clusters that contain a query entry point ahead of dense
+  declaration blocks, and whole-file "envelope" nodes (a class/struct that
+  spans most of the file) are excluded from clustering so the methods the
+  query asked about aren't buried under the container's opening lines.
+  Measured against the same repos used in the README benchmark, end state
+  with line numbers on: Alamofire ~60% smaller per call, Excalidraw ~32%,
+  VS Code ~12%. Agent-trust floor still holds — the Relationships section,
+  scored cluster selection, and structured-source output are all retained.
+  Thanks to [@essopsp](https://github.com/essopsp) for the repro.
+
+### Fixed
+- **MCP**: source-omission markers in `codegraph_explore` and
+  `codegraph_context` output are now language-neutral (`... (gap) ...`,
+  `... (trimmed) ...`, `... (truncated) ...`) instead of C-style `//`
+  comments, which were misleading inside Python, Ruby, and other non-C
+  fenced source blocks.
 
 ## [0.7.10] - 2026-05-19