diff --git a/README.md b/README.md
index 793d584..d8116ab 100644
--- a/README.md
+++ b/README.md
@@ -3,7 +3,7 @@
 <img src=".github/assets/logo.png" width="280" alt="repowise" /><br />
 **Codebase intelligence for AI-assisted engineering teams.**
 
-Four intelligence layers. Eight MCP tools. One `pip install`.
+Four intelligence layers. Ten MCP tools. One `pip install`.
 
 [![PyPI version](https://img.shields.io/pypi/v/repowise?color=F59520&labelColor=0A0A0A)](https://pypi.org/project/repowise/)
 [![License: AGPL v3](https://img.shields.io/badge/license-AGPL--v3-F59520?labelColor=0A0A0A)](https://www.gnu.org/licenses/agpl-3.0)
@@ -23,12 +23,63 @@ Four intelligence layers. Eight MCP tools. One `pip install`.
 
 When Claude Code reads a 3,000-file codebase, it reads files. It does not know who owns them, which ones change together, which ones are dead, or why they were built the way they were.
 
-repowise fixes that. It indexes your codebase into four intelligence layers — dependency graph, git history, auto-generated documentation, and architectural decisions — and exposes them to Claude Code (and any MCP-compatible AI agent) through eight precisely designed tools.
+repowise fixes that. It indexes your codebase into four intelligence layers — dependency graph, git history, auto-generated documentation, and architectural decisions — and exposes them to Claude Code (and any MCP-compatible AI agent) through ten precisely designed tools.
 
 The result: Claude Code answers *"why does auth work this way?"* instead of *"here is what auth.ts contains."*
 
 ---
 
+## What's new
+
+### Faster indexing
+Indexing is now fully parallel. A `ProcessPoolExecutor` distributes AST parsing across all CPU cores. Graph construction and git history indexing run concurrently via `asyncio.gather`. Per-file git history is fetched through a thread executor with a semaphore to cap concurrency — full parallelism without overwhelming the system. Large repos index noticeably faster.
+
+### RAG-aware documentation generation
+Every wiki page is generated with richer context: before calling the LLM, repowise fetches the already-generated summaries of each file's direct dependencies from the vector store and injects them into the prompt. Generation is topologically sorted so leaf files are always written first. The LLM sees what its dependencies actually do, not just their names — producing more accurate, cross-referenced documentation.
+
+### Atomic three-store transactions
+`AtomicStorageCoordinator` buffers writes across the SQL database, the in-memory dependency graph, and the vector store, then flushes them in a single coordinated operation. If any store fails, all three are rolled back — no partial writes, no silent drift. Run `repowise doctor` to inspect drift across all three stores and repair mismatches.
+
+### Dynamic import hints
+The dependency graph now captures edges that pure AST parsing misses:
+- Django `INSTALLED_APPS`, `ROOT_URLCONF`, and `MIDDLEWARE` settings
+- pytest fixture wiring through `conftest.py`
+- Node/TypeScript path aliases from `tsconfig.json` `paths` and `package.json` `exports`
+
+These edges appear in `get_context`, `get_risk`, and `get_dependency_path` like any other dependency.
+
+### Single-call answers via `get_answer`
+A new `get_answer(question)` MCP tool collapses the typical "search → read → reason" loop into one call. It runs retrieval over the wiki, gates on confidence (top-hit dominance ratio), and synthesizes a 2–5 sentence answer with concrete file/symbol citations. High-confidence answers can be cited directly; ambiguous ones return ranked excerpts so the agent grounds in source. Responses are cached per repository by question hash, so repeated questions cost nothing.
+
+### Symbol lookup via `get_symbol`
+A new `get_symbol(symbol_id)` MCP tool resolves a fully-qualified symbol identifier (e.g. `pkg/module.py::Class::method`) to its definition, returning the source body, signature, file location, and any cross-referenced docstring — without the agent having to grep then read.
+
+### Test files in the documentation layer
+The page generator now treats test files as first-class wiki targets. They have near-zero PageRank (nothing imports them back) but answer real questions like "what test exercises X" or "where is Y verified", which the doc layer is the right place to surface. Filtering remains available via `skip_tests` for users who prefer to exclude them.
+
+### Temporal hotspot decay
+Hotspot scoring now uses an exponentially time-decayed score with a 180-day half-life layered on top of the raw 90-day churn count. A commit from a year ago contributes roughly 25% as much as a commit from today. The score reflects recent activity, not just total volume. Surfaced in `get_overview` and `get_risk`.
+
+### Percentile ranks via SQL window function
+Incremental updates now recompute global percentile ranks for every file using a single `PERCENT_RANK()` SQL window function. Previously this required loading all rows into Python. The new approach is both faster and correct on large repos — no sampling, no approximation.
+
+### PR blast radius
+`get_risk(changed_files=[...])` now returns a full blast-radius report: transitive affected files, co-change warnings for historical co-change partners not included in the PR, recommended reviewers ranked by temporal ownership, test gap detection, and an overall 0–10 risk score. Same flat tool surface — substantially more signal per call.
+
+### Knowledge map in `get_overview`
+`get_overview` now surfaces: top owners across the codebase, "bus factor 1" knowledge silos (files where one person owns >80% of commits), and onboarding targets — high-centrality files with the weakest documentation coverage. Useful for team planning and risk review.
+
+### Test gaps and security signals in `get_risk`
+`get_risk` now includes a `test_gap` flag per file (no test file co-changes detected) and `security_signals` — static pattern detection for common risk categories: authentication bypass patterns, `eval`-family calls, raw SQL string construction, and weak cryptography. Signals appear alongside the existing hotspot and ownership data.
+
+### LLM cost tracking
+Every LLM call is logged to a new `llm_costs` table with operation type, model, token counts, and estimated cost. A new `repowise costs` CLI command lets you group spending by operation, model, or day. The indexing progress bar now shows a live `Cost: $X.XXX` counter next to the spinner.
+
+### Configurable dead-code sensitivity
+The `repowise dead-code` command and the `get_dead_code` MCP tool now expose sensitivity controls: `--min-confidence` (default 0.70), `--include-internals` (include private/underscore-prefixed symbols), and `--include-zombie-packages` (packages present in `package.json` / `pyproject.toml` but unused in the graph). Tune the output to your cleanup goals.
+
+---
+
 ## What repowise builds
 
 repowise runs once, builds everything, then keeps it in sync on every commit.
@@ -84,17 +135,19 @@ Add to your Claude Code config (`~/.claude/claude_desktop_config.json`):
 
 ---
 
-## Eight MCP tools
+## Ten MCP tools
 
 Most tools are designed around data entities — one module, one file, one symbol — which forces AI agents into long chains of sequential calls. repowise tools are designed around **tasks**. Pass multiple targets in one call. Get complete context back.
 
 | Tool | What it answers | When Claude Code calls it |
 |---|---|---|
+| `get_answer(question)` | One-call RAG: retrieves over the wiki, gates on confidence, and synthesizes a cited 2–5 sentence answer. High-confidence answers cite directly; ambiguous queries return ranked excerpts. Responses are cached per repository by question hash. | First call on any code question — collapses search → read → reason into one round-trip |
+| `get_symbol(symbol_id)` | Resolves a qualified symbol id (`path::Class::method`) to its source body, signature, and docstring | When the question names a specific class, function, or method |
 | `get_overview()` | Architecture summary, module map, entry points | First call on any unfamiliar codebase |
-| `get_context(targets, include?)` | Docs, ownership, decisions, freshness for any targets — files, modules, or symbols | Before reading or modifying code. Pass all relevant targets in one call. |
+| `get_context(targets, include?, compact?)` | Docs, ownership, decisions, freshness for any targets — files, modules, or symbols. `compact=True` is the default and bounds the response to ~10K characters; pass `compact=False` for the full structure block, importer list, and per-symbol docstrings | Before reading or modifying code. Pass all relevant targets in one call. |
 | `get_risk(targets?, changed_files?)` | Hotspot scores, dependents, co-change partners, blast radius, recommended reviewers, test gaps, security signals, 0–10 risk score | Before modifying files — understand what could break |
 | `get_why(query?)` | Three modes: NL search over decisions · path-based decisions for a file · no-arg health dashboard | Before architectural changes — understand existing intent |
-| `search_codebase(query)` | Semantic search over the full wiki. Natural language. | When you don't know where something lives |
+| `search_codebase(query)` | Semantic search over the full wiki. Natural language. | When `get_answer` returned low confidence and you need to discover candidate pages by topic |
 | `get_dependency_path(from, to)` | Connection path between two files, modules, or symbols | When tracing how two things are connected |
 | `get_dead_code(min_confidence?, include_internals?, include_zombie_packages?)` | Unreachable code sorted by confidence and cleanup impact | Cleanup tasks |
 | `get_architecture_diagram(module?)` | Mermaid diagram for the repo or a specific module | Documentation and presentation |
@@ -106,7 +159,7 @@ Most tools are designed around data entities — one module, one file, one symbo
 | Approach | Tool calls | Time to first change | What it misses |
 |---|---|---|---|
 | Claude Code alone (no MCP) | grep + read ~30 files | ~8 min | Ownership, prior decisions, hidden coupling |
-| **repowise (8 tools)** | **5 calls** | **~2 min** | **Nothing** |
+| **repowise (10 tools)** | **5 calls** | **~2 min** | **Nothing** |
 
 The 5 calls for that task:
 
@@ -284,7 +337,7 @@ When a senior engineer leaves, the "why" usually leaves with them. Decision inte
 | Git intelligence (hotspots, ownership, co-changes) | ✅ | ❌ | ❌ | ❌ | ✅ |
 | Bus factor analysis | ✅ | ❌ | ❌ | ❌ | ✅ |
 | Architectural decision records | ✅ | ❌ | ❌ | ❌ | ❌ |
-| MCP server for AI agents | ✅ 8 tools | ❌ | ✅ 3 tools | ✅ | ✅ |
+| MCP server for AI agents | ✅ 10 tools | ❌ | ✅ 3 tools | ✅ | ✅ |
 | Auto-generated CLAUDE.md | ✅ | ❌ | ❌ | ❌ | ❌ |
 | Doc freshness scoring | ✅ | ❌ | ❌ | ⚠️ staleness only | ❌ |
 | Incremental updates on commit | ✅ <30s | ✅ | ❌ | ✅ | ✅ |
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index c93f737..9025c3c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -16,7 +16,7 @@ For per-package detail (installation, full API reference, all CLI flags, file ma
 |---------|--------|----------------|
 | `packages/core` | [`packages/core/README.md`](../packages/core/README.md) | Ingestion, generation, persistence, providers — all key classes with code examples |
 | `packages/cli` | [`packages/cli/README.md`](../packages/cli/README.md) | All 10 CLI commands with every flag documented |
-| `packages/server` | [`packages/server/README.md`](../packages/server/README.md) | All REST API endpoints, 8 MCP tools, webhook setup, scheduler jobs |
+| `packages/server` | [`packages/server/README.md`](../packages/server/README.md) | All REST API endpoints, 10 MCP tools, webhook setup, scheduler jobs |
 | `packages/web` | [`packages/web/README.md`](../packages/web/README.md) | Every frontend file with purpose — API client, hooks, components, pages |
 
 ---
@@ -78,7 +78,7 @@ For per-package detail (installation, full API reference, all CLI flags, file ma
 │      Three Stores     │   │              Consumers                  │
 │                      │   │                                         │
 │  SQL (wiki pages,    │   │  Web UI     MCP Server   GitHub Action  │
-│  jobs, symbols,      │   │  (Next.js)  (9 tools)    (CI/CD)        │
+│  jobs, symbols,      │   │  (Next.js)  (10 tools)   (CI/CD)        │
 │  versions)           │   │                                         │
 │                      │   │  repowise CLI                           │
 │  Vector (LanceDB /   │   │  (init, update, watch,                  │
@@ -167,7 +167,7 @@ repowise/
 │   ├── server/                 # Python: FastAPI REST API + MCP server
 │   │   └── src/repowise/server/
 │   │       ├── routers/         # FastAPI routers (repos, pages, jobs, symbols, graph, git, dead-code, decisions, search, claude-md)
-│   │       ├── mcp_server/      # MCP server package (8 tools, split into focused modules)
+│   │       ├── mcp_server/      # MCP server package (10 tools, split into focused modules)
 │   │       ├── webhooks/        # GitHub + GitLab handlers
 │   │       ├── job_executor.py  # Background pipeline executor — bridges REST endpoints to core pipeline
 │   │       └── scheduler.py     # APScheduler background jobs
@@ -219,9 +219,10 @@ Key tables:
 | Table | Purpose |
 |-------|---------|
 | `repos` | Registered repositories, sync state, provider config |
-| `wiki_pages` | All generated wiki pages with content, metadata, confidence score |
+| `wiki_pages` | All generated wiki pages with content, metadata, confidence score, and a short LLM-extracted `summary` (1–3 sentences) used by `get_context` to keep responses bounded |
 | `page_versions` | Full version history of every page (for diff view) |
 | `symbols` | Symbol index: every function, class, method across all files |
+| `answer_cache` | Memoised `get_answer` responses keyed by `(repository_id, question_hash)` plus the provider/model used. Repeated questions return at zero LLM cost; cache entries are invalidated by repository re-indexing. |
 | `generation_jobs` | Job state machine with checkpoint fields for resumability |
 | `webhook_events` | Every received webhook event (deduplication, audit, retry) |
 | `symbol_rename_history` | Detected renames for auditing and targeted text patching |
@@ -424,6 +425,14 @@ cross-package edges tracked in the graph.
 Each `FileInfo` is tagged with: `language`, `is_test`, `is_config`, `is_api_contract`,
 `is_entry_point`, `git_hash`. These tags influence generation priority and prompt choice.
 
+**Test files are first-class wiki targets.** The page generator includes any file
+tagged `is_test=True` that has at least one extracted symbol, even if the file's
+PageRank is near zero (which is typical: nothing imports test files back, so
+graph-centrality metrics never select them on their own). Test files answer
+questions of the form *"what test exercises X"* / *"where is Y verified"*, and
+the doc layer is the right place to surface those. Users who want to exclude
+tests from the wiki entirely can pass `--skip-tests` to `repowise init`.
+
 ### 5.2 AST Parsing
 
 `ASTParser` is a single class that handles all supported languages. There are no
@@ -1103,7 +1112,7 @@ file, tokens used, estimated cost, estimated time remaining).
 repowise includes an interactive chat interface that lets users ask questions about
 their codebase and receive answers grounded in the wiki, dependency graph, git
 history, and architectural decisions. The chat agent uses whichever LLM provider
-the user has configured and has access to all 8 MCP tools.
+the user has configured and has access to all 10 MCP tools.
 
 See [`docs/CHAT.md`](CHAT.md) for the full technical reference covering the
 backend agentic loop, SSE streaming protocol, provider abstraction extensions,
@@ -1114,7 +1123,7 @@ database schema, frontend component architecture, and artifact rendering system.
 - **Provider-agnostic** — the chat agent goes through the same provider abstraction
   as documentation generation. A `ChatProvider` protocol extends `BaseProvider` with
   `stream_chat()` for streaming + tool use without breaking existing callers.
-- **Tool reuse** — the 8 MCP tools are called directly as Python functions (no
+- **Tool reuse** — the 10 MCP tools are called directly as Python functions (no
   subprocess round-trip). Tool schemas are defined once in `chat_tools.py` and
   fed to both the LLM and the executor.
 - **SSE streaming** — `POST /api/repos/{repo_id}/chat/messages` runs the agentic
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index 4614ab6..194d7dd 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -12,6 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **`get_answer` MCP tool** (`tool_answer.py`) — single-call RAG over the wiki layer. Runs retrieval, gates synthesis on top-hit dominance ratio, and returns a 2–5 sentence answer with concrete file/symbol citations plus a `confidence` label. High-confidence responses can be cited directly without verification reads. Backed by an `AnswerCache` table so repeated questions on the same repository cost nothing on the second call.
+- **`get_symbol` MCP tool** (`tool_symbol.py`) — resolves a fully-qualified symbol id (`path::Class::method`, also accepts `Class.method`) to its source body, signature, file location, line range, and docstring. Returns the rich source-line signature (with base classes, decorators, and full type annotations preserved) instead of the stripped DB form.
+- **`Page.summary` column** — short LLM-extracted summary (1–3 sentences) attached to every wiki page during generation. Used by `get_context` to keep context payloads bounded on dense files. Added by alembic migration `0012_page_summary`.
+- **`AnswerCache` table** — memoised `get_answer` responses keyed by `(repository_id, question_hash)` plus the provider/model used. Added by alembic migration `0013_answer_cache`. Cache entries are repository-scoped and invalidated by re-indexing.
+- **Test files in the wiki** — `page_generator._is_significant_file()` now treats any file tagged `is_test=True` (with at least one extracted symbol) as significant, regardless of PageRank. Test files have near-zero centrality because nothing imports them back, but they answer "what test exercises X" / "where is Y verified" questions; the doc layer is the right place to surface those. Filtering remains available via `--skip-tests`.
 - **Overview dashboard** (`/repos/[id]/overview`) — new landing page for each repository with:
   - Health score ring (composite of doc coverage, freshness, dead code, hotspot density, silo risk)
   - Attention panel highlighting items needing action (stale docs, high-risk hotspots, dead code)
@@ -27,6 +32,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Health score utility** (`web/src/lib/utils/health-score.ts`) — composite health score computation, attention item builder, and language aggregation for the overview dashboard
 
 ### Changed
+- **`get_context` default is now `compact=True`** — drops the `structure` block, the `imported_by` list, and per-symbol docstring/end-line fields to keep the response under ~10K characters. Pass `compact=False` for the full payload (e.g. when you specifically need import-graph dependents on a large file).
 - `init_cmd.py` refactored to use shared `persist_pipeline_result()` instead of inline persistence logic
 - Pipeline orchestrator uses async-friendly patterns to keep the event loop responsive during ingestion
 - Sidebar and mobile nav updated to include "Overview" link
diff --git a/docs/CHAT.md b/docs/CHAT.md
index ae84b96..4e9d616 100644
--- a/docs/CHAT.md
+++ b/docs/CHAT.md
@@ -2,7 +2,7 @@
 
 The codebase chat feature lets users have an interactive conversation with their
 codebase. The agent uses whichever LLM provider the user has configured, has
-access to all 8 MCP tools, and streams responses back to the browser in real time
+access to all 10 MCP tools, and streams responses back to the browser in real time
 showing tool calls as they happen and rendering results in an artifact panel.
 
 ---
@@ -158,7 +158,7 @@ class ChatProvider(Protocol):
 
 Defined in `packages/server/src/repowise/server/chat_tools.py`.
 
-Single source of truth for tool schemas and execution. Imports the 8 MCP tool
+Single source of truth for tool schemas and execution. Imports the 10 MCP tool
 functions directly from `repowise.server.mcp_server`.
 
 ```python
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index 0625b96..665eb79 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -315,12 +315,14 @@ This is how you connect repowise to Claude Code, Cursor, Cline, Windsurf, and ot
 | `--transport` | Protocol: `stdio` (default, for editors) or `sse` (for web clients) |
 | `--port` | Port for SSE transport (default: 7338) |
 
-**MCP tools exposed (8 tools):**
+**MCP tools exposed (10 tools):**
 
 | Tool | What it does |
 |------|-------------|
+| `get_answer` | One-call RAG: confidence-gated synthesis over the wiki, with cited 2–5 sentence answers and a per-repository question cache |
+| `get_symbol` | Resolve a qualified symbol id (`path::Class::method`) to its source body, signature, and docstring |
 | `get_overview` | Repository architecture summary, key modules, entry points, git health |
-| `get_context` | Complete context for files/modules/symbols — docs, ownership, decisions, freshness |
+| `get_context` | Complete context for files/modules/symbols — docs, ownership, decisions, freshness. Defaults to `compact=True`; pass `compact=False` for the full structure block and importer list. |
 | `get_risk` | Modification risk assessment — hotspot score, dependents, bus factor, trend |
 | `get_why` | Why code is structured the way it is — architectural decisions, git archaeology |
 | `search_codebase` | Semantic search over wiki with git freshness boosting |
diff --git a/docs/architecture-guide.md b/docs/architecture-guide.md
index e17dea3..1b0ed3c 100644
--- a/docs/architecture-guide.md
+++ b/docs/architecture-guide.md
@@ -890,7 +890,7 @@ The chat endpoint runs an agentic loop where the LLM can call Repowise tools:
 User: "How does auth work in this codebase?"
      │
      ▼
-  LLM receives: system prompt (with repo context) + 8 tool schemas
+  LLM receives: system prompt (with repo context) + 10 tool schemas
      │
      ▼
   Iteration 1: LLM calls search_codebase("authentication")
@@ -914,7 +914,7 @@ Max 10 iterations per request. Streamed via SSE (Server-Sent Events).
 
 ## 8. MCP Tools
 
-MCP (Model Context Protocol) lets AI coding assistants (Claude Code, Cursor, Windsurf, Cline) call Repowise tools directly. There are 8 tools, each answering a specific question.
+MCP (Model Context Protocol) lets AI coding assistants (Claude Code, Cursor, Windsurf, Cline) call Repowise tools directly. There are 10 tools, each answering a specific question.
 
 ### Tool 1: `get_overview` — "What is this codebase?"
 
diff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.py
index 7fa3650..2cc741d 100644
--- a/packages/cli/src/repowise/cli/main.py
+++ b/packages/cli/src/repowise/cli/main.py
@@ -41,3 +41,9 @@ def cli() -> None:
 cli.add_command(serve_command)
 cli.add_command(mcp_command)
 cli.add_command(reindex_command)
+
+
+if __name__ == "__main__":
+    # Allow `python -m repowise.cli.main` (used by repowise-bench when running
+    # against a local source checkout instead of a pip-installed package).
+    cli()
diff --git a/packages/core/alembic/versions/0012_page_summary.py b/packages/core/alembic/versions/0012_page_summary.py
new file mode 100644
index 0000000..aecfc72
--- /dev/null
+++ b/packages/core/alembic/versions/0012_page_summary.py
@@ -0,0 +1,35 @@
+"""Add summary column to wiki_pages.
+
+Stores a 1–3 sentence purpose blurb per page so MCP get_context can return
+narrative file-level descriptions without shipping the full content_md to the
+agent on every turn. Always populated (LLM-extracted in full mode, deterministic
+in index-only mode).
+
+Revision ID: 0012
+Revises: 0011
+Create Date: 2026-04-08
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0012"
+down_revision: str | None = "0011"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "wiki_pages",
+        sa.Column("summary", sa.Text(), nullable=False, server_default=""),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("wiki_pages", "summary")
diff --git a/packages/core/alembic/versions/0013_answer_cache.py b/packages/core/alembic/versions/0013_answer_cache.py
new file mode 100644
index 0000000..25518f5
--- /dev/null
+++ b/packages/core/alembic/versions/0013_answer_cache.py
@@ -0,0 +1,60 @@
+"""Add answer_cache table for get_answer LLM synthesis caching.
+
+Caches the full JSON payload of a get_answer response keyed by repository
+and question hash. Repeat questions from the agent return zero-LLM-cost
+hits.
+
+Revision ID: 0013
+Revises: 0012
+Create Date: 2026-04-08
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0013"
+down_revision: str | None = "0012"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "answer_cache",
+        sa.Column("id", sa.String(32), primary_key=True),
+        sa.Column(
+            "repository_id",
+            sa.String(32),
+            sa.ForeignKey("repositories.id", ondelete="CASCADE"),
+            nullable=False,
+        ),
+        sa.Column("question_hash", sa.String(64), nullable=False),
+        sa.Column("question", sa.Text(), nullable=False),
+        sa.Column("payload_json", sa.Text(), nullable=False),
+        sa.Column("provider_name", sa.String(64), nullable=False, server_default=""),
+        sa.Column("model_name", sa.String(128), nullable=False, server_default=""),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+        ),
+        sa.UniqueConstraint(
+            "repository_id", "question_hash", name="uq_answer_cache_q"
+        ),
+    )
+    op.create_index(
+        "ix_answer_cache_repo",
+        "answer_cache",
+        ["repository_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_answer_cache_repo", table_name="answer_cache")
+    op.drop_table("answer_cache")
diff --git a/packages/core/src/repowise/core/generation/models.py b/packages/core/src/repowise/core/generation/models.py
index 5630ec7..f326b36 100644
--- a/packages/core/src/repowise/core/generation/models.py
+++ b/packages/core/src/repowise/core/generation/models.py
@@ -130,6 +130,10 @@ class GeneratedPage:
     confidence: float = 1.0
     freshness_status: str = "fresh"  # FreshnessStatus literal
     metadata: dict[str, object] = field(default_factory=dict)
+    # 1–3 sentence purpose blurb extracted from the rendered content. Used by
+    # MCP get_context as the default narrative payload (content is gated behind
+    # include=["full_doc"]).
+    summary: str = ""
 
     @property
     def total_tokens(self) -> int:
diff --git a/packages/core/src/repowise/core/generation/page_generator.py b/packages/core/src/repowise/core/generation/page_generator.py
index 4f0c9d3..97f5050 100644
--- a/packages/core/src/repowise/core/generation/page_generator.py
+++ b/packages/core/src/repowise/core/generation/page_generator.py
@@ -964,6 +964,7 @@ def _build_generated_page(
             page_type=page_type,
             title=title,
             content=response.content,
+            summary=_extract_summary(response.content),
             source_hash=source_hash,
             model_name=self._provider.model_name,
             provider_name=self._provider.provider_name,
@@ -987,6 +988,40 @@ def _render(self, template_name: str, **kwargs: Any) -> str:
 # ---------------------------------------------------------------------------
 
 
+def _extract_summary(content: str, max_chars: int = 320) -> str:
+    """Extract a 1–3 sentence purpose blurb from rendered wiki markdown.
+
+    Strategy: walk lines top-to-bottom, skip blanks/headings/list-markers/HTML
+    comments, and take the first prose paragraph. Truncate at sentence boundary
+    near max_chars. Fully deterministic — no extra LLM call.
+    """
+    if not content:
+        return ""
+    para_lines: list[str] = []
+    for raw in content.splitlines():
+        line = raw.strip()
+        if not line:
+            if para_lines:
+                break
+            continue
+        if line.startswith(("#", ">", "```", "---", "<!--", "|", "- ", "* ", "1.")):
+            if para_lines:
+                break
+            continue
+        para_lines.append(line)
+    if not para_lines:
+        return ""
+    text = " ".join(para_lines)
+    if len(text) <= max_chars:
+        return text
+    # Truncate at the last sentence boundary before max_chars
+    cut = text[:max_chars]
+    last_period = max(cut.rfind(". "), cut.rfind("? "), cut.rfind("! "))
+    if last_period > max_chars // 2:
+        return cut[: last_period + 1]
+    return cut.rstrip() + "…"
+
+
 def _is_infra_file(parsed: ParsedFile) -> bool:
     """Return True if the file is an infrastructure file."""
     lang = parsed.file_info.language
@@ -1020,17 +1055,26 @@ def _is_significant_file(
     bet = betweenness.get(path, 0.0)
     is_entry = parsed.file_info.is_entry_point
 
-    # F3: package __init__.py files are module interfaces — always include
+    # Package __init__.py files are module interfaces — always include them
     # if they have any symbols (re-exports, __getattr__, etc.)
     if path.endswith("__init__.py") and len(parsed.symbols) > 0:
         return True
 
+    # Test files are always significant when present. They have near-zero
+    # PageRank because nothing imports them back, but they answer "what
+    # tests exercise X" / "where is Y verified" questions that the doc layer
+    # is the right place to surface. Users who want to exclude tests
+    # entirely can do so via skip_tests in the orchestrator upstream.
+    if parsed.file_info.is_test and len(parsed.symbols) > 0:
+        return True
+
     # Must appear significant in the graph
     if not (is_entry or pr >= pr_threshold or bet > 0.0):
         return False
 
-    # F2: waive symbol requirement for connected files with no original
-    # definitions (e.g. state/config modules imported by many files)
+    # Waive the symbol-count requirement for graph-connected files that have
+    # no original definitions of their own (e.g. state/config modules that
+    # are imported by many files but mostly re-export or assemble values).
     if len(parsed.symbols) < config.file_page_min_symbols:
         return is_entry or pr >= pr_threshold
 
diff --git a/packages/core/src/repowise/core/ingestion/graph.py b/packages/core/src/repowise/core/ingestion/graph.py
index d9d21df..b0e9baf 100644
--- a/packages/core/src/repowise/core/ingestion/graph.py
+++ b/packages/core/src/repowise/core/ingestion/graph.py
@@ -34,6 +34,73 @@
 
 _LARGE_REPO_THRESHOLD = 30_000  # nodes — above this, algorithms are expensive
 
+# Path segments that mark a file as low-value for stem-based import resolution.
+# Files under these directories lose stem-collision tiebreaks against equivalents
+# in the canonical source tree (e.g. a `flask.py` test fixture will never beat
+# `src/flask/__init__.py` for the import-stem "flask"). The list is intentionally
+# language-agnostic — it captures the universal convention that fixture, example,
+# and script trees shadow rather than replace library code.
+_LOW_VALUE_PATH_SEGMENTS = frozenset(
+    {
+        "tests",
+        "test",
+        "_tests",
+        "__tests__",
+        "testing",
+        "test_apps",
+        "testdata",
+        "test_data",
+        "fixtures",
+        "examples",
+        "example",
+        "samples",
+        "sample",
+        "scripts",
+        "benchmarks",
+        "bench",
+        "docs",
+        "doc",
+    }
+)
+
+
+def _stem_priority(path: str, stem: str) -> tuple[int, int, int, str]:
+    """Sort key for choosing among files that share an import stem.
+
+    Lower tuples sort first; callers take ``candidates[0]`` as the resolution.
+    The ordering is deliberately language-agnostic so the same logic governs
+    Python, Go, C/C++, and the generic fallback in :meth:`_resolve_import`.
+
+    Fields, in priority order:
+
+    1. **Parent-directory match.** A file whose parent directory equals the
+       stem is almost always the canonical home for that name across every
+       package layout we care about — ``src/flask/__init__.py`` for stem
+       ``flask``, ``pkg/foo/foo.go`` for stem ``foo``, ``include/json/json.h``
+       for stem ``json``. Strongest single signal we have.
+    2. **Low-value path.** Files under fixture/example/script/doc trees lose
+       to equivalents in the source tree. This catches the failure mode
+       where a test fixture named identically to the package (e.g.
+       ``tests/.../<pkg>.py``) would otherwise win the stem-collision
+       tiebreak and inflate its PageRank by absorbing the entire library's
+       in-edges.
+    3. **Path depth.** Canonical package roots live shallow; deep nesting
+       usually means a vendored copy or a sub-fixture.
+    4. **Lexicographic path.** Deterministic tiebreak so resolution is
+       independent of dict iteration order — critical for reproducible
+       graphs across re-indexes and platforms.
+    """
+    path_obj = Path(path)
+    parts = path_obj.parts
+    if path_obj.name == "__init__.py":
+        # Registered under parent dir name — parent-matching by construction.
+        parent_match = 0
+    else:
+        parent_dir = parts[-2].lower() if len(parts) >= 2 else ""
+        parent_match = 0 if parent_dir == stem else 1
+    low_value = 1 if any(seg.lower() in _LOW_VALUE_PATH_SEGMENTS for seg in parts) else 0
+    return (parent_match, low_value, len(parts), path)
+
 
 class GraphBuilder:
     """Build a dependency graph from a collection of ParsedFile objects.
@@ -82,11 +149,7 @@ def build(self) -> nx.DiGraph:
 
         # Build lookup tables for import resolution
         path_set = set(self._parsed_files.keys())
-        # stem_map: "calculator" → "python_pkg/calculator.py"
-        stem_map: dict[str, str] = {}
-        for p in path_set:
-            stem = Path(p).stem.lower()
-            stem_map[stem] = p
+        stem_map = self._build_stem_map(path_set)
 
         for path, parsed in self._parsed_files.items():
             for imp in parsed.imports:
@@ -335,12 +398,56 @@ def _extract_include_dirs(self, source_file: str) -> list[str]:
             result.append(str(p.resolve()))
         return result
 
+    def _build_stem_map(self, path_set: set[str]) -> dict[str, list[str]]:
+        """Map import-stems to candidate file paths, sorted best-first.
+
+        For Python ``__init__.py`` files the stem is the *parent directory
+        name*, since ``import flask`` resolves to ``src/flask/__init__.py``
+        and not to a file with literal stem ``__init__``. For every other
+        file the stem is the filename without extension. The same map is
+        consulted by Python, Go, C/C++, and the generic fallback in
+        :meth:`_resolve_import` — keeping all collision logic in one place
+        is what makes the resolver deterministic across languages.
+
+        On stem collisions (test fixtures, vendored copies, deep examples)
+        candidates are sorted by :func:`_stem_priority` so callers can take
+        ``candidates[0]`` and get the canonical resolution. The fix that
+        prevents test-fixture-named-like-the-package PageRank inflation
+        lives here, not in any per-directory exclusion list.
+
+        Complexity: O(N) build, plus O(k log k) per bucket of size k. Total
+        worst case O(N log N) when one stem dominates; in practice O(N).
+        """
+        buckets: dict[str, list[str]] = {}
+        for p in path_set:
+            path_obj = Path(p)
+            if path_obj.name == "__init__.py":
+                parent = path_obj.parent.name
+                if not parent:
+                    # Repo-root __init__.py — no meaningful key. Skip rather
+                    # than register under the empty stem.
+                    continue
+                stem = parent.lower()
+            else:
+                stem = path_obj.stem.lower()
+            buckets.setdefault(stem, []).append(p)
+
+        for stem, paths in buckets.items():
+            paths.sort(key=lambda candidate: _stem_priority(candidate, stem))
+        return buckets
+
+    @staticmethod
+    def _stem_lookup(stem_map: dict[str, list[str]], stem: str) -> str | None:
+        """Return the highest-priority path for ``stem``, or None."""
+        candidates = stem_map.get(stem)
+        return candidates[0] if candidates else None
+
     def _resolve_import(
         self,
         module_path: str,
         importer_path: str,
         path_set: set[str],
-        stem_map: dict[str, str],
+        stem_map: dict[str, list[str]],
         language: str,
     ) -> str | None:
         """Best-effort resolve of an import to a known file path."""
@@ -367,17 +474,26 @@ def _resolve_import(
                         return c
                 return None
             # Absolute import: "python_pkg.calculator" → "python_pkg/calculator.py"
+            # Try the obvious filesystem layouts in order. Modern Python
+            # packaging conventions place the package under "src/", so we
+            # check that prefix too — non-existent candidates are filtered
+            # by the path_set membership check, so adding more candidates
+            # is free of regressions.
             dotted = module_path.replace(".", "/")
             candidates = [
                 f"{dotted}.py",
                 f"{dotted}/__init__.py",
+                f"src/{dotted}.py",
+                f"src/{dotted}/__init__.py",
             ]
             for c in candidates:
                 if c in path_set:
                     return c
-            # Stem-only fallback
+            # Stem-only fallback — uses the deterministic priority from
+            # _build_stem_map so test fixtures named like the package
+            # cannot win against the canonical source file.
             stem = module_path.split(".")[-1].lower()
-            return stem_map.get(stem)
+            return self._stem_lookup(stem_map, stem)
 
         # --- TypeScript / JavaScript ---
         if language in ("typescript", "javascript"):
@@ -406,7 +522,7 @@ def _resolve_import(
         if language == "go":
             # Last segment of the import path is the package name
             stem = module_path.rsplit("/", 1)[-1].lower()
-            return stem_map.get(stem)
+            return self._stem_lookup(stem_map, stem)
 
         # --- C / C++ ---
         if language in ("cpp", "c"):
@@ -431,11 +547,11 @@ def _resolve_import(
                     pass
             # 3. Stem-matching fallback
             stem = Path(module_path).stem.lower()
-            return stem_map.get(stem)
+            return self._stem_lookup(stem_map, stem)
 
         # --- Generic fallback: stem matching ---
         stem = Path(module_path).stem.lower()
-        return stem_map.get(stem)
+        return self._stem_lookup(stem_map, stem)
 
     # ------------------------------------------------------------------
     # Co-change edges (Phase 5.5)
diff --git a/packages/core/src/repowise/core/ingestion/parser.py b/packages/core/src/repowise/core/ingestion/parser.py
index cae5605..8c4e35f 100644
--- a/packages/core/src/repowise/core/ingestion/parser.py
+++ b/packages/core/src/repowise/core/ingestion/parser.py
@@ -814,15 +814,24 @@ def _extract_symbol_docstring(def_node: Node, src: str, lang: str) -> str | None
 
 def _build_signature(node_type: str, name: str, params_text: str, def_node: Node, src: str) -> str:
     """Build a human-readable signature string."""
+    # Helper: try multiple field names for "return type", fall back gracefully.
+    def _ret(fields: tuple[str, ...]) -> str:
+        for f in fields:
+            n = def_node.child_by_field_name(f)
+            if n is not None:
+                return f" -> {_node_text(n, src)}"
+        return ""
+
     if node_type == "function_definition":
         # Detect async via child "async" keyword (tree-sitter-python >= 0.23)
         prefix = "async " if any(c.type == "async" for c in def_node.children) else ""
-        # Get return type annotation for Python
-        ret_node = def_node.child_by_field_name("return_type")
-        ret_text = f" -> {_node_text(ret_node, src)}" if ret_node else ""
-        return f"{prefix}def {name}{params_text}{ret_text}"
-    if node_type in ("function_declaration", "generator_function_declaration", "function_item"):
-        return f"function {name}{params_text}"
+        return f"{prefix}def {name}{params_text}{_ret(('return_type',))}"
+    if node_type == "function_item":
+        # Rust: return_type field
+        return f"fn {name}{params_text}{_ret(('return_type',))}"
+    if node_type in ("function_declaration", "generator_function_declaration"):
+        # TS/JS use return_type; Go uses result
+        return f"function {name}{params_text}{_ret(('return_type', 'result'))}"
     if node_type in ("class_definition", "class_declaration", "abstract_class_declaration"):
         base = f"class {name}"
         if params_text:
@@ -835,9 +844,14 @@ def _build_signature(node_type: str, name: str, params_text: str, def_node: Node
     if node_type == "enum_declaration":
         return f"enum {name}"
     if node_type == "method_definition":
-        return f"{name}{params_text}"
+        # TypeScript/JavaScript class method
+        return f"{name}{params_text}{_ret(('return_type',))}"
     if node_type == "method_declaration":
-        return f"func ({name}) method{params_text}"
+        # Go method: include receiver text and result type
+        recv_node = def_node.child_by_field_name("receiver")
+        recv_text = _node_text(recv_node, src) if recv_node else ""
+        recv_prefix = f"{recv_text} " if recv_text else ""
+        return f"func {recv_prefix}{name}{params_text}{_ret(('result',))}"
     if node_type in ("struct_item", "struct_specifier"):
         return f"struct {name}"
     if node_type in ("enum_item", "enum_specifier"):
diff --git a/packages/core/src/repowise/core/ingestion/traverser.py b/packages/core/src/repowise/core/ingestion/traverser.py
index 25894a7..fa878b0 100644
--- a/packages/core/src/repowise/core/ingestion/traverser.py
+++ b/packages/core/src/repowise/core/ingestion/traverser.py
@@ -64,6 +64,25 @@
         ".cache",
         ".idea",
         ".vscode",
+        # NOTE: test/tests/spec/specs/__tests__ are intentionally NOT
+        # blocked here. They used to be excluded as a workaround for a
+        # PageRank-inflation bug in graph.py, where a test fixture named
+        # like the package (e.g. tests/.../<pkg>.py) would dominate the
+        # import stem map and collect spurious in-edges from the entire
+        # library. That bug is now fixed in graph.py via deterministic
+        # stem disambiguation (see _build_stem_map / _stem_priority), so
+        # test files can be indexed safely. Their content is needed to
+        # answer questions about test helpers and fixtures. Files under
+        # these directories are still tagged is_test=True via
+        # _is_test_file() so downstream consumers can filter them when
+        # appropriate.
+        #
+        # The following ARE still blocked because they typically hold
+        # binary fixtures, generated artifacts, or browser-driven test
+        # rigs whose content rarely answers code questions:
+        "e2e",
+        "fixtures",
+        "conftest",
     }
 )
 
diff --git a/packages/core/src/repowise/core/persistence/crud.py b/packages/core/src/repowise/core/persistence/crud.py
index 577abb8..b3654bd 100644
--- a/packages/core/src/repowise/core/persistence/crud.py
+++ b/packages/core/src/repowise/core/persistence/crud.py
@@ -209,6 +209,7 @@ async def upsert_page(
     page_type: str,
     title: str,
     content: str,
+    summary: str = "",
     target_path: str,
     source_hash: str,
     model_name: str,
@@ -261,6 +262,7 @@ async def upsert_page(
         existing.page_type = page_type
         existing.title = title
         existing.content = content
+        existing.summary = summary
         existing.target_path = target_path
         existing.source_hash = source_hash
         existing.model_name = model_name
@@ -284,6 +286,7 @@ async def upsert_page(
             page_type=page_type,
             title=title,
             content=content,
+            summary=summary,
             target_path=target_path,
             source_hash=source_hash,
             model_name=model_name,
@@ -323,6 +326,7 @@ async def upsert_page_from_generated(
         page_type=gp.page_type,  # type: ignore[attr-defined]
         title=gp.title,  # type: ignore[attr-defined]
         content=gp.content,  # type: ignore[attr-defined]
+        summary=getattr(gp, "summary", "") or "",
         target_path=gp.target_path,  # type: ignore[attr-defined]
         source_hash=gp.source_hash,  # type: ignore[attr-defined]
         model_name=gp.model_name,  # type: ignore[attr-defined]
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 1ab2229..3f03538 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -100,6 +100,11 @@ class Page(Base):
     page_type: Mapped[str] = mapped_column(String(64), nullable=False)
     title: Mapped[str] = mapped_column(Text, nullable=False)
     content: Mapped[str] = mapped_column(Text, nullable=False)
+    # 1–3 sentence purpose blurb. Always populated (LLM-extracted from content
+    # for full mode, deterministic structure summary for index-only mode).
+    # Surfaced by get_context as the default narrative; content is gated
+    # behind include=["full_doc"] to keep MCP responses small.
+    summary: Mapped[str] = mapped_column(Text, nullable=False, default="")
     target_path: Mapped[str] = mapped_column(Text, nullable=False)
     source_hash: Mapped[str] = mapped_column(String(64), nullable=False)
     model_name: Mapped[str] = mapped_column(String(128), nullable=False)
@@ -475,3 +480,41 @@ class DeadCodeFinding(Base):
     analyzed_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False, default=_now_utc
     )
+
+
+class AnswerCache(Base):
+    """Cached LLM-synthesized answers from get_answer.
+
+    Keyed by (repo_id, question_hash). The hash is computed from the
+    normalized question text only — answer cache invalidation on index
+    change is handled by deleting rows for a repository when its alembic
+    head advances (cheap to rebuild).
+
+    Storing payload as a single JSON text column keeps the schema stable
+    across get_answer response shape changes.
+    """
+
+    __tablename__ = "answer_cache"
+
+    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_uuid)
+    repository_id: Mapped[str] = mapped_column(
+        String(32), ForeignKey("repositories.id", ondelete="CASCADE"), nullable=False
+    )
+    # SHA-256 hex of the normalized (lowercased + stripped) question.
+    question_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    # Original (un-normalized) question, kept for human inspection.
+    question: Mapped[str] = mapped_column(Text, nullable=False)
+    # Full JSON payload from get_answer (answer, citations, confidence,
+    # fallback_targets, retrieval).
+    payload_json: Mapped[str] = mapped_column(Text, nullable=False)
+    # Provider + model used for the synthesis call (lets us invalidate
+    # selectively if a better model is configured later).
+    provider_name: Mapped[str] = mapped_column(String(64), nullable=False, default="")
+    model_name: Mapped[str] = mapped_column(String(128), nullable=False, default="")
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), nullable=False, default=_now_utc
+    )
+
+    __table_args__ = (
+        UniqueConstraint("repository_id", "question_hash", name="uq_answer_cache_q"),
+    )
diff --git a/packages/server/README.md b/packages/server/README.md
index f4a9a96..8aafb3e 100644
--- a/packages/server/README.md
+++ b/packages/server/README.md
@@ -11,7 +11,7 @@ FastAPI REST API, webhook handlers, MCP server, and background job scheduler for
 | Component | Description |
 |-----------|-------------|
 | **REST API** | FastAPI application with full CRUD for repos, pages, symbols, jobs, git analytics, dead code |
-| **MCP Server** | 8 MCP tools for AI coding assistants (Claude Code, Cursor, Cline) |
+| **MCP Server** | 10 MCP tools for AI coding assistants (Claude Code, Cursor, Cline) |
 | **Webhooks** | GitHub and GitLab push event handlers — trigger incremental updates automatically |
 | **Scheduler** | APScheduler background jobs — polling fallback, stale page decay, periodic re-sync |
 
@@ -153,7 +153,7 @@ Job progress events (`JobProgressEvent`) carry: `event` type, `file` currently b
 
 ## MCP Server
 
-repowise exposes 8 MCP tools for AI coding assistants. Start the MCP server via:
+repowise exposes 10 MCP tools for AI coding assistants. Start the MCP server via:
 
 ```bash
 repowise mcp                          # stdio transport (Claude Code, Cursor, Cline)
diff --git a/packages/server/src/repowise/server/chat_tools.py b/packages/server/src/repowise/server/chat_tools.py
index 1ca0669..53dde52 100644
--- a/packages/server/src/repowise/server/chat_tools.py
+++ b/packages/server/src/repowise/server/chat_tools.py
@@ -1,6 +1,6 @@
 """Chat tool registry — single source of truth for tool schemas and execution.
 
-Imports the 8 MCP tool functions directly and exposes them as a callable registry
+Imports the 10 MCP tool functions directly and exposes them as a callable registry
 for the agentic chat loop. Also provides OpenAI-format tool definitions for the LLM.
 """
 
diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.py
index 8dd038e..99a441b 100644
--- a/packages/server/src/repowise/server/mcp_server/__init__.py
+++ b/packages/server/src/repowise/server/mcp_server/__init__.py
@@ -1,4 +1,4 @@
-"""repowise MCP Server — 9 tools for AI coding assistants.
+"""repowise MCP Server — 10 tools for AI coding assistants.
 
 Exposes the full repowise wiki as queryable tools via the MCP protocol.
 Supports both stdio transport (Claude Code, Cursor, Cline) and SSE transport
@@ -27,6 +27,7 @@
     mcp,
     run_mcp,
 )
+from repowise.server.mcp_server.tool_answer import get_answer
 from repowise.server.mcp_server.tool_context import get_context
 from repowise.server.mcp_server.tool_dead_code import get_dead_code
 from repowise.server.mcp_server.tool_decision_records import update_decision_records
@@ -38,6 +39,7 @@
 from repowise.server.mcp_server.tool_overview import get_overview
 from repowise.server.mcp_server.tool_risk import get_risk
 from repowise.server.mcp_server.tool_search import search_codebase
+from repowise.server.mcp_server.tool_symbol import get_symbol
 from repowise.server.mcp_server.tool_why import get_why
 
 # ---------------------------------------------------------------------------
@@ -90,12 +92,14 @@ def __setattr__(self, name: str, value: Any) -> None:
     "_get_repo",
     "_is_path",
     "create_mcp_server",
+    "get_answer",
     "get_architecture_diagram",
     "get_context",
     "get_dead_code",
     "get_dependency_path",
     "get_overview",
     "get_risk",
+    "get_symbol",
     "get_why",
     "mcp",
     "run_mcp",
diff --git a/packages/server/src/repowise/server/mcp_server/_meta.py b/packages/server/src/repowise/server/mcp_server/_meta.py
new file mode 100644
index 0000000..891fa72
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/_meta.py
@@ -0,0 +1,137 @@
+"""Shared `_meta` envelope helpers for MCP tool responses.
+
+Every tool can attach a small `_meta` dict to its response with timing and
+optional hint text. The hint is the killer feature: a short, conservative
+nudge toward the cheaper next-tool when one obviously applies. Hints are
+intentionally narrow — pushing every agent toward `get_symbol` regardless of
+question shape would replicate the over-trust failure mode that drove
+jcodemunch's accuracy regression on alive-with-dead-exports tasks.
+
+Rules of thumb baked into the hint generators:
+  * NEVER suggest a more compact tool when the original question contains
+    explanation words ("explain", "why", "how does", "what is the relationship",
+    "describe").
+  * Only suggest get_symbol when the agent has already pinpointed a single
+    symbol or single file — never as a starting move.
+  * Hints are advisory; the harness/agent is free to ignore them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Question patterns where narrative wiki context wins over symbol-body slicing.
+# Used to suppress "use get_symbol" hints — those questions need surrounding prose.
+_EXPLAIN_TOKENS = (
+    "explain",
+    "why ",
+    "why is",
+    "why does",
+    "why was",
+    "how does",
+    "how do",
+    "how is",
+    "how are",
+    "what is the relationship",
+    "describe",
+    "walk me through",
+    "tell me about",
+    "purpose of",
+)
+
+
+def is_explanation_question(question: str | None) -> bool:
+    """True if the question reads like 'explain X', not 'find X'.
+
+    Used as a guard before any hint that would push the agent toward
+    symbol-level (narrower) retrieval. Conservative by design: any explanation
+    cue suppresses the hint.
+    """
+    if not question:
+        return False
+    q = question.strip().lower()
+    return any(tok in q for tok in _EXPLAIN_TOKENS)
+
+
+def build_meta(
+    *,
+    timing_ms: float | None = None,
+    hint: str | None = None,
+    cached: bool = False,
+    extra: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Construct a `_meta` envelope. All fields optional, omitted if falsy.
+
+    Stable shape:
+      {
+        "timing_ms": float,   # tool wall-time (omitted if None)
+        "hint":      str,     # short follow-up suggestion (omitted if None)
+        "cached":    bool,    # only included when True
+        ...extras
+      }
+    """
+    out: dict[str, Any] = {}
+    if timing_ms is not None:
+        out["timing_ms"] = round(float(timing_ms), 2)
+    if hint:
+        out["hint"] = hint
+    if cached:
+        out["cached"] = True
+    if extra:
+        out.update(extra)
+    return out
+
+
+def context_hint(targets: list[str], compact: bool) -> str | None:
+    """Hint for `get_context` callers.
+
+    Conservative: only fires when the call shape suggests the agent could
+    have used a cheaper tool, AND the suggestion is unambiguously safe.
+    """
+    if compact:
+        # Already in compact mode — don't push further.
+        return None
+    if not targets:
+        return None
+    # Single file target where the agent is likely to follow up with a Read:
+    # nudge toward get_symbol so they slice instead of reading the whole file.
+    if len(targets) == 1 and "::" not in targets[0] and "/" in targets[0]:
+        return (
+            "If you only need one function from this file, call "
+            "get_symbol(symbol_id='{path}::{name}') to get just that "
+            "function body — cheaper than Read.".format(
+                path=targets[0], name="<symbol_name>"
+            )
+        )
+    return None
+
+
+def symbol_hint(symbol_id: str, end_line: int, start_line: int) -> str | None:
+    """Hint for `get_symbol` callers.
+
+    Suggests context_lines expansion only for very small symbols where the
+    body alone may be insufficient.
+    """
+    span = max(end_line - start_line, 0)
+    if span < 5:
+        return (
+            "Small symbol — pass context_lines=10 if you need surrounding "
+            "context (imports, sibling defs)."
+        )
+    return None
+
+
+def answer_hint(confidence: str, retrieval_count: int) -> str | None:
+    """Hint for `get_answer` callers.
+
+    Encourages verification when confidence is low; never tells the agent to
+    "trust the answer" — that's the over-trust failure mode.
+    """
+    if confidence == "low":
+        return (
+            "Low confidence — Read the listed fallback_targets to verify "
+            "before answering."
+        )
+    if retrieval_count == 0:
+        return "No wiki hits — fall back to search_codebase or Grep."
+    return None
diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer.py
new file mode 100644
index 0000000..1d3c053
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_answer.py
@@ -0,0 +1,809 @@
+"""MCP Tool: get_answer — RAG-style synthesis over the wiki layer.
+
+Single-call retrieval + LLM synthesis. Replaces the agent's multi-turn
+search → context → read loop with one tool call that returns:
+
+    {
+      "answer":            str   — 2–5 sentence synthesised answer
+      "citations":         list  — file paths backing the answer
+      "confidence":        str   — "high" | "medium" | "low"
+      "fallback_targets":  list  — top retrieval hits the agent should Read
+                                   to verify (always present)
+      "retrieval":         list  — raw top-N hits with snippets
+    }
+
+When no LLM provider is configured, the tool degrades to retrieval-only
+mode (returns ranked hits + snippets, confidence="low") so C1 / index-only
+deployments still benefit from the structured single-call shortcut.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import hashlib
+import json as _json
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import select
+
+from repowise.core.persistence.database import get_session
+from repowise.core.persistence.models import AnswerCache, Page, WikiSymbol
+from repowise.server.mcp_server import _state
+from repowise.server.mcp_server._helpers import _get_repo
+from repowise.server.mcp_server._meta import answer_hint as _answer_hint
+from repowise.server.mcp_server._meta import build_meta as _build_meta
+from repowise.server.mcp_server._server import mcp
+
+# How many top retrieval hits to enrich with WikiSymbol context. Enriching
+# every hit produces large responses that bloat the cached prompt prefix on
+# multi-turn agent sessions without changing the answer — the agent typically
+# cites the top-1 file. Top-2 captures the primary navigation need with a
+# bounded payload.
+_ENRICH_TOP_N_HITS = 2
+# How many symbols per enriched file. Bounded to keep the context block from
+# growing unboundedly on dense files; the limit is sufficient to surface both
+# foundational types and a representative function/method.
+_MAX_SYMBOLS_PER_HIT = 4
+
+# Sort priority by symbol kind. Classes first because "what does X do" /
+# "which class inherits from Y" questions resolve at the class level. Then
+# top-level functions, then methods (which usually only matter once the
+# class context is established).
+_KIND_PRIORITY = {"class": 0, "interface": 0, "function": 1, "method": 2}
+# Per-symbol docstring truncation. Keeps the context block bounded — the
+# first sentence is typically sufficient and trailing prose mostly contributes
+# cache-write cost on follow-up turns.
+_MAX_SYMBOL_DOC_CHARS = 120
+
+# Confidence gate for synthesis. When the top retrieval hit is NOT clearly
+# dominant relative to the second-best hit, skip LLM synthesis and return
+# ranked snippets only. This forces the agent to ground in source rather than
+# trust a possibly-wrong frame. Generic, repo-agnostic, no question parsing.
+# Failure modes addressed:
+#   (a) wrong-target retrieval where top-1 and top-2 are both plausible;
+#   (b) synthesis hallucination on tangential top hits.
+_DOMINANCE_RATIO = 1.2
+_COVERAGE_THRESHOLD = 0.66
+# The dominance ratio threshold (top_score / second_score >= 1.2x) separates
+# reliable retrievals from ambiguous ones. This is a property of BM25-style
+# retrieval with a coverage re-ranker on top, not of any particular repository;
+# tune if a deployment shows systematic over- or under-gating.
+
+# When the gate triggers and we drop synthesis, fetch this many chars of
+# real page content per top hit so the agent has substantive raw material
+# to ground in (vs. one-line summary that's too thin to act on).
+_GATED_EXCERPT_CHARS = 600
+_GATED_RETURN_HITS = 3
+
+# Intersection-retrieval connectives. If a question contains any of these
+# (case-insensitive whole-word), it's likely a relational/multi-entity
+# question. We split the question on the connective, run two FTS passes,
+# and boost any page that appears in BOTH result sets — the page at the
+# intersection is much more likely to be the actual answer than a page
+# at the top of either single-side query.
+# This is grammar, not domain — the same list applies to any English-language
+# code question, independent of the repository or codebase.
+_RELATIONAL_CONNECTIVES = (
+    " between ", " from ", " across ", " through ", " with ",
+    " and ", " versus ", " vs ",
+)
+
+# Term-coverage re-ranker tuning. Multiplies BM25 by (FLOOR + (1-FLOOR)*coverage)
+# where coverage = (# distinct query terms present in hit) / (# query terms).
+# FLOOR=0.5 → single-concept questions (coverage≈1.0) are unaffected;
+# multi-constraint questions where a hit covers 1/3 of terms get scored at 0.67
+# of their raw BM25 (vs 1.0 for a hit covering 3/3). Conjunctive coverage
+# becomes a tie-breaker rather than a hard filter.
+_COVERAGE_FLOOR = 0.5
+# English stopwords — minimal list, just enough to keep "what is the" from
+# dominating coverage. Not language-specific, not repo-specific.
+_STOPWORDS = frozenset({
+    "a","an","the","is","are","was","were","be","been","being","of","to","in",
+    "on","at","by","for","with","from","as","that","this","these","those","it",
+    "its","and","or","but","not","no","do","does","did","done","have","has",
+    "had","what","which","who","whom","whose","when","where","why","how","can",
+    "could","should","would","may","might","will","shall","i","you","he","she",
+    "we","they","me","him","her","us","them","my","your","his","their","our",
+    "if","then","than","so","such","there","here","about","into","through",
+    "between","across","over","under","up","down","out","off","via",
+})
+# Cap on bytes read from source per symbol when we recover a real signature
+# from disk (multi-line def with type annotations). Anything longer than this
+# gets truncated; the agent can call get_symbol for the full body.
+_MAX_RICH_SIG_LINES = 4
+
+
+def _hash_question(question: str) -> str:
+    """Stable SHA-256 of the normalized question. Lowercase + strip + collapse ws."""
+    norm = " ".join(question.lower().strip().split())
+    return hashlib.sha256(norm.encode("utf-8")).hexdigest()
+
+_log = __import__("logging").getLogger("repowise.mcp.answer")
+
+_SYSTEM_PROMPT = (
+    "You are a code-aware retrieval assistant. Given a developer question and "
+    "excerpts from a project wiki, answer in 2–5 sentences. Cite the source "
+    "files by relative path inline like (path/to/file.py). If the excerpts do "
+    "not contain enough information, say so explicitly and suggest which files "
+    "the developer should inspect. Never invent file paths."
+)
+
+_USER_TEMPLATE = """\
+Question: {question}
+
+Project wiki excerpts (top {n} retrieval hits):
+
+{context}
+
+Answer in 2–5 sentences. Cite file paths inline. If the excerpts are not
+sufficient, say so and list the most likely files to inspect.
+"""
+
+
+def _resolve_provider_for_answer():
+    """Best-effort provider lookup mirroring cli/helpers.resolve_provider.
+
+    Avoids the click dependency from the cli package. Returns a BaseProvider
+    or None if no API key / provider is configured.
+    """
+    try:
+        from repowise.core.providers.llm.registry import get_provider
+    except Exception:
+        _log.debug("Provider registry import failed", exc_info=True)
+        return None
+
+    name = os.environ.get("REPOWISE_PROVIDER")
+    model = os.environ.get("REPOWISE_DOC_MODEL") or os.environ.get("REPOWISE_MODEL")
+
+    def _try(provider_name: str, **kwargs: Any):
+        try:
+            return get_provider(provider_name, **kwargs)
+        except Exception:
+            _log.debug("get_provider(%s) failed", provider_name, exc_info=True)
+            return None
+
+    # Explicit selection wins.
+    if name:
+        kw: dict[str, Any] = {}
+        if model:
+            kw["model"] = model
+        if name == "anthropic" and os.environ.get("ANTHROPIC_API_KEY"):
+            kw["api_key"] = os.environ["ANTHROPIC_API_KEY"]
+        elif name == "openai" and os.environ.get("OPENAI_API_KEY"):
+            kw["api_key"] = os.environ["OPENAI_API_KEY"]
+        elif name == "gemini" and (
+            os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY")
+        ):
+            kw["api_key"] = os.environ.get("GEMINI_API_KEY") or os.environ.get(
+                "GOOGLE_API_KEY"
+            )
+        elif name == "ollama" and os.environ.get("OLLAMA_BASE_URL"):
+            kw["base_url"] = os.environ["OLLAMA_BASE_URL"]
+        return _try(name, **kw)
+
+    # Auto-detect from API keys.
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        kw = {"api_key": os.environ["ANTHROPIC_API_KEY"]}
+        if model:
+            kw["model"] = model
+        return _try("anthropic", **kw)
+    if os.environ.get("OPENAI_API_KEY"):
+        kw = {"api_key": os.environ["OPENAI_API_KEY"]}
+        if model:
+            kw["model"] = model
+        return _try("openai", **kw)
+    if os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY"):
+        kw = {
+            "api_key": os.environ.get("GEMINI_API_KEY")
+            or os.environ.get("GOOGLE_API_KEY")
+        }
+        if model:
+            kw["model"] = model
+        return _try("gemini", **kw)
+    if os.environ.get("OLLAMA_BASE_URL"):
+        kw = {"base_url": os.environ["OLLAMA_BASE_URL"]}
+        if model:
+            kw["model"] = model
+        return _try("ollama", **kw)
+    return None
+
+
+def _build_context_block(hits: list[dict], max_chars_per_hit: int = 800) -> str:
+    """Format retrieval hits as a compact text block for the LLM.
+
+    Each hit includes:
+      * file path + title + retrieval score
+      * file-level summary (Page.summary, capped at max_chars_per_hit)
+      * up to _MAX_SYMBOLS_PER_HIT WikiSymbol entries (signature + truncated
+        docstring) — the critical addition that turns get_answer from a
+        navigator into a real synthesizer for symbol-level questions.
+    """
+    parts = []
+    for i, h in enumerate(hits, start=1):
+        body_src = h.get("summary") or h.get("snippet") or ""
+        body = body_src[:max_chars_per_hit]
+        block = [
+            f"[{i}] {h['target_path']} (score={h['score']:.3f})",
+            f"    title: {h['title']}",
+            f"    summary: {body}",
+        ]
+        symbols = h.get("symbols") or []
+        if symbols:
+            block.append("    symbols:")
+            for s in symbols[:_MAX_SYMBOLS_PER_HIT]:
+                sig = s.get("signature") or s.get("name") or ""
+                kind = s.get("kind") or "?"
+                doc = (s.get("docstring") or "").strip()
+                if doc:
+                    doc_one_line = " ".join(doc.split())[:_MAX_SYMBOL_DOC_CHARS]
+                    block.append(f"      - [{kind}] {sig}")
+                    block.append(f"          {doc_one_line}")
+                else:
+                    block.append(f"      - [{kind}] {sig}")
+        parts.append("\n".join(block))
+    return "\n\n".join(parts)
+
+
+def _read_signature_from_source(
+    repo_root: Path | None, file_path: str, start_line: int
+) -> str | None:
+    """Read the symbol's actual signature line from disk.
+
+    Returns the def/class line (or its multi-line continuation) verbatim from
+    the source file. Captures everything WikiSymbol.signature strips:
+      * base classes for `class Foo(Bar, Baz):`
+      * decorators (one line above the def)
+      * full type annotations across line continuations
+
+    None on any failure — caller falls back to the stored signature.
+    """
+    if repo_root is None:
+        return None
+    try:
+        abs_path = (repo_root / file_path).resolve()
+        # Defense in depth: never read outside the repo root.
+        try:
+            abs_path.relative_to(repo_root.resolve())
+        except ValueError:
+            return None
+        text = abs_path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    lines = text.splitlines()
+    if not lines or start_line < 1 or start_line > len(lines):
+        return None
+    # Walk forward up to _MAX_RICH_SIG_LINES until we close the parenthesis
+    # group (Python signatures often span multiple lines for type hints).
+    sig_lines: list[str] = []
+    paren_depth = 0
+    for i in range(start_line - 1, min(start_line - 1 + _MAX_RICH_SIG_LINES, len(lines))):
+        line = lines[i]
+        sig_lines.append(line.strip())
+        paren_depth += line.count("(") - line.count(")")
+        if line.rstrip().endswith(":") and paren_depth <= 0:
+            break
+    if not sig_lines:
+        return None
+    return " ".join(sig_lines)
+
+
+async def _hydrate_symbols_for_hits(
+    session, repo_id: str, hits: list[dict]
+) -> None:
+    """Mutate `hits` in place: attach `symbols` list to top-N file_page hits.
+
+    Only the top _ENRICH_TOP_N_HITS hits get enriched — others would just bloat
+    the cached prompt prefix on follow-up turns without changing the answer.
+
+    For each enriched symbol we ALSO try to recover the real source-line
+    signature from disk (`_read_signature_from_source`) so base classes,
+    decorators, and full type annotations reach the LLM. WikiSymbol.signature
+    strips these at parse time, so the on-disk read is what gives the LLM a
+    faithful view of the symbol's interface.
+    """
+    # Identify the top file_page hits in retrieval-rank order. `hits` is
+    # already sorted by descending score upstream.
+    enrich_paths: list[str] = []
+    for h in hits:
+        if (
+            h.get("target_path")
+            and h.get("page_type") == "file_page"
+            and len(enrich_paths) < _ENRICH_TOP_N_HITS
+        ):
+            enrich_paths.append(h["target_path"])
+    if not enrich_paths:
+        return
+
+    res = await session.execute(
+        select(WikiSymbol)
+        .where(
+            WikiSymbol.repository_id == repo_id,
+            WikiSymbol.file_path.in_(enrich_paths),
+        )
+        .order_by(WikiSymbol.file_path, WikiSymbol.start_line)
+    )
+    by_file: dict[str, list[dict]] = {}
+    repo_root = Path(_state._repo_path) if _state._repo_path else None
+    for row in res.scalars().all():
+        rich_sig = _read_signature_from_source(
+            repo_root, row.file_path, row.start_line
+        )
+        by_file.setdefault(row.file_path, []).append(
+            {
+                "name": row.name,
+                "kind": row.kind,
+                # Prefer the real source line (has bases / decorators / types)
+                # falling back to the stripped WikiSymbol.signature on failure.
+                "signature": rich_sig or row.signature,
+                "docstring": row.docstring or "",
+                "start_line": row.start_line,
+            }
+        )
+    # Cap each list to _MAX_SYMBOLS_PER_HIT. Sort by start_line ASC —
+    # natural document order is the most general default. Kind-priority
+    # sorting (classes before functions before methods) is available via
+    # _KIND_PRIORITY but is not applied here, since reordering symbols away
+    # from source order can mislead the LLM about file structure.
+    for path, syms in by_file.items():
+        syms.sort(key=lambda s: s["start_line"])
+        by_file[path] = syms[:_MAX_SYMBOLS_PER_HIT]
+    for h in hits:
+        if h.get("target_path") in by_file:
+            h["symbols"] = by_file[h["target_path"]]
+
+
+def _split_relational(question: str) -> list[str] | None:
+    """If the question is relational (contains a connective like 'and' or
+    'between'), split it into two sub-queries on the FIRST matching
+    connective. Returns [left, right] or None if not relational.
+
+    Heuristic only — works on English grammar, not on code or repo terms.
+    """
+    q = " " + question.strip() + " "
+    qlow = q.lower()
+    for conn in _RELATIONAL_CONNECTIVES:
+        idx = qlow.find(conn)
+        if idx > 0:
+            left = q[:idx].strip()
+            right = q[idx + len(conn):].strip()
+            # Both sides must have at least 3 content terms to be a real
+            # multi-entity question (not e.g. "what is X and how").
+            if len(_question_terms(left)) >= 3 and len(_question_terms(right)) >= 3:
+                return [left, right]
+    return None
+
+
+async def _intersection_boost(question: str, hits: list[dict]) -> None:
+    """For relational questions, boost any hit that appears in both halves
+    of a split-FTS retrieval. Mutates `hits` in place: adds a multiplicative
+    bonus to `score` for hits that appear in both subset retrievals.
+
+    Universal IR principle: pages at the intersection of two query halves
+    are much more likely to answer relational questions than pages at the
+    top of either half alone. Independent of repo or domain.
+    """
+    parts = _split_relational(question)
+    if parts is None or _state._fts is None:
+        return
+    sub_hit_ids: list[set] = []
+    for sub_q in parts:
+        try:
+            sub = await asyncio.wait_for(
+                _state._fts.search(sub_q, limit=15), timeout=3.0
+            )
+            sub_hit_ids.append({h.page_id for h in sub})
+        except Exception:
+            return
+    if len(sub_hit_ids) < 2:
+        return
+    intersection = sub_hit_ids[0] & sub_hit_ids[1]
+    if not intersection:
+        return
+    # 2× boost for hits at the intersection — strong enough to overtake
+    # a single-side top hit, not so strong that it ignores BM25 entirely.
+    for h in hits:
+        if h.get("page_id") in intersection:
+            h["score"] = h.get("score", 0.0) * 2.0
+            h["_intersection"] = True
+    hits.sort(key=lambda h: h["score"], reverse=True)
+
+
+async def _enrich_gated_excerpts(hits: list[dict]) -> None:
+    """For the gated (low-confidence) return path, fetch real page content
+    for top hits so the agent has substantive raw material instead of
+    one-line summaries. Mutates `hits` in place — adds an `excerpt` field.
+
+    Universal motivation: thin retrieval output forces consumers to fall
+    back on priors instead of grounding in source. Symmetric with the
+    enrichment we already do for synthesis.
+    """
+    if not hits:
+        return
+    page_ids = [h["page_id"] for h in hits[:_GATED_RETURN_HITS] if h.get("page_id")]
+    if not page_ids:
+        return
+    try:
+        async with get_session(_state._session_factory) as session:
+            res = await session.execute(
+                select(Page.id, Page.content_md).where(Page.id.in_(page_ids))
+            )
+            content_by_id = {row[0]: (row[1] or "") for row in res.all()}
+    except Exception:
+        return
+    for h in hits[:_GATED_RETURN_HITS]:
+        body = content_by_id.get(h.get("page_id"), "")
+        if body:
+            h["excerpt"] = body[:_GATED_EXCERPT_CHARS]
+
+
+def _question_terms(question: str) -> list[str]:
+    """Extract content terms from a question. Lowercase, alnum-tokenized,
+    stopwords + length<3 dropped. Used by the term-coverage re-ranker."""
+    import re
+    raw = re.findall(r"[a-zA-Z0-9_]+", question.lower())
+    return [t for t in raw if len(t) >= 3 and t not in _STOPWORDS]
+
+
+def _rerank_by_coverage(hits: list[dict], question: str) -> list[dict]:
+    """Re-rank FTS hits by term-coverage boost on top of BM25.
+
+    For each hit, compute the fraction of distinct query terms present in
+    (title + snippet + summary), then multiply the raw BM25 score by
+    (FLOOR + (1-FLOOR)*coverage). Single-concept questions (coverage≈1.0
+    across all hits) are unaffected; multi-constraint questions push hits
+    that cover all the terms above hits that repeat just one term.
+
+    This addresses a common BM25 failure mode where a hit that matches one
+    constraint very strongly can outrank a hit that matches all constraints
+    moderately — the latter is usually the better answer for multi-constraint
+    questions.
+    """
+    terms = set(_question_terms(question))
+    if not terms or not hits:
+        return hits
+    n_terms = len(terms)
+    for h in hits:
+        haystack = " ".join([
+            h.get("title", "") or "",
+            h.get("snippet", "") or "",
+            h.get("summary", "") or "",
+        ]).lower()
+        # Count distinct terms present (substring match — FTS5 already handles
+        # stemming upstream, so we keep this simple).
+        present = sum(1 for t in terms if t in haystack)
+        coverage = present / n_terms
+        raw = h.get("score", 0.0)
+        h["_coverage"] = coverage
+        h["_raw_score"] = raw
+        h["score"] = raw * (_COVERAGE_FLOOR + (1.0 - _COVERAGE_FLOOR) * coverage)
+    hits.sort(key=lambda h: h["score"], reverse=True)
+    return hits
+
+
+def _confidence_from_scores(scores: list[float]) -> str:
+    """Map raw FTS scores to a coarse confidence label.
+
+    The thresholds are intentionally generous on the low end — when retrieval
+    finds *anything* we still let the agent see it, but mark it 'low' so the
+    workflow forces verification.
+    """
+    if not scores:
+        return "low"
+    top = scores[0]
+    gap = top - (scores[1] if len(scores) > 1 else 0.0)
+    if top >= 1.0 and gap >= 0.2:
+        return "high"
+    if top >= 0.5:
+        return "medium"
+    return "low"
+
+
+@mcp.tool()
+async def get_answer(
+    question: str,
+    scope: str | None = None,
+    repo: str | None = None,
+) -> dict:
+    """One-call RAG: answer a code question. Always your first call.
+
+    Returns {answer, citations, confidence, fallback_targets}. If
+    confidence=="high" and the answer names concrete files/symbols, cite it
+    directly — do NOT verify by Read. Only fall back to search_codebase +
+    get_context if confidence=="low" or the answer is hedged.
+
+    Args:
+        question: developer question.
+        scope: optional path prefix to restrict retrieval (e.g. "src/pkg/").
+        repo: repository identifier; usually omitted.
+    """
+    t0 = time.perf_counter()
+    if not question or not question.strip():
+        return {
+            "answer": "",
+            "citations": [],
+            "confidence": "low",
+            "fallback_targets": [],
+            "retrieval": [],
+            "error": "question is required",
+            "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000),
+        }
+
+    async with get_session(_state._session_factory) as session:
+        repository = await _get_repo(session, repo)
+        repo_id = repository.id
+
+    # --- Cache lookup --------------------------------------------------------
+    # Scope: ignore the (rare) `scope` argument in the cache key for now;
+    # scoped queries are uncommon and including scope would balloon hit rate
+    # variance. We hash on (repo_id, normalized_question) only.
+    qhash = _hash_question(question)
+    async with get_session(_state._session_factory) as session:
+        res = await session.execute(
+            select(AnswerCache).where(
+                AnswerCache.repository_id == repo_id,
+                AnswerCache.question_hash == qhash,
+            )
+        )
+        cached = res.scalar_one_or_none()
+    if cached is not None:
+        with contextlib.suppress(Exception):
+            payload = _json.loads(cached.payload_json)
+            payload["_meta"] = _build_meta(
+                timing_ms=(time.perf_counter() - t0) * 1000,
+                cached=True,
+                hint=_answer_hint(payload.get("confidence", "low"), len(payload.get("retrieval", []))),
+            )
+            return payload
+
+    # --- Retrieval (FTS) ---------------------------------------------------
+    raw_hits: list[Any] = []
+    if _state._fts is not None:
+        with contextlib.suppress(Exception):
+            # Pull a wider candidate set so the term-coverage re-ranker has
+            # room to push conjunctive matches up the list before we cap to 5.
+            raw_hits = await asyncio.wait_for(
+                _state._fts.search(question, limit=15), timeout=5.0
+            )
+
+    # Hydrate hits with target_path + summary from the Page table.
+    hits: list[dict] = []
+    if raw_hits:
+        page_ids = [h.page_id for h in raw_hits]
+        async with get_session(_state._session_factory) as session:
+            res = await session.execute(
+                select(
+                    Page.id,
+                    Page.target_path,
+                    Page.summary,
+                    Page.page_type,
+                ).where(Page.id.in_(page_ids))
+            )
+            meta_by_id = {
+                row[0]: {
+                    "target_path": row[1],
+                    "summary": row[2] or "",
+                    "page_type": row[3],
+                }
+                for row in res.all()
+            }
+        for h in raw_hits:
+            meta = meta_by_id.get(h.page_id, {})
+            target_path = meta.get("target_path", "")
+            if scope and target_path and not target_path.startswith(scope):
+                continue
+            hits.append(
+                {
+                    "page_id": h.page_id,
+                    "title": h.title,
+                    "target_path": target_path,
+                    "page_type": meta.get("page_type", h.page_type),
+                    "snippet": h.snippet,
+                    "summary": meta.get("summary", ""),
+                    "score": float(h.score or 0.0),
+                }
+            )
+
+    # Term-coverage re-rank before the cap so conjunctive matches survive.
+    hits = _rerank_by_coverage(hits, question)
+    # Intersection-retrieval boost for relational questions (multi-entity).
+    # Pages at the intersection of two split-FTS halves get a 2× bonus.
+    with contextlib.suppress(Exception):
+        await _intersection_boost(question, hits)
+    # Always cap retrieval hits at 5 for the response payload.
+    hits = hits[:5]
+
+    # Enrich each file_page hit with its top-N WikiSymbol rows. This is the
+    # critical fix for symbol-level questions — without it the LLM only sees
+    # file-level summaries and consistently refuses to identify specific
+    # classes/functions named in the question.
+    if hits:
+        with contextlib.suppress(Exception):
+            async with get_session(_state._session_factory) as session:
+                await _hydrate_symbols_for_hits(session, repo_id, hits)
+
+    fallback_targets = [
+        h["target_path"] for h in hits if h.get("target_path")
+    ]
+
+    if not hits:
+        return {
+            "answer": "",
+            "citations": [],
+            "confidence": "low",
+            "fallback_targets": [],
+            "retrieval": [],
+            "note": (
+                "No wiki hits for this question. Fall back to "
+                "search_codebase or Grep to locate candidate files."
+            ),
+            "_meta": _build_meta(
+                timing_ms=(time.perf_counter() - t0) * 1000,
+                hint=_answer_hint("low", 0),
+            ),
+        }
+
+    # --- Confidence gate ---------------------------------------------------
+    # Skip synthesis when retrieval is NOT clearly dominant. The dominance
+    # ratio (top score / second score) is the sole gating criterion: above
+    # the threshold the top hit is reliably the right answer; below it the
+    # top-1 / top-2 ambiguity is large enough that we hand the agent ranked
+    # excerpts and let it ground in source.
+    #
+    # Coverage (fraction of query terms present in the top hit) is also
+    # available via the re-ranker and is used to bias score-based ranking,
+    # but is intentionally NOT used as a hard gate here. Natural-language
+    # questions rarely have all their content terms co-occurring in a single
+    # page (typical coverage is 0.15–0.25), so a coverage threshold over-
+    # fires on confidently-dominant retrievals and degrades the cheap path.
+    if len(hits) >= 2:
+        top_score = hits[0].get("score", 0.0)
+        second_score = hits[1].get("score", 0.0) or 1e-9
+        dominant = (top_score / second_score) >= _DOMINANCE_RATIO
+        if not dominant:
+            # Enrich top hits with substantive excerpts so the agent has
+            # real material to ground in (not one-line summaries).
+            await _enrich_gated_excerpts(hits)
+            return {
+                "answer": "",
+                "citations": [],
+                "confidence": "low",
+                "fallback_targets": fallback_targets,
+                "retrieval": hits[:_GATED_RETURN_HITS],
+                "note": (
+                    "Multiple plausible candidates — synthesis skipped to "
+                    "avoid anchoring on a wrong frame. Each retrieval entry "
+                    "includes an excerpt from the page; read them and pick "
+                    "the one that actually answers the question."
+                ),
+                "_meta": _build_meta(
+                    timing_ms=(time.perf_counter() - t0) * 1000,
+                    hint=_answer_hint("low", len(hits)),
+                ),
+            }
+
+    # Confidence is the only axis we gate on. We deliberately do NOT add a
+    # second gate keyed on question shape (e.g. relational questions
+    # containing connectives like "between", "and", "from"). Relational vs
+    # non-relational is the wrong axis to gate on: the hard relational
+    # failures already surface as low-dominance retrievals and are caught
+    # by the gate above, while a shape-based gate over-fires on confidently
+    # dominant relational questions and pushes cost back onto the agent's
+    # own reasoning loop.
+
+    # --- Synthesis (LLM) ---------------------------------------------------
+    provider = _resolve_provider_for_answer()
+    if provider is None:
+        # Retrieval-only mode (no provider). Return the hits so the agent can
+        # at least skip the search_codebase step.
+        return {
+            "answer": "",
+            "citations": [],
+            "confidence": "low",
+            "fallback_targets": fallback_targets,
+            "retrieval": hits,
+            "note": (
+                "No LLM provider configured (set REPOWISE_PROVIDER + API key). "
+                "Returning retrieval hits only — Read the listed files to answer."
+            ),
+            "_meta": _build_meta(
+                timing_ms=(time.perf_counter() - t0) * 1000,
+                hint=_answer_hint("low", len(hits)),
+            ),
+        }
+
+    user_prompt = _USER_TEMPLATE.format(
+        question=question.strip(),
+        n=len(hits),
+        context=_build_context_block(hits),
+    )
+
+    answer_text = ""
+    try:
+        response = await asyncio.wait_for(
+            provider.generate(
+                system_prompt=_SYSTEM_PROMPT,
+                user_prompt=user_prompt,
+                max_tokens=512,
+                temperature=0.2,
+            ),
+            timeout=30.0,
+        )
+        answer_text = (response.content or "").strip()
+    except Exception as exc:
+        _log.warning("get_answer LLM call failed: %s", exc)
+        return {
+            "answer": "",
+            "citations": [],
+            "confidence": "low",
+            "fallback_targets": fallback_targets,
+            "retrieval": hits,
+            "note": f"LLM synthesis failed ({type(exc).__name__}). Read the listed files to answer.",
+            "_meta": _build_meta(
+                timing_ms=(time.perf_counter() - t0) * 1000,
+                hint=_answer_hint("low", len(hits)),
+            ),
+        }
+
+    citations = [
+        h["target_path"] for h in hits if h["target_path"] and h["target_path"] in answer_text
+    ]
+    if not citations:
+        # Fall back to top-2 retrieval paths so the agent always has something to verify.
+        citations = fallback_targets[:2]
+
+    # Compute confidence from the dominance ratio (top hit vs second hit).
+    # The dominance ratio is a more reliable separator than absolute BM25
+    # thresholds, which tend to label most retrievals "high" indiscriminately.
+    if len(hits) >= 2:
+        _top = hits[0].get("score", 0.0)
+        _second = hits[1].get("score", 0.0) or 1e-9
+        _ratio = _top / _second
+    else:
+        _ratio = float("inf") if hits else 0.0
+    if _ratio >= _DOMINANCE_RATIO:
+        confidence = "high"
+    else:
+        confidence = "medium"
+
+    payload = {
+        "answer": answer_text,
+        "citations": citations,
+        "confidence": confidence,
+        "fallback_targets": fallback_targets,
+        "retrieval": hits,
+    }
+    # When confidence is high, document what the signal means so the consumer
+    # knows it can cite the answer directly without falling back to Read.
+    if confidence == "high":
+        payload["note"] = (
+            "High confidence: top retrieval result clearly dominates "
+            f"(dominance ratio {_ratio:.2f}x). Cite this answer directly; "
+            "no further verification needed unless the question explicitly "
+            "requires checking additional files."
+        )
+
+    # Persist to cache. Best-effort: cache failures must NEVER block the
+    # response (we already have the answer in hand).
+    if answer_text:
+        with contextlib.suppress(Exception):
+            async with get_session(_state._session_factory) as session:
+                row = AnswerCache(
+                    repository_id=repo_id,
+                    question_hash=qhash,
+                    question=question.strip(),
+                    payload_json=_json.dumps(payload),
+                    provider_name=getattr(provider, "provider_name", "") or "",
+                    model_name=getattr(provider, "model_name", "") or "",
+                )
+                session.add(row)
+                await session.commit()
+
+    payload["_meta"] = _build_meta(
+        timing_ms=(time.perf_counter() - t0) * 1000,
+        hint=_answer_hint(confidence, len(hits)),
+    )
+    return payload
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context.py b/packages/server/src/repowise/server/mcp_server/tool_context.py
index daf8631..2214b1e 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context.py
@@ -4,8 +4,28 @@
 
 import asyncio
 import json
+import logging
 from typing import Any
 
+logger = logging.getLogger(__name__)
+
+# --- Output size budget -------------------------------------------------------
+# The Claude Code harness rejects MCP tool results whose stringified form exceeds
+# ~10k tokens (it refuses to inline them and then refuses to Read the spilled
+# file). When that happens the agent falls back to multiple get_symbol calls,
+# each of which re-plays the cached system prompt — a significant cost driver
+# on dense files in long multi-turn agent sessions.
+#
+# We therefore cap get_context output well below that ceiling. 8000 tokens
+# leaves headroom for the wrapping JSON envelope and _meta fields the harness
+# adds on top. The estimator is intentionally dependency-free: 4 chars/token is
+# the widely-quoted average for English + code on BPE tokenizers and is within
+# ~20% of tiktoken for typical wiki content. Precise counting is unnecessary
+# because we only need to stay comfortably under the hard limit.
+_TOKEN_BUDGET = 8000
+_CHARS_PER_TOKEN = 4
+_CHAR_BUDGET = _TOKEN_BUDGET * _CHARS_PER_TOKEN
+
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -14,20 +34,48 @@
     DecisionRecord,
     GitMetadata,
     GraphEdge,
+    GraphNode,
     Page,
     Repository,
     WikiSymbol,
 )
 from repowise.server.mcp_server import _state
 from repowise.server.mcp_server._helpers import _get_repo
+from repowise.server.mcp_server._meta import build_meta as _build_meta
+from repowise.server.mcp_server._meta import context_hint as _context_hint
 from repowise.server.mcp_server._server import mcp
 
 
+def _synthesize_structural_summary(
+    file_path: str, classes: list[str], functions: list[str]
+) -> str:
+    """Build a deterministic 1-line summary when no LLM-generated summary exists.
+
+    Used in --index-only mode (no wiki pages) and as a fallback when an LLM
+    page predates the summary column. Always returns a non-empty string so the
+    agent never sees a missing field.
+    """
+    name = file_path.rsplit("/", 1)[-1]
+    parts: list[str] = []
+    if classes:
+        head = ", ".join(classes[:3])
+        more = f" (+{len(classes) - 3} more)" if len(classes) > 3 else ""
+        parts.append(f"defines {head}{more}")
+    if functions:
+        head = ", ".join(functions[:3])
+        more = f" (+{len(functions) - 3} more)" if len(functions) > 3 else ""
+        parts.append(f"function{'s' if len(functions) > 1 else ''} {head}{more}")
+    if not parts:
+        return f"{name}: empty or non-symbol file"
+    return f"{name}: " + "; ".join(parts) + "."
+
+
 async def _resolve_one_target(
     session: AsyncSession,
     repository: Repository,
     target: str,
     include: set[str] | None,
+    compact: bool = False,
 ) -> dict:
     """Resolve a single target and return its full context."""
     repo_id = repository.id
@@ -102,57 +150,76 @@ async def _resolve_one_target(
                     file_path_for_git = target
 
     if target_type is None:
-        # F1: check git_metadata — file may exist but have no wiki page
+        # Fallback 1: index-only mode (no wiki pages) — return graph node + symbols if present
         res = await session.execute(
-            select(GitMetadata).where(
-                GitMetadata.repository_id == repo_id,
-                GitMetadata.file_path == target,
+            select(GraphNode).where(
+                GraphNode.repository_id == repo_id,
+                GraphNode.node_id == target,
             )
         )
-        meta = res.scalar_one_or_none()
-        if meta:
-            return {
-                "target": target,
-                "error": (
-                    f"'{target}' exists in the repository but has no wiki page. "
-                    "This usually means the file has too few symbols or is below "
-                    "the PageRank threshold. Run `repowise update` to regenerate docs."
-                ),
-                "exists_in_git": True,
-                "last_commit_at": meta.last_commit_at.isoformat() if meta.last_commit_at else None,
-                "primary_owner": meta.primary_owner_name,
-                "is_hotspot": meta.is_hotspot,
-            }
-
-        # F5: fuzzy path suggestions — match by filename or partial path
-        tail = target.rsplit("/", 1)[-1]
-        res = await session.execute(
-            select(GitMetadata.file_path)
-            .where(
-                GitMetadata.repository_id == repo_id,
-                GitMetadata.file_path.contains(tail),
+        gnode = res.scalar_one_or_none()
+        if gnode is not None:
+            target_type = "file"
+            file_path_for_git = target
+            page = None  # no wiki page; subsequent blocks must guard for this
+
+        # Fallback 2: check git_metadata — file may exist but have no wiki page AND no graph node
+        if target_type is None:
+            res = await session.execute(
+                select(GitMetadata).where(
+                    GitMetadata.repository_id == repo_id,
+                    GitMetadata.file_path == target,
+                )
             )
-            .limit(5)
-        )
-        suggestions = [row[0] for row in res.all() if row[0] != target]
-        if suggestions:
-            return {
-                "target": target,
-                "error": f"Target not found: '{target}'",
-                "suggestions": suggestions,
-            }
+            meta = res.scalar_one_or_none()
+            if meta:
+                return {
+                    "target": target,
+                    "error": (
+                        f"'{target}' exists in the repository but has no wiki page. "
+                        "This usually means the file has too few symbols or is below "
+                        "the PageRank threshold. Run `repowise update` to regenerate docs."
+                    ),
+                    "exists_in_git": True,
+                    "last_commit_at": meta.last_commit_at.isoformat() if meta.last_commit_at else None,
+                    "primary_owner": meta.primary_owner_name,
+                    "is_hotspot": meta.is_hotspot,
+                }
 
-        return {"target": target, "error": f"Target not found: '{target}'"}
+        # Fallback 3: fuzzy path suggestions — match by filename or partial path.
+        # Only runs if the prior fallbacks didn't resolve the target.
+        if target_type is None:
+            tail = target.rsplit("/", 1)[-1]
+            res = await session.execute(
+                select(GitMetadata.file_path)
+                .where(
+                    GitMetadata.repository_id == repo_id,
+                    GitMetadata.file_path.contains(tail),
+                )
+                .limit(5)
+            )
+            suggestions = [row[0] for row in res.all() if row[0] != target]
+            if suggestions:
+                return {
+                    "target": target,
+                    "error": f"Target not found: '{target}'",
+                    "suggestions": suggestions,
+                }
+            return {"target": target, "error": f"Target not found: '{target}'"}
 
     result_data["target"] = target
     result_data["type"] = target_type
 
     # --- Docs ---
     if include is None or "docs" in include:
+        want_full_doc = bool(include and "full_doc" in include)
         docs: dict[str, Any] = {}
         if target_type == "file":
-            docs["title"] = page.title
-            docs["content_md"] = page.content
+            if page is not None:
+                docs["title"] = page.title
+                docs["summary"] = page.summary or ""
+                if want_full_doc:
+                    docs["content_md"] = page.content
             # Symbols in this file
             res = await session.execute(
                 select(WikiSymbol).where(
@@ -161,22 +228,73 @@ async def _resolve_one_target(
                 )
             )
             symbols = res.scalars().all()
-            docs["symbols"] = [
-                {"name": s.name, "kind": s.kind, "signature": s.signature} for s in symbols
-            ]
-            # Importers
-            res = await session.execute(
-                select(GraphEdge).where(
-                    GraphEdge.repository_id == repo_id,
-                    GraphEdge.target_node_id == target,
+            classes = [s.name for s in symbols if s.kind == "class"]
+            functions = [s.name for s in symbols if s.kind in ("function", "method")]
+            if compact:
+                # Compact mode: name+kind+signature+line only. Drop docstring,
+                # start_line/end_line range, structure block, and imported_by.
+                # Used by agents that already know the file and just want a
+                # cheap signature index.
+                docs["symbols"] = [
+                    {
+                        "name": s.name,
+                        "kind": s.kind,
+                        "signature": s.signature,
+                        "line": s.start_line,
+                    }
+                    for s in symbols
+                ]
+                if not docs.get("summary"):
+                    docs["summary"] = _synthesize_structural_summary(
+                        target, classes, functions
+                    )
+            else:
+                docs["symbols"] = [
+                    {
+                        "name": s.name,
+                        "kind": s.kind,
+                        "signature": s.signature,
+                        "start_line": s.start_line,
+                        "end_line": s.end_line,
+                        "docstring": (s.docstring or "")[:400],
+                    }
+                    for s in symbols
+                ]
+                # Structure summary block — quick scan of what's in the file
+                total_loc = max((s.end_line for s in symbols), default=0)
+                avg_complexity = (
+                    sum(s.complexity_estimate for s in symbols) / len(symbols)
+                    if symbols
+                    else 0
                 )
-            )
-            importers = res.scalars().all()
-            docs["imported_by"] = [e.source_node_id for e in importers]
+                docs["structure"] = {
+                    "classes": classes,
+                    "functions": functions,
+                    "symbol_count": len(symbols),
+                    "total_loc": total_loc,
+                    "avg_complexity": round(avg_complexity, 2),
+                }
+                # Fallback summary: if no Page (index-only mode) or page.summary
+                # is empty, synthesize a deterministic one-liner from structure.
+                if not docs.get("summary"):
+                    docs["summary"] = _synthesize_structural_summary(
+                        target, classes, functions
+                    )
+                # Importers
+                res = await session.execute(
+                    select(GraphEdge).where(
+                        GraphEdge.repository_id == repo_id,
+                        GraphEdge.target_node_id == target,
+                    )
+                )
+                importers = res.scalars().all()
+                docs["imported_by"] = [e.source_node_id for e in importers]
 
         elif target_type == "module":
             docs["title"] = page.title
-            docs["content_md"] = page.content
+            docs["summary"] = page.summary or ""
+            if want_full_doc:
+                docs["content_md"] = page.content
             # Child file pages
             res = await session.execute(
                 select(Page).where(
@@ -203,10 +321,13 @@ async def _resolve_one_target(
             docs["signature"] = sym.signature
             docs["file_path"] = sym.file_path
             docs["docstring"] = sym.docstring or ""
-            # File page content as documentation
+            # File page summary (full content gated behind include=["full_doc"])
             sym_page_id = f"file_page:{sym.file_path}"
             sym_page = await session.get(Page, sym_page_id)
-            docs["documentation"] = sym_page.content if sym_page else ""
+            if sym_page is not None:
+                docs["file_summary"] = sym_page.summary or ""
+                if want_full_doc:
+                    docs["documentation"] = sym_page.content
             # Used by
             res = await session.execute(
                 select(GraphEdge).where(
@@ -349,39 +470,241 @@ async def _resolve_one_target(
     return result_data
 
 
+def _estimate_tokens(obj: Any) -> int:
+    """Cheap upper-bound token estimate for an arbitrary JSON-serialisable object.
+
+    Serialises to compact JSON (the wire format the MCP layer eventually emits)
+    and divides by ``_CHARS_PER_TOKEN``. We use the serialised form — not just
+    raw text fields — because structural JSON overhead (quotes, braces, field
+    names) is non-trivial and is what the downstream tokenizer actually sees.
+    """
+    return len(json.dumps(obj, separators=(",", ":"), default=str)) // _CHARS_PER_TOKEN
+
+
+# Heavy optional fields we can strip from a target's docs block without losing
+# its identity. Ordering matters: earlier entries are dropped first because they
+# carry the most bytes per unit of navigational value.
+_HEAVY_DOC_FIELDS: tuple[str, ...] = ("content_md", "documentation", "file_summary")
+
+
+def _symbol_priority(sym: dict[str, Any], query_terms: set[str]) -> tuple[int, int, int]:
+    """Return a sort key (higher = keep) for a symbol within a target.
+
+    Priority order (language-agnostic — no Python-specific heuristics):
+      1. Exact name match against any user query term.
+      2. Substring / case-insensitive match against query terms.
+      3. Kind rank: classes/types outrank functions/methods which outrank the
+         rest. This mirrors navigational usefulness across Python, TS, Go,
+         Rust, C++, etc. where a type anchors a module more than a helper fn.
+      4. PageRank / centrality if present on the dict (forward-compatible —
+         ``get_context`` doesn't currently populate it but ``_resolve_one_target``
+         may in the future).
+    """
+    name = (sym.get("name") or "").lower()
+    exact = 1 if name and name in query_terms else 0
+    fuzzy = 1 if any(t and t in name for t in query_terms) else 0
+    kind = (sym.get("kind") or "").lower()
+    kind_rank = {
+        "class": 3, "interface": 3, "struct": 3, "trait": 3, "type": 3, "enum": 3,
+        "function": 2, "method": 2,
+    }.get(kind, 1)
+    centrality = int((sym.get("pagerank") or sym.get("centrality") or 0) * 1000)
+    return (exact * 10 + fuzzy * 5 + kind_rank, centrality, -len(json.dumps(sym, default=str)))
+
+
+def _query_terms_for(target: str) -> set[str]:
+    """Derive cheap query terms from a target string for symbol prioritisation.
+
+    ``get_context`` has no explicit query argument, so we fall back to the
+    target identifier itself — the tail of a file path, or the raw symbol name.
+    This is deliberately coarse: it just nudges symbol retention toward the
+    thing the caller asked about.
+    """
+    tail = target.rsplit("/", 1)[-1].lower()
+    # Strip common extension if present (language-agnostic: split once on '.').
+    if "." in tail:
+        tail = tail.rsplit(".", 1)[0]
+    return {t for t in (tail, target.lower()) if t}
+
+
+def _truncate_to_budget(
+    result: dict[str, Any],
+    char_budget: int = _CHAR_BUDGET,
+) -> dict[str, Any]:
+    """Cap the ``get_context`` response at roughly ``_TOKEN_BUDGET`` tokens.
+
+    Strategy (applied in order, stopping as soon as the budget is met):
+
+    1. **Strip heavy optional doc fields** (``content_md``, ``documentation``,
+       ``file_summary``) from each target. These are 1–2k tokens apiece and
+       duplicate information the agent can re-request via ``full_doc``.
+    2. **Shrink symbol lists within each target**, keeping the highest-priority
+       symbols per ``_symbol_priority``. This preserves the navigational index
+       (names, signatures, line numbers) while dropping bulk docstrings.
+    3. **Drop whole targets** from the tail of the list. Per spec we prefer
+       keeping fewer full-fidelity targets over many stubs, so once symbols
+       can't shrink further we evict entire targets rather than gutting them.
+
+    Adds ``truncated: bool``, ``dropped_targets: list[str]``, and
+    ``dropped_symbols: dict[target, list[name]]`` top-level fields — additive
+    only, existing callers are unaffected.
+
+    Edge cases:
+      * Empty ``targets`` → returns unchanged with ``truncated=False``.
+      * A single target whose symbol list alone busts the budget → we reduce
+        symbols down to 1 and accept the overshoot rather than returning an
+        empty response. The ``truncated`` flag still fires.
+      * Targets that carry an ``error`` field (not-found) are cheap and are
+        preserved unless literally nothing else fits.
+    """
+    result.setdefault("truncated", False)
+    result.setdefault("dropped_targets", [])
+    result.setdefault("dropped_symbols", {})
+
+    targets: dict[str, Any] = result.get("targets") or {}
+    if not targets:
+        return result
+
+    def _size() -> int:
+        return len(json.dumps(result, separators=(",", ":"), default=str))
+
+    if _size() <= char_budget:
+        return result
+
+    # Stage 1: strip heavy optional doc fields across all targets.
+    for name, tgt in targets.items():
+        docs = tgt.get("docs") if isinstance(tgt, dict) else None
+        if not isinstance(docs, dict):
+            continue
+        for field in _HEAVY_DOC_FIELDS:
+            if field in docs:
+                docs.pop(field, None)
+                result["truncated"] = True
+        if _size() <= char_budget:
+            return result
+
+    # Stage 2: prioritise symbols within each target. We iterate from the
+    # largest target down so the biggest offenders shrink first.
+    def _target_cost(item: tuple[str, Any]) -> int:
+        return len(json.dumps(item[1], default=str))
+
+    for tgt_name, tgt in sorted(targets.items(), key=_target_cost, reverse=True):
+        docs = tgt.get("docs") if isinstance(tgt, dict) else None
+        if not isinstance(docs, dict):
+            continue
+        symbols = docs.get("symbols")
+        if not isinstance(symbols, list) or not symbols:
+            continue
+        query_terms = _query_terms_for(tgt_name)
+        ordered = sorted(symbols, key=lambda s: _symbol_priority(s, query_terms), reverse=True)
+        kept: list[dict[str, Any]] = []
+        dropped: list[str] = []
+        # Add symbols one at a time from highest priority until we hit the cap.
+        for sym in ordered:
+            docs["symbols"] = kept + [sym]
+            if _size() <= char_budget:
+                kept.append(sym)
+            else:
+                dropped.append(sym.get("name") or "<anonymous>")
+        if not kept and ordered:
+            # Edge case: a single symbol is larger than the budget. Keep one
+            # (truncating its docstring) rather than returning zero symbols —
+            # the caller at least learns the target resolved.
+            head = dict(ordered[0])
+            if isinstance(head.get("docstring"), str):
+                head["docstring"] = head["docstring"][:200]
+            kept = [head]
+            dropped = [s.get("name") or "<anonymous>" for s in ordered[1:]]
+        docs["symbols"] = kept
+        if dropped:
+            result["dropped_symbols"][tgt_name] = dropped
+            result["truncated"] = True
+        if _size() <= char_budget:
+            return result
+
+    # Stage 3: drop whole targets, largest first, until we fit. Prefer to keep
+    # error-only targets (they're tiny and signal "not found" to the caller).
+    def _evictable_order() -> list[str]:
+        items = list(targets.items())
+        items.sort(
+            key=lambda kv: (
+                0 if isinstance(kv[1], dict) and "error" in kv[1] else 1,
+                len(json.dumps(kv[1], default=str)),
+            ),
+            reverse=True,
+        )
+        return [k for k, _ in items]
+
+    for name in _evictable_order():
+        if len(targets) <= 1:
+            break
+        targets.pop(name, None)
+        result["dropped_targets"].append(name)
+        result["truncated"] = True
+        if _size() <= char_budget:
+            break
+
+    if result["truncated"]:
+        logger.info(
+            "get_context truncated to budget",
+            extra={
+                "char_budget": char_budget,
+                "token_budget": _TOKEN_BUDGET,
+                "final_chars": _size(),
+                "dropped_targets": result["dropped_targets"],
+                "dropped_symbol_counts": {
+                    k: len(v) for k, v in result["dropped_symbols"].items()
+                },
+            },
+        )
+    return result
+
+
 @mcp.tool()
 async def get_context(
     targets: list[str],
     include: list[str] | None = None,
+    compact: bool = True,
     repo: str | None = None,
 ) -> dict:
-    """Get complete context for one or more targets (files, modules, or symbols).
+    """Get a compact navigation index for files/modules/symbols. Batch targets.
 
-    Pass ALL relevant targets in a single call rather than calling this tool
-    multiple times. Each target is resolved automatically — pass file paths
-    like "src/auth/service.py", module paths like "src/auth", or symbol names
-    like "AuthService".
+    Default returns title + summary + symbol signatures (~3× smaller than
+    full mode). For full structure block + imported_by + docstrings pass
+    compact=False. For the full wiki content_md pass include=["docs","full_doc"].
 
-    Example: get_context(["src/auth/service.py", "src/auth/middleware.py", "AuthService"])
-
-    Optional `include` parameter filters response fields:
-    ["docs", "ownership", "last_change", "decisions", "freshness"]
-    Default: all fields returned.
+    Example: get_context(["src/auth/service.py", "src/auth/middleware.py"])
 
     Args:
-        targets: List of file paths, module paths, or symbol names to look up.
-        include: Optional list of fields to include. Default returns all.
-        repo: Repository path, name, or ID.
+        targets: file paths, module paths, or symbol names.
+        include: ["docs"] (default) | add "full_doc"/"ownership"/"last_change".
+        compact: default True (signatures only). False adds structure+imports+docstrings.
+        repo: usually omitted.
     """
-    include_set = set(include) if include else None
+    # Default to docs-only when include is omitted. The other blocks
+    # (ownership/last_change/decisions/freshness) are 200–500 bytes each and
+    # bloat every subsequent agent turn via cache replay. Callers that want
+    # them must pass include explicitly.
+    include_set = set(include) if include else {"docs"}
 
+    import time as _time
+    _t0 = _time.perf_counter()
     async with get_session(_state._session_factory) as session:
         repository = await _get_repo(session, repo)
 
         results = await asyncio.gather(
-            *[_resolve_one_target(session, repository, t, include_set) for t in targets]
+            *[
+                _resolve_one_target(session, repository, t, include_set, compact)
+                for t in targets
+            ]
         )
 
-    return {
+    response: dict[str, Any] = {
         "targets": {r["target"]: r for r in results},
+        "_meta": _build_meta(
+            timing_ms=(_time.perf_counter() - _t0) * 1000,
+            hint=_context_hint(targets, compact),
+        ),
     }
+    # Enforce the global token cap. See ``_truncate_to_budget`` for strategy.
+    return _truncate_to_budget(response)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview.py b/packages/server/src/repowise/server/mcp_server/tool_overview.py
index 56198d9..62a346e 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_overview.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_overview.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections import Counter
+from collections import Counter, defaultdict
 from typing import Any
 
 from sqlalchemy import select
@@ -119,16 +119,76 @@ async def get_overview(repo: str | None = None) -> dict:
             }
 
         # B. Knowledge map -------------------------------------------------------
-        knowledge_map = await compute_knowledge_map(session, repository.id)
-        # Flatten onboarding_targets to a list of paths (MCP tool backward compat)
-        if knowledge_map and "onboarding_targets" in knowledge_map:
-            knowledge_map = dict(knowledge_map)
-            knowledge_map["onboarding_targets"] = [
-                t["path"] for t in knowledge_map["onboarding_targets"]
+        knowledge_map: dict[str, Any] = {}
+        if all_git:
+            # top_owners: aggregate primary_owner_email across all files
+            owner_file_count: dict[str, int] = defaultdict(int)
+            owner_pct_sum: dict[str, float] = defaultdict(float)
+            for g in all_git:
+                email = g.primary_owner_email or ""
+                if email:
+                    owner_file_count[email] += 1
+                    owner_pct_sum[email] += float(g.primary_owner_commit_pct or 0.0)
+
+            total_files = len(all_git) or 1
+            top_owners = sorted(
+                [
+                    {
+                        "email": email,
+                        "files_owned": count,
+                        "percentage": round(count / total_files * 100.0, 1),
+                    }
+                    for email, count in owner_file_count.items()
+                ],
+                key=lambda x: -x["files_owned"],
+            )[:10]
+
+            # knowledge_silos: files where primary owner has > 80% ownership
+            knowledge_silos = [
+                g.file_path
+                for g in all_git
+                if (g.primary_owner_commit_pct or 0.0) > 0.8
             ]
-            knowledge_map["knowledge_silos"] = [
-                s["file_path"] for s in knowledge_map["knowledge_silos"]
+
+            # onboarding_targets: high-centrality files with least docs
+            # pagerank from graph_nodes; doc length from wiki_pages
+            node_result = await session.execute(
+                select(GraphNode).where(
+                    GraphNode.repository_id == repository.id,
+                    GraphNode.is_test == False,  # noqa: E712
+                )
+            )
+            all_nodes = node_result.scalars().all()
+
+            # Build word-count map from wiki_pages (file pages)
+            page_result = await session.execute(
+                select(Page).where(
+                    Page.repository_id == repository.id,
+                    Page.page_type == "file_page",
+                )
+            )
+            doc_words: dict[str, int] = {
+                p.target_path: len(p.content.split()) for p in page_result.scalars().all()
+            }
+
+            onboarding_candidates = [
+                {
+                    "path": n.node_id,
+                    "pagerank": n.pagerank,
+                    "doc_words": doc_words.get(n.node_id, 0),
+                }
+                for n in all_nodes
+                if n.pagerank > 0.0
             ]
+            # Sort by fewest doc words first (least documented), then by highest pagerank
+            onboarding_candidates.sort(key=lambda x: (x["doc_words"], -x["pagerank"]))
+            onboarding_targets = [c["path"] for c in onboarding_candidates[:5]]
+
+            knowledge_map = {
+                "top_owners": top_owners,
+                "knowledge_silos": knowledge_silos,
+                "onboarding_targets": onboarding_targets,
+            }
 
         return {
             "title": overview_page.title if overview_page else repository.name,
diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk.py b/packages/server/src/repowise/server/mcp_server/tool_risk.py
index 7cad1a7..fa48127 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_risk.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_risk.py
@@ -220,8 +220,15 @@ async def _assess_one_target(
 
     hotspot_score = meta.churn_percentile or 0.0
 
-    # Co-change partners
+    # Co-change partners — keep only the top-5 by frequency. Larger lists make
+    # MCP responses verbose without adding signal: top-5 captures the bulk of
+    # the temporal-coupling mass and keeps tool output tight for LLM agents.
     partners = json.loads(meta.co_change_partners_json)
+    partners_sorted = sorted(
+        partners,
+        key=lambda p: p.get("co_change_count", p.get("count", 0)) or 0,
+        reverse=True,
+    )[:5]
     import_related = import_links.get(target, set())
     co_changes = [
         {
@@ -230,7 +237,7 @@ async def _assess_one_target(
             "last_co_change": p.get("last_co_change"),
             "has_import_link": p.get("file_path", p.get("path", "")) in import_related,
         }
-        for p in partners
+        for p in partners_sorted
     ]
 
     owner = meta.primary_owner_name or "unknown"
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search.py b/packages/server/src/repowise/server/mcp_server/tool_search.py
index f5e3869..4c00878 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_search.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_search.py
@@ -24,13 +24,15 @@ async def search_codebase(
     page_type: str | None = None,
     repo: str | None = None,
 ) -> dict:
-    """Semantic search over the full wiki. Ask in natural language.
+    """Semantic search over the wiki. Use when ``get_answer`` did not return
+    a confident result and you need to discover candidate pages by topic.
 
     Args:
-        query: Natural language search query (e.g. "how does authentication work?").
-        limit: Maximum results to return (default 5).
-        page_type: Optional filter by page type (file_page, module_page, etc.).
-        repo: Repository path, name, or ID.
+        query: natural-language search query.
+        limit: maximum number of results to return (default 5).
+        page_type: optional filter on page kind (e.g. ``file_page``,
+            ``module_page``, ``symbol_spotlight``).
+        repo: repository identifier; usually omitted in single-repo deployments.
     """
     async with get_session(_state._session_factory) as session:
         # Ensure repo exists
diff --git a/packages/server/src/repowise/server/mcp_server/tool_symbol.py b/packages/server/src/repowise/server/mcp_server/tool_symbol.py
new file mode 100644
index 0000000..29cd03b
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/tool_symbol.py
@@ -0,0 +1,368 @@
+"""MCP Tool: get_symbol — byte-precise source retrieval for a single symbol.
+
+This is the structural counterpart to get_context. Where get_context returns
+file-level narrative (summary, symbol list, importers), get_symbol returns
+the actual source bytes of one named symbol — function body, class body, or
+method — by slicing the on-disk source file using the line range stored on
+the WikiSymbol row at index time.
+
+Why a separate tool instead of "include source" on get_context?
+  * Granularity: a single function is ~30 lines vs a 300-line file. Cuts the
+    cached prompt prefix by ~10× when the agent only needs one symbol.
+  * Predictability: response size is bounded by the symbol size, never the
+    file size — no surprise 50 KB payloads.
+  * No reparsing: the bytes come straight from disk via the persisted line
+    range. Tree-sitter never runs at retrieval time.
+
+The tool is intentionally additive — get_context remains the right call for
+"explain this file" or "what's the relationship between A and B" questions.
+get_symbol is for "show me the body of this function".
+
+Resolution strategy (in order):
+  1. Exact match on WikiSymbol.symbol_id (the canonical "{path}::{name}" key)
+  2. Exact match on (file_path, qualified_name) — supports class.method form
+  3. Exact match on (file_path, name) — supports unqualified names
+
+Returns a flat dict (not wrapped in `targets`) so the agent can pipe the
+`source` field straight to its scratch buffer.
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import select
+
+from repowise.core.persistence.database import get_session
+from repowise.core.persistence.models import WikiSymbol
+from repowise.server.mcp_server import _state
+from repowise.server.mcp_server._helpers import _get_repo
+from repowise.server.mcp_server._meta import build_meta as _build_meta
+from repowise.server.mcp_server._meta import symbol_hint as _symbol_hint
+from repowise.server.mcp_server._server import mcp
+
+_log = __import__("logging").getLogger("repowise.mcp.symbol")
+
+# Safety cap so a misconfigured WikiSymbol row pointing at a giant file
+# can never blow up the agent's context window. Tuned to ~12 KB of source.
+_MAX_SOURCE_LINES = 400
+
+
+def _parse_symbol_id(symbol_id: str) -> tuple[str | None, str | None]:
+    """Split a "{path}::{name}" id. Either side may be None if missing.
+
+    Tolerant of double-colons in qualified names like "Foo::Bar::baz" by
+    splitting on the FIRST "::" only — the first segment is always the file
+    path. Returns (file_path, name) where name may itself contain "::" for
+    nested qualified forms ("Class::method").
+    """
+    if not symbol_id or "::" not in symbol_id:
+        return symbol_id or None, None
+    file_part, _, name_part = symbol_id.partition("::")
+    return (file_part or None, name_part or None)
+
+
+# Separators used between name segments AFTER the file path. Different
+# languages use different conventions: Python/TS/Go use ".", C++/Rust use
+# "::", and some tools emit "/". The lookup must be uniform across all of
+# them — we never encode a single language's rule.
+_NAME_SEPARATORS = (".", "::", "/")
+
+
+def _name_variants(name: str) -> list[str]:
+    """Generate all separator variants of a qualified name segment.
+
+    Given "App.update_template_context" we yield the same name with every
+    supported separator between segments, so a DB storing "App::method"
+    still resolves when the agent passed dot-form (or vice versa).
+
+    Operates only on the *name* (post file-path), never on the path itself.
+    """
+    if not name:
+        return []
+    # Split on any of the known separators to get atomic segments.
+    segments = [name]
+    for sep in _NAME_SEPARATORS:
+        next_segments: list[str] = []
+        for seg in segments:
+            next_segments.extend(seg.split(sep))
+        segments = next_segments
+    segments = [s for s in segments if s]
+    if not segments:
+        return [name]
+    variants: list[str] = []
+    seen: set[str] = set()
+    for sep in _NAME_SEPARATORS:
+        v = sep.join(segments)
+        if v not in seen:
+            seen.add(v)
+            variants.append(v)
+    # Also include the original as-is in case it used a mixed separator.
+    if name not in seen:
+        variants.append(name)
+    return variants
+
+
+def _symbol_id_variants(symbol_id: str) -> list[str]:
+    """Generate {file_path}::{name_variant} for every name separator form."""
+    file_path, name = _parse_symbol_id(symbol_id)
+    if not file_path or not name:
+        return [symbol_id]
+    out: list[str] = []
+    seen: set[str] = set()
+    for nv in _name_variants(name):
+        sid = f"{file_path}::{nv}"
+        if sid not in seen:
+            seen.add(sid)
+            out.append(sid)
+    if symbol_id not in seen:
+        out.append(symbol_id)
+    return out
+
+
+def _bare_name(name: str) -> str:
+    """Return the last name segment regardless of separator style."""
+    tail = name
+    for sep in _NAME_SEPARATORS:
+        tail = tail.rsplit(sep, 1)[-1]
+    return tail
+
+
+def _pick_canonical(
+    rows: list[WikiSymbol], queried_file_path: str | None
+) -> WikiSymbol | None:
+    """Deterministically select one row from a candidate list.
+
+    Priority:
+      1. file_path matches the file_path embedded in the queried symbol_id
+      2. deterministic tiebreak on the (id) primary key (ascending)
+    """
+    if not rows:
+        return None
+    if len(rows) == 1:
+        return rows[0]
+    if queried_file_path:
+        matching = [r for r in rows if r.file_path == queried_file_path]
+        if matching:
+            rows = matching
+    # Deterministic: lowest id wins. (No confidence column today; leaving
+    # room to add one without changing the fallback.)
+    rows_sorted = sorted(rows, key=lambda r: (r.id or ""))
+    if len(rows) > 1:
+        _log.warning(
+            "get_symbol: %d duplicate rows for lookup (file=%s); picked id=%s",
+            len(rows),
+            queried_file_path,
+            rows_sorted[0].id,
+        )
+    return rows_sorted[0]
+
+
+async def _resolve_symbol(
+    session, repo_id: str, symbol_id: str
+) -> WikiSymbol | None:
+    """Look up a symbol by id, qualified_name, or bare name. None if absent.
+
+    Language-agnostic: the qualified-name portion of the symbol_id is
+    normalized across ``.``, ``::`` and ``/`` separators before matching,
+    so callers can pass any of ``Class.method``, ``Class::method``, or
+    ``Class/method`` and still resolve. Only the name part is normalized —
+    file paths are never rewritten.
+
+    Duplicate-safe: every query uses ``.all()`` + :func:`_pick_canonical`
+    instead of ``.scalar_one_or_none()``. The canonical constraint
+    ``uq_wiki_symbol`` on ``(repository_id, symbol_id)`` already prevents
+    duplicates on the primary key, but the fallback lookups on
+    ``(file_path, qualified_name)`` and ``(file_path, name)`` can legitimately
+    return several rows (e.g. overloads, re-exports, conditional defs).
+    """
+    file_path, _name = _parse_symbol_id(symbol_id)
+    variants = _symbol_id_variants(symbol_id)
+
+    # 1. Exact symbol_id — try every separator variant.
+    res = await session.execute(
+        select(WikiSymbol).where(
+            WikiSymbol.repository_id == repo_id,
+            WikiSymbol.symbol_id.in_(variants),
+        )
+    )
+    rows = list(res.scalars().all())
+    picked = _pick_canonical(rows, file_path)
+    if picked is not None:
+        return picked
+
+    _, name = _parse_symbol_id(symbol_id)
+    if not name:
+        return None
+
+    name_variants = _name_variants(name)
+
+    # 2. Match on (file_path, qualified_name) across name variants.
+    if file_path:
+        res = await session.execute(
+            select(WikiSymbol).where(
+                WikiSymbol.repository_id == repo_id,
+                WikiSymbol.file_path == file_path,
+                WikiSymbol.qualified_name.in_(name_variants),
+            )
+        )
+        rows = list(res.scalars().all())
+        picked = _pick_canonical(rows, file_path)
+        if picked is not None:
+            return picked
+
+        # 3. Match on (file_path, name) — last segment of qualified name.
+        bare = _bare_name(name)
+        res = await session.execute(
+            select(WikiSymbol).where(
+                WikiSymbol.repository_id == repo_id,
+                WikiSymbol.file_path == file_path,
+                WikiSymbol.name == bare,
+            )
+        )
+        rows = list(res.scalars().all())
+        picked = _pick_canonical(rows, file_path)
+        if picked is not None:
+            return picked
+
+    return None
+
+
+def _slice_source(
+    repo_path: Path, file_path: str, start_line: int, end_line: int, context_lines: int
+) -> tuple[str, int, int, int | None]:
+    """Read the file and return (source, actual_start, actual_end, total_lines).
+
+    Returns ("", start, end, None) on read failure. Lines are 1-indexed in the
+    inputs and outputs to match WikiSymbol storage. Honors _MAX_SOURCE_LINES.
+    """
+    abs_path = (repo_path / file_path).resolve()
+    # Defense in depth: never read outside the repo root, even if the
+    # WikiSymbol.file_path was somehow tampered with.
+    try:
+        abs_path.relative_to(repo_path.resolve())
+    except ValueError:
+        _log.warning("get_symbol path escape attempt: %s", file_path)
+        return "", start_line, end_line, None
+    try:
+        text = abs_path.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        _log.warning("get_symbol read failed for %s: %s", abs_path, exc)
+        return "", start_line, end_line, None
+
+    lines = text.splitlines()
+    total = len(lines)
+
+    # 1-indexed inclusive range, then expand by context_lines on both sides.
+    s = max(1, min(start_line, total))
+    e = max(s, min(end_line, total))
+    if context_lines > 0:
+        s = max(1, s - context_lines)
+        e = min(total, e + context_lines)
+
+    span = e - s + 1
+    if span > _MAX_SOURCE_LINES:
+        # Truncate from the tail; the head usually has the signature
+        # which is what the agent needs to ground itself.
+        e = s + _MAX_SOURCE_LINES - 1
+        span = _MAX_SOURCE_LINES
+
+    sliced = "\n".join(lines[s - 1 : e])
+    return sliced, s, e, total
+
+
+@mcp.tool()
+async def get_symbol(
+    symbol_id: str,
+    context_lines: int = 0,
+    repo: str | None = None,
+) -> dict:
+    """Return the exact source body of one symbol by ID. Trust the result.
+
+    Cheaper than Read for "show me X" / "what does Y do" questions.
+    Returns {file, name, kind, signature, start_line, end_line, source}.
+    On miss returns {error: "Symbol not found"}.
+
+    Args:
+        symbol_id: "path/to/file.py::SymbolName" (canonical id from get_context).
+        context_lines: extra source lines before/after (0–50, default 0).
+        repo: usually omitted.
+    """
+    t0 = time.perf_counter()
+    if not symbol_id or not symbol_id.strip():
+        return {
+            "symbol_id": symbol_id,
+            "error": "symbol_id is required",
+            "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000),
+        }
+    if context_lines < 0 or context_lines > 50:
+        # Bound context_lines to a sane range — runaway values would
+        # defeat the whole point of symbol-level retrieval.
+        context_lines = max(0, min(50, context_lines))
+
+    async with get_session(_state._session_factory) as session:
+        repository = await _get_repo(session, repo)
+        row = await _resolve_symbol(session, repository.id, symbol_id)
+
+    if row is None:
+        return {
+            "symbol_id": symbol_id,
+            "error": (
+                f"Symbol not found: {symbol_id!r}. Use get_context to list "
+                "available symbols in the file, then try again with the "
+                "exact symbol_id from that response."
+            ),
+            "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000),
+        }
+
+    if not _state._repo_path:
+        return {
+            "symbol_id": symbol_id,
+            "error": "MCP server has no repo path configured",
+            "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000),
+        }
+
+    repo_root = Path(_state._repo_path)
+    source, start, end, total = _slice_source(
+        repo_root, row.file_path, row.start_line, row.end_line, context_lines
+    )
+
+    if not source:
+        return {
+            "symbol_id": symbol_id,
+            "file": row.file_path,
+            "name": row.name,
+            "kind": row.kind,
+            "signature": row.signature,
+            "error": (
+                "Symbol metadata exists but source file could not be read. "
+                "The file may have been moved or deleted since indexing."
+            ),
+            "_meta": _build_meta(timing_ms=(time.perf_counter() - t0) * 1000),
+        }
+
+    truncated = (end - start + 1) >= _MAX_SOURCE_LINES and (
+        row.end_line - row.start_line + 1 + 2 * context_lines
+    ) > _MAX_SOURCE_LINES
+
+    return {
+        "symbol_id": row.symbol_id,
+        "file": row.file_path,
+        "name": row.name,
+        "kind": row.kind,
+        "qualified_name": row.qualified_name,
+        "signature": row.signature,
+        "language": row.language,
+        "start_line": start,
+        "end_line": end,
+        "symbol_start_line": row.start_line,
+        "symbol_end_line": row.end_line,
+        "source": source,
+        "truncated": truncated,
+        "_meta": _build_meta(
+            timing_ms=(time.perf_counter() - t0) * 1000,
+            hint=_symbol_hint(row.symbol_id, row.end_line, row.start_line),
+        ),
+    }
diff --git a/plugins/claude-code/DEVELOPER.md b/plugins/claude-code/DEVELOPER.md
index d9edaf5..e2cd66e 100644
--- a/plugins/claude-code/DEVELOPER.md
+++ b/plugins/claude-code/DEVELOPER.md
@@ -46,7 +46,7 @@ repowise-plugin/                    # Standalone repo root
 
 **`.claude-plugin/marketplace.json`** — Makes the repo a self-hosted marketplace. The `plugins[].source: "."` tells Claude Code the plugin root is the repo root itself. Without this file, users can't `/plugin install` from this repo.
 
-**`.mcp.json`** — When the plugin is enabled, Claude Code auto-starts `repowise mcp` as an MCP server. This is what gives Claude access to the 8 tools. Uses `mcpServers` wrapper key. The `repowise` binary must be on PATH (the init command handles installation).
+**`.mcp.json`** — When the plugin is enabled, Claude Code auto-starts `repowise mcp` as an MCP server. This is what gives Claude access to the 10 tools. Uses `mcpServers` wrapper key. The `repowise` binary must be on PATH (the init command handles installation).
 
 **`commands/*.md`** — Markdown files that become `/repowise:<filename>` slash commands. Frontmatter defines `description`, `allowed-tools`, etc. The `$ARGUMENTS` placeholder captures user input after the command name.
 
diff --git a/tests/unit/ingestion/test_graph.py b/tests/unit/ingestion/test_graph.py
index f9069a1..702f627 100644
--- a/tests/unit/ingestion/test_graph.py
+++ b/tests/unit/ingestion/test_graph.py
@@ -185,6 +185,114 @@ def test_parallel_imports_merged(self) -> None:
         assert "bar" in names
 
 
+# ---------------------------------------------------------------------------
+# Stem disambiguation — protects against the historical PageRank inflation
+# bug where a test fixture named like the package (e.g. tests/.../flask.py)
+# was the only file with stem "flask" in the stem map (because the real
+# src/flask/__init__.py registered under stem "__init__"), so every internal
+# `from flask import X` resolved to the test fixture, giving it massive
+# in-degree and dominating PageRank.
+# ---------------------------------------------------------------------------
+
+
+class TestStemDisambiguation:
+    def test_init_py_registers_under_parent_dir(self) -> None:
+        """`from flask import X` resolves to src/flask/__init__.py, not a
+        test fixture named flask.py."""
+        b = GraphBuilder()
+        b.add_file(_parsed("src/flask/__init__.py"))
+        b.add_file(_parsed("tests/test_apps/cliapp/inner1/inner2/flask.py"))
+        b.add_file(_parsed("src/flask/app.py", imports=[_imp("flask")]))
+        b.build()
+        g = b.graph()
+        assert g.has_edge("src/flask/app.py", "src/flask/__init__.py")
+        assert not g.has_edge(
+            "src/flask/app.py", "tests/test_apps/cliapp/inner1/inner2/flask.py"
+        )
+
+    def test_test_fixture_loses_to_source_file(self) -> None:
+        """When two files share a stem and one is under tests/, the
+        non-test file wins regardless of insertion order."""
+        # Insert test file FIRST so dict iteration would have favored it
+        # under the old last-write-wins logic.
+        b = GraphBuilder()
+        b.add_file(_parsed("tests/fixtures/widget.py"))
+        b.add_file(_parsed("src/widget.py"))
+        b.add_file(_parsed("main.py", imports=[_imp("widget")]))
+        b.build()
+        g = b.graph()
+        assert g.has_edge("main.py", "src/widget.py")
+        assert not g.has_edge("main.py", "tests/fixtures/widget.py")
+
+    def test_resolution_is_deterministic_across_orderings(self) -> None:
+        """Two builders with files added in opposite orders must produce
+        the same edge — resolution cannot depend on dict iteration."""
+        files = ["src/widget.py", "tests/fixtures/widget.py", "examples/widget.py"]
+
+        def build_with_order(order: list[str]) -> str | None:
+            b = GraphBuilder()
+            for f in order:
+                b.add_file(_parsed(f))
+            b.add_file(_parsed("main.py", imports=[_imp("widget")]))
+            b.build()
+            edges = list(b.graph().out_edges("main.py"))
+            return edges[0][1] if edges else None
+
+        target_a = build_with_order(files)
+        target_b = build_with_order(list(reversed(files)))
+        assert target_a == target_b == "src/widget.py"
+
+    def test_parent_dir_match_beats_shorter_path(self) -> None:
+        """A nested file whose parent directory matches the stem beats a
+        shallower file whose parent doesn't — canonical package layout
+        is the strongest signal."""
+        b = GraphBuilder()
+        # Shallower path, parent dir doesn't match stem
+        b.add_file(_parsed("vendor/util.py"))
+        # Deeper path, but parent dir == stem (canonical layout)
+        b.add_file(_parsed("src/util/util.py"))
+        b.add_file(_parsed("main.py", imports=[_imp("util")]))
+        b.build()
+        assert b.graph().has_edge("main.py", "src/util/util.py")
+
+    def test_src_layout_direct_match(self) -> None:
+        """`from flask.app import X` finds src/flask/app.py via the new
+        src/ candidate, not via stem fallback."""
+        b = GraphBuilder()
+        b.add_file(_parsed("src/flask/app.py"))
+        # Decoy: another app.py with the same stem in a deep test tree.
+        b.add_file(_parsed("tests/test_apps/cliapp/app.py"))
+        b.add_file(_parsed("main.py", imports=[_imp("flask.app")]))
+        b.build()
+        assert b.graph().has_edge("main.py", "src/flask/app.py")
+
+    def test_repo_root_init_does_not_crash(self) -> None:
+        """A repo-root __init__.py has no parent directory name; it must
+        be skipped from the stem map without crashing the build."""
+        b = GraphBuilder()
+        b.add_file(_parsed("__init__.py"))
+        b.add_file(_parsed("main.py", imports=[_imp("anything")]))
+        b.build()  # must not raise
+        # No edge expected — stem "anything" is unresolvable
+        assert b.graph().number_of_edges() == 0
+
+    def test_go_stem_collision_prefers_parent_match(self) -> None:
+        """Go: `import .../calculator` prefers calculator/calculator.go
+        over a test fixture with the same filename."""
+        b = GraphBuilder()
+        b.add_file(_parsed("internal/testdata/calculator.go", language="go"))
+        b.add_file(_parsed("calculator/calculator.go", language="go"))
+        b.add_file(
+            _parsed(
+                "main.go",
+                language="go",
+                imports=[_imp("github.com/example/app/calculator")],
+            )
+        )
+        b.build()
+        assert b.graph().has_edge("main.go", "calculator/calculator.go")
+
+
 # ---------------------------------------------------------------------------
 # TypeScript import resolution
 # ---------------------------------------------------------------------------
diff --git a/tests/unit/persistence/test_models.py b/tests/unit/persistence/test_models.py
index d4f9f81..5855be4 100644
--- a/tests/unit/persistence/test_models.py
+++ b/tests/unit/persistence/test_models.py
@@ -306,5 +306,6 @@ def test_base_includes_all_models():
         "chat_messages",
         "llm_costs",
         "security_findings",
+        "answer_cache",
     }
     assert expected == table_names
diff --git a/tests/unit/server/test_mcp.py b/tests/unit/server/test_mcp.py
index 4b751f2..bd0cb75 100644
--- a/tests/unit/server/test_mcp.py
+++ b/tests/unit/server/test_mcp.py
@@ -611,7 +611,11 @@ async def test_get_overview_repo_not_found(setup_mcp):
 async def test_get_context_single_file(setup_mcp):
     from repowise.server.mcp_server import get_context
 
-    result = await get_context(["src/auth/service.py"])
+    result = await get_context(
+        ["src/auth/service.py"],
+        include=["docs", "full_doc", "ownership", "last_change", "decisions", "freshness"],
+        compact=False,
+    )
     targets = result["targets"]
     assert "src/auth/service.py" in targets
     t = targets["src/auth/service.py"]
@@ -642,7 +646,11 @@ async def test_get_context_single_file(setup_mcp):
 async def test_get_context_single_module(setup_mcp):
     from repowise.server.mcp_server import get_context
 
-    result = await get_context(["src/auth"])
+    result = await get_context(
+        ["src/auth"],
+        include=["docs", "full_doc", "ownership", "last_change", "decisions", "freshness"],
+        compact=False,
+    )
     targets = result["targets"]
     assert "src/auth" in targets
     t = targets["src/auth"]
@@ -658,7 +666,11 @@ async def test_get_context_single_module(setup_mcp):
 async def test_get_context_single_symbol(setup_mcp):
     from repowise.server.mcp_server import get_context
 
-    result = await get_context(["AuthService"])
+    result = await get_context(
+        ["AuthService"],
+        include=["docs", "full_doc"],
+        compact=False,
+    )
     targets = result["targets"]
     assert "AuthService" in targets
     t = targets["AuthService"]
@@ -704,6 +716,95 @@ async def test_get_context_not_found(setup_mcp):
     assert "error" in t
 
 
+# ---- get_context: truncation ----
+
+
+def _make_big_response(n_targets: int = 5, n_symbols: int = 80, body_chars: int = 4000) -> dict:
+    """Build a synthetic get_context response well over the 32 KB budget."""
+    targets = {}
+    for i in range(n_targets):
+        name = f"pkg/mod_{i}/file_{i}.ext"
+        targets[name] = {
+            "target": name,
+            "type": "file",
+            "docs": {
+                "title": f"File {i}",
+                "summary": "s" * 200,
+                "content_md": "x" * body_chars,
+                "symbols": [
+                    {
+                        "name": f"Sym{i}_{j}",
+                        "kind": "class" if j % 5 == 0 else "function",
+                        "signature": f"sig_{j}(...)",
+                        "start_line": j * 10,
+                        "end_line": j * 10 + 8,
+                        "docstring": "d" * 300,
+                    }
+                    for j in range(n_symbols)
+                ],
+            },
+        }
+    return {"targets": targets, "_meta": {"timing_ms": 1.0}}
+
+
+def test_truncate_to_budget_enforces_cap():
+    from repowise.server.mcp_server.tool_context import (
+        _CHAR_BUDGET,
+        _truncate_to_budget,
+    )
+
+    big = _make_big_response()
+    raw_size = len(json.dumps(big, separators=(",", ":"), default=str))
+    assert raw_size > _CHAR_BUDGET, "fixture must exceed budget to be meaningful"
+
+    out = _truncate_to_budget(big)
+    final_size = len(json.dumps(out, separators=(",", ":"), default=str))
+    assert final_size <= _CHAR_BUDGET
+    assert out["truncated"] is True
+    # At least one target must survive.
+    assert len(out["targets"]) >= 1
+
+
+def test_truncate_flags_and_dropped_fields_populate():
+    from repowise.server.mcp_server.tool_context import _truncate_to_budget
+
+    big = _make_big_response(n_targets=6, n_symbols=60, body_chars=5000)
+    out = _truncate_to_budget(big)
+
+    assert out["truncated"] is True
+    # Either whole targets were dropped, or individual symbols were dropped —
+    # both are acceptable outcomes; at least one must be populated.
+    dropped_any = bool(out["dropped_targets"]) or bool(out["dropped_symbols"])
+    assert dropped_any
+    # Heavy optional fields should have been stripped from surviving targets.
+    for tgt in out["targets"].values():
+        assert "content_md" not in tgt.get("docs", {})
+    # Dropped symbol lists (if any) must reference actual symbol names.
+    for tgt_name, names in out["dropped_symbols"].items():
+        assert tgt_name in big["targets"] or tgt_name not in out["targets"]
+        assert all(isinstance(n, str) for n in names)
+
+
+def test_truncate_noop_when_under_budget():
+    from repowise.server.mcp_server.tool_context import _truncate_to_budget
+
+    small = {
+        "targets": {
+            "a.py": {
+                "target": "a.py",
+                "type": "file",
+                "docs": {"title": "A", "symbols": [{"name": "f", "kind": "function"}]},
+            }
+        },
+        "_meta": {},
+    }
+    out = _truncate_to_budget(small)
+    assert out["truncated"] is False
+    assert out["dropped_targets"] == []
+    assert out["dropped_symbols"] == {}
+    assert "content_md" not in out["targets"]["a.py"]["docs"]  # wasn't there anyway
+
+
 # ---- Tool 3: get_risk ----
 
 
diff --git a/tests/unit/server/test_tool_symbol.py b/tests/unit/server/test_tool_symbol.py
new file mode 100644
index 0000000..6a9c1cb
--- /dev/null
+++ b/tests/unit/server/test_tool_symbol.py
@@ -0,0 +1,168 @@
+"""Tests for the get_symbol MCP tool resolution logic.
+
+These exercise :func:`_resolve_symbol` directly against a test DB session
+so we don't need to spin up the full MCP server. They cover two
+reliability bugs that previously caused unnecessary agent retries:
+
+  * Separator-style mismatch between ``Class.method`` and ``Class::method``
+  * ``MultipleResultsFound`` when duplicate rows share a lookup key
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.persistence.database import get_session
+from repowise.core.persistence.models import WikiSymbol, _new_uuid
+from repowise.server.mcp_server.tool_symbol import (
+    _name_variants,
+    _pick_canonical,
+    _resolve_symbol,
+    _symbol_id_variants,
+)
+from tests.unit.server.conftest import create_test_repo
+
+
+async def _add(session_factory, repo_id: str, **overrides):
+    defaults = dict(
+        id=_new_uuid(),
+        repository_id=repo_id,
+        file_path="src/flask/sansio/app.py",
+        symbol_id="src/flask/sansio/app.py::App::update_template_context",
+        name="update_template_context",
+        qualified_name="App::update_template_context",
+        kind="method",
+        signature="def update_template_context(self, context)",
+        start_line=1,
+        end_line=5,
+        visibility="public",
+        language="python",
+    )
+    defaults.update(overrides)
+    async with get_session(session_factory) as session:
+        session.add(WikiSymbol(**defaults))
+    return defaults["id"]
+
+
+def test_name_variants_language_agnostic() -> None:
+    # Dot form and double-colon form should yield the same set of variants.
+    dot = set(_name_variants("App.update_template_context"))
+    colon = set(_name_variants("App::update_template_context"))
+    assert dot == colon
+    assert "App.update_template_context" in dot
+    assert "App::update_template_context" in dot
+    assert "App/update_template_context" in dot
+
+    # Nested qualifiers (C++/Rust style) normalize too.
+    variants = set(_name_variants("ns::Outer::Inner::fn"))
+    assert "ns.Outer.Inner.fn" in variants
+    assert "ns::Outer::Inner::fn" in variants
+
+
+def test_symbol_id_variants_preserves_file_path() -> None:
+    # Path segments must NEVER be rewritten — only the name after "::".
+    sids = _symbol_id_variants("src/flask/sansio/app.py::App.method")
+    assert "src/flask/sansio/app.py::App.method" in sids
+    assert "src/flask/sansio/app.py::App::method" in sids
+    # The file path slashes should remain untouched.
+    for sid in sids:
+        assert sid.startswith("src/flask/sansio/app.py::")
+
+
+@pytest.mark.asyncio
+async def test_resolve_symbol_dot_and_colon_forms_equivalent(
+    client, app, session_factory
+) -> None:
+    repo = await create_test_repo(client)
+    await _add(session_factory, repo["id"])  # stored with "::" form
+
+    async with get_session(session_factory) as session:
+        row_colon = await _resolve_symbol(
+            session,
+            repo["id"],
+            "src/flask/sansio/app.py::App::update_template_context",
+        )
+        row_dot = await _resolve_symbol(
+            session,
+            repo["id"],
+            "src/flask/sansio/app.py::App.update_template_context",
+        )
+
+    assert row_colon is not None
+    assert row_dot is not None
+    assert row_colon.id == row_dot.id
+    assert row_dot.name == "update_template_context"
+
+
+@pytest.mark.asyncio
+async def test_resolve_symbol_duplicate_rows_picks_canonical(
+    client, app, session_factory
+) -> None:
+    """When the (file_path, qualified_name) lookup returns several rows,
+    we must return one canonical row instead of raising MultipleResultsFound.
+    """
+    repo = await create_test_repo(client)
+    # Two rows share the same (file_path, qualified_name, name) — simulates
+    # the 'from .x import y' re-export case.
+    await _add(
+        session_factory,
+        repo["id"],
+        id="aaaa" + "0" * 28,
+        symbol_id="src/flask/sansio/blueprints.py::BlueprintSetupState::add_url_rule#1",
+        file_path="src/flask/sansio/blueprints.py",
+        qualified_name="BlueprintSetupState::add_url_rule",
+        name="add_url_rule",
+    )
+    await _add(
+        session_factory,
+        repo["id"],
+        id="bbbb" + "0" * 28,
+        symbol_id="src/flask/sansio/blueprints.py::BlueprintSetupState::add_url_rule#2",
+        file_path="src/flask/sansio/blueprints.py",
+        qualified_name="BlueprintSetupState::add_url_rule",
+        name="add_url_rule",
+    )
+
+    async with get_session(session_factory) as session:
+        row = await _resolve_symbol(
+            session,
+            repo["id"],
+            "src/flask/sansio/blueprints.py::BlueprintSetupState.add_url_rule",
+        )
+
+    assert row is not None
+    # Deterministic tiebreak: lowest id wins.
+    assert row.id.startswith("aaaa")
+    assert row.file_path == "src/flask/sansio/blueprints.py"
+
+
+@pytest.mark.asyncio
+async def test_resolve_symbol_nonexistent_returns_none(
+    client, app, session_factory
+) -> None:
+    repo = await create_test_repo(client)
+    await _add(session_factory, repo["id"])
+
+    async with get_session(session_factory) as session:
+        row = await _resolve_symbol(
+            session,
+            repo["id"],
+            "src/flask/sansio/app.py::App.this_method_does_not_exist",
+        )
+
+    assert row is None
+
+
+def test_pick_canonical_prefers_matching_file_path() -> None:
+    class Fake:
+        def __init__(self, id_: str, path: str) -> None:
+            self.id = id_
+            self.file_path = path
+
+    rows = [Fake("zzzz", "other/path.py"), Fake("aaaa", "src/target.py")]
+    picked = _pick_canonical(rows, "src/target.py")  # type: ignore[arg-type]
+    assert picked.id == "aaaa"  # type: ignore[union-attr]
+
+    # No file_path hint: fall back to lowest id.
+    picked = _pick_canonical(rows, None)  # type: ignore[arg-type]
+    assert picked.id == "aaaa"  # type: ignore[union-attr]
diff --git a/website/claude-md-generator.md b/website/claude-md-generator.md
index 67059ff..760f0ab 100644
--- a/website/claude-md-generator.md
+++ b/website/claude-md-generator.md
@@ -47,7 +47,7 @@ What goes into the generated content:
 | Entry points | Detected `main.py`, `__main__`, CLI entry files |
 | Tech stack | Languages, frameworks, databases, infra |
 | Hotspots | Top 5 high-churn files with percentile rank |
-| MCP tool instructions | Mandatory usage table for all 8 tools |
+| MCP tool instructions | Mandatory usage table for all 10 tools |
 | Codebase conventions | Active architectural decisions + build commands |
 
 ---
diff --git a/website/concepts.md b/website/concepts.md
index 9305d09..36a4537 100644
--- a/website/concepts.md
+++ b/website/concepts.md
@@ -161,7 +161,7 @@ The dependency graph is loaded into memory at server startup for fast traversal.
 
 ## The MCP server
 
-The MCP server sits on top of the persistence layer and exposes everything to AI coding assistants via 8 tools. It's the primary interface between repowise and Claude Code, Cursor, Cline, or any other MCP-compatible editor.
+The MCP server sits on top of the persistence layer and exposes everything to AI coding assistants via 10 tools. It's the primary interface between repowise and Claude Code, Cursor, Cline, or any other MCP-compatible editor.
 
 When you run `repowise mcp`, the server starts in stdio mode and your editor can begin calling tools. The tools are designed to answer the questions an AI needs to make good decisions about your code — not just "what is this file" but "should I edit it", "why is it structured this way", and "what will break if I change it".
 
diff --git a/website/index.md b/website/index.md
index 9df1bb8..5cc2f78 100644
--- a/website/index.md
+++ b/website/index.md
@@ -24,7 +24,7 @@ repowise generates and maintains a structured wiki for any codebase. It tracks c
 | **Git intelligence** | Churn hotspots, ownership, bus factor, change patterns |
 | **Dead code detection** | Finds confirmed unused exports, functions, and types |
 | **Decision intelligence** | Captures *why* code is structured the way it is |
-| **MCP server** | 8 tools for AI assistants (Claude Code, Cursor, Windsurf, Cline) |
+| **MCP server** | 10 tools for AI assistants (Claude Code, Cursor, Windsurf, Cline) |
 | **Web dashboard** | Browse wiki, search, and explore architecture diagrams |
 | **Multi-language** | Python, TypeScript, JavaScript, Go, Rust, Java, C/C++, Kotlin, Ruby |
 
diff --git a/website/mcp-server.md b/website/mcp-server.md
index 41abdca..e1d421e 100644
--- a/website/mcp-server.md
+++ b/website/mcp-server.md
@@ -22,7 +22,7 @@ Connect repowise to Claude Code, Cursor, Cline, or any MCP-compatible editor.
 
 ## Overview
 
-The MCP (Model Context Protocol) server is how repowise talks to AI coding assistants. Once connected, your editor's AI can call 8 tools to query your codebase wiki — getting docs, ownership, risk signals, dependency paths, and architectural decisions in a single call.
+The MCP (Model Context Protocol) server is how repowise talks to AI coding assistants. Once connected, your editor's AI can call 10 tools to query your codebase wiki — synthesizing answers, looking up symbols, fetching docs, ownership, risk signals, dependency paths, and architectural decisions.
 
 Start the server with:
 
@@ -139,7 +139,55 @@ Clients connect to `http://localhost:7338/sse` and receive server-sent events. C
 
 ---
 
-## The 8 tools
+## The 10 tools
+
+### `get_answer(question, scope?)`
+
+One-call RAG over the wiki layer. Runs retrieval, gates on confidence, and synthesizes a 2–5 sentence answer with concrete file/symbol citations. Responses are cached per repository by question hash, so repeated questions cost nothing on the second call.
+
+**Parameters:**
+- `question` (string) — natural-language developer question
+- `scope` (optional, string) — path prefix to restrict retrieval (e.g. `"src/auth/"`)
+
+**Returns:**
+- `answer` (string) — synthesized 2–5 sentence answer
+- `citations` (list of strings) — file paths backing the answer
+- `confidence` (string) — `"high"`, `"medium"`, or `"low"`. High-confidence answers can be cited directly without verification reads; lower confidence indicates the agent should fall back to `search_codebase` or `Read`.
+- `fallback_targets` (list of strings) — top retrieval hits the agent should `Read` if it does not trust the synthesized answer
+- `retrieval` (list) — raw top-N hits with snippets
+
+**When to use:** First call on any code question. Collapses the typical "search → read → reason" loop into a single round-trip.
+
+**Example:**
+```
+get_answer(question="how does the request context get pushed and popped per request")
+
+→ answer: "Flask pushes a RequestContext onto _request_ctx_stack at the start
+  of every request via Flask.wsgi_app, and pops it in the corresponding
+  finally clause. The push happens in src/flask/app.py::Flask.wsgi_app."
+  citations: ["src/flask/app.py", "src/flask/ctx.py"]
+  confidence: "high"
+```
+
+---
+
+### `get_symbol(symbol_id)`
+
+Resolves a fully-qualified symbol identifier to its definition. Returns the source body, signature, file location, line range, and any associated docstring without the agent having to grep then read.
+
+**Parameters:**
+- `symbol_id` (string) — qualified id of the form `path/to/file.py::ClassName::method_name`. Both `::` and `.` are accepted as the symbol separator (`Class::method` and `Class.method` resolve identically).
+
+**Returns:**
+- `symbol_id`, `name`, `kind` (`class`, `function`, `method`, …)
+- `file_path`, `start_line`, `end_line`
+- `signature` (recovered from source so base classes, decorators, and full type annotations are preserved)
+- `body` (the symbol's source code)
+- `docstring`
+
+**When to use:** When the question names a specific class, function, or method and you want its source without a separate `Read` call.
+
+---
 
 ### `get_overview()`
 
@@ -159,13 +207,14 @@ Bus factor risk: git_indexer.py (1 author)
 
 ---
 
-### `get_context(targets, include?)`
+### `get_context(targets, include?, compact?)`
 
 Returns rich context for one or more files, modules, or symbols: documentation, ownership, last change, governing decisions, and freshness status.
 
 **Parameters:**
 - `targets` (list of strings) — file paths, module names, or symbol names
 - `include` (optional) — subset of `["docs", "ownership", "last_change", "decisions", "freshness"]`
+- `compact` (optional, default `True`) — when `True`, drops the `structure` block, the `imported_by` list, and per-symbol docstrings/end-line fields to keep the response under ~10K characters. Pass `compact=False` to receive the full payload, e.g. when you specifically need the import-graph dependents or every symbol docstring on a dense file.
 
 **When to use:** Before reading or editing any file. Faster and richer than reading the raw source.