purecontext-mcp 1.1.0 → 1.1.2

package/guide/navigating-new-code.md

@@ -0,0 +1,121 @@
+# Navigating a New Codebase
+
+Whether you've just joined a team or picked up a project you haven't touched in six months, the first challenge is the same: you don't know where anything is. PureContext gives you a structured way to orient yourself without reading files at random.
+
+---
+
+## The orientation problem
+
+Most developers starting on a new codebase do one of three things: they ask someone to walk them through it (expensive for the team), they read files top-to-bottom hoping to find patterns (slow), or they wait until they need to touch something and learn as they go (risky).
+
+AI assistants make this better in theory — but without a structured index, they can only help you understand files you explicitly show them. PureContext lets Claude navigate the codebase proactively, building a picture you can interrogate.
+
+---
+
+## Step 1: Get the lay of the land
+
+Start by asking Claude to describe the project structure:
+
+> "Give me an overview of this project's structure. What are the main directories and what do they contain?"
+
+Claude will call `get_file_tree` and `get_repo_outline` to return a directory breakdown and the top-level symbols per file — without reading any file content. In a 200-file TypeScript project, this might return something like:
+
+```
+src/
+  api/          — 12 files, 87 symbols (routes, controllers, middleware)
+  core/         — 8 files, 64 symbols (services, domain logic)
+  db/           — 5 files, 43 symbols (models, migrations, queries)
+  workers/      — 3 files, 28 symbols (background job handlers)
+  utils/        — 6 files, 51 symbols (formatters, validators, helpers)
+```
+
+That's the skeleton. You now know where things live without reading a single file.
+
+---
+
+## Step 2: Find the entry points
+
+> "Where does this application start? What are the main entry points?"
+
+Claude will search for common patterns — `main`, `createServer`, `app.listen`, `bootstrap` — and return the symbols with their signatures. For a Node.js API:
+
+```
+src/index.ts        — bootstrap()           starts the HTTP server
+src/api/router.ts   — createRouter()        registers all routes
+src/workers/index.ts — startWorkers()       initializes background jobs
+```
+
+Three entry points, their file locations, their signatures — in seconds.
+
+---
+
+## Step 3: Follow a feature you care about
+
+Once you know the structure, pick a feature area you'll be working in and trace it:
+
+> "I'll be working on the payment system. Find all payment-related symbols."
+
+```
+search_symbols(query: "payment") →
+  processPayment()      src/core/billing.ts       function
+  PaymentGateway        src/api/gateway.ts         class
+  validatePaymentMethod src/core/validators.ts      function
+  POST /payments        src/api/routes/payments.ts  route
+  PaymentRecord         src/db/models/payment.ts    class (ORM model)
+```
+
+Five symbols across five files gives you the full map of the payment system before you've opened a single file.
+
+---
+
+## Step 4: Understand a specific symbol in depth
+
+Now pick the one that matters most:
+
+> "Show me how processPayment works and what it depends on."
+
+Claude calls `get_context_bundle` starting from `processPayment`. It returns the function's source plus everything it imports transitively — `validatePaymentMethod`, `PaymentGateway`, the database model — up to the depth you specify. The token estimate tells you how large the context is before it loads.
+
+This is the difference between "read billing.ts" (entire file) and "get the context bundle for processPayment" (exactly the symbols involved in payment processing, nothing else).
+
+---
+
+## Step 5: Ask questions about what you've found
+
+With the context bundle loaded, ask anything:
+
+> "What happens if the payment gateway is unavailable? Does this code handle that case?"
+
+> "Where does the currency conversion happen? I don't see it in processPayment."
+
+> "Who calls this function? I want to make sure I understand all the places payments are triggered."
+
+Claude uses `find_importers` and `search_symbols` to answer the last question without you having to search manually.
+
+---
+
+## For enterprise onboarding: going deeper
+
+On a large codebase, you won't understand everything in one session. Use PureContext to build a map over time:
+
+**Day 1:** Project structure, entry points, the one domain area you'll be working in.
+
+**Day 2:** The APIs your domain area calls. The services it depends on. The database tables it touches.
+
+**Week 1:** The patterns the codebase uses. How errors propagate. How authentication works. How jobs are scheduled.
+
+Each of these is a focused PureContext session — specific questions with targeted symbol retrieval. You're not reading documentation that may be stale. You're reading the code that's actually running.
+
+---
+
+## Tips
+
+**Use `get_file_outline` on files you'll be editing frequently.** It gives you a complete list of everything defined in a file with signatures and summaries — a live table of contents that's always current.
+
+**Ask about naming conventions early.** `search_symbols(query: "user")` in a new codebase tells you immediately whether the team calls things `User`, `UserRecord`, `UserEntity`, or `Account`. Understanding the vocabulary saves hours.
+
+**Don't try to understand everything at once.** The goal of day-one orientation is to know where to find things, not to understand every file. Let the index do the navigation for you when you need something specific.
+
+---
+
+→ Reference: [MCP Tools Reference](../docs/06-tools-reference.md) — `get_file_tree`, `get_repo_outline`, `get_file_outline`, `search_symbols`, `get_context_bundle`

package/guide/safe-changes.md

@@ -0,0 +1,156 @@
+# Making Changes Safely
+
+The hardest part of changing code in a large codebase is not writing the new code — it's understanding what the old code touches. Every change that breaks something unexpected does so because the developer didn't know about a dependency they couldn't see.
+
+PureContext gives you two tools that together form a complete pre-change analysis workflow: **blast radius** (what does this touch?) and **context bundle** (what does this need?).
+
+---
+
+## The blast radius: knowing your impact before you start
+
+Before you change anything, find out what depends on it.
+
+**Scenario:** You're refactoring a utility function `formatCurrency` that's been in the codebase for three years. It's used everywhere, but you don't know exactly where.
+
+> "Before I refactor formatCurrency, show me everything that uses it."
+
+Claude calls `get_blast_radius` and returns:
+
+```
+formatCurrency() is imported by 23 files:
+  Direct importers (depth 1):
+    src/billing/invoice.ts
+    src/reporting/pdf-generator.ts
+    src/api/responses/pricing.ts
+    src/ui/components/PriceDisplay.tsx
+    ... (8 more)
+
+  Transitive importers (depth 2–3):
+    src/api/routes/orders.ts  (via billing/invoice.ts)
+    src/workers/monthly-report.ts  (via reporting/pdf-generator.ts)
+    ... (9 more)
+
+  Total files affected: 23
+```
+
+You now know the scope before you've written a line. If the blast radius is 23 files, you know this change needs careful testing. If it's 2, you can move quickly.
+
+**What the blast radius tells you:**
+- Files you need to update if the function's signature changes
+- Test files that will break if behavior changes
+- Services that will fail if the function is removed
+- The difference between "safe to refactor locally" and "needs a deprecation cycle"
+
+**Using blast radius for deletion decisions:**
+
+> "I think this helper is unused — can you confirm?"
+
+```
+get_blast_radius(symbolId: "legacyFormatDate-id") →
+  importers: []
+  count: 0
+```
+
+Zero importers. Safe to delete. `find_dead_code` will surface all such symbols at once across the whole codebase.
+
+---
+
+## The context bundle: understanding what you're changing
+
+Once you know the impact scope, understand the code itself before you touch it.
+
+**Scenario:** You need to modify the `processOrder` function but you've never worked in this part of the codebase. You need to understand what it calls, what data it expects, and what it produces.
+
+> "Give me everything I need to understand processOrder before I change it."
+
+Claude calls `get_context_bundle` starting from `processOrder` with a depth of 2:
+
+```
+Context bundle for processOrder():
+
+  processOrder()          src/orders/processor.ts    (the function itself, 67 lines)
+  validateCart()          src/cart/validator.ts      (called by processOrder, 34 lines)
+  calculateTax()          src/billing/tax.ts          (called by processOrder, 28 lines)
+  formatPrice()           src/utils/format.ts         (called by validateCart, 12 lines)
+  OrderRecord             src/db/models/order.ts      (the data shape, 22 lines)
+
+  Token estimate: 1,240 tokens
+  Files covered: 5
+```
+
+1,240 tokens for a complete picture of the order processing flow. Reading those 5 files directly would be ~8,000 tokens and would include unrelated functions, imports, and comments.
+
+**Setting depth:** `maxDepth: 1` gives you just the direct dependencies. `maxDepth: 3` follows the dependency chain further but returns more. Start at 2 and go deeper only if you need it.
+
+**Setting a token budget:** If you're working within a context window budget, set `maxTokens` and the bundle will stop collecting symbols once the estimate exceeds it — always returning the most directly connected ones first.
+
+---
+
+## The complete pre-change workflow
+
+This is the pattern to use before any significant change:
+
+```
+1. Identify the symbol you're changing
+   search_symbols(query: "processOrder") → find the right one
+
+2. Check the blast radius
+   get_blast_radius(symbolId) → how many files are affected?
+
+3. Understand the symbol in context
+   get_context_bundle(symbolId, maxDepth: 2) → what does it depend on?
+
+4. Make the change
+
+5. Verify nothing became orphaned
+   find_dead_code(repoId) → any exports that are now unused?
+
+6. Re-index (if you changed signatures)
+   index_folder → incremental, fast, picks up your changes
+```
+
+---
+
+## Detecting architectural violations before they ship
+
+PureContext can also check whether your change violates the project's intended layer structure. If your codebase has defined architectural layers — for example, "core services must not import from API controllers" — the `get_layer_violations` tool checks for violations across the whole codebase.
+
+> "Check if my changes introduced any architectural boundary violations."
+
+```
+get_layer_violations(repoId) →
+
+  VIOLATION: src/core/billing.ts imports from src/api/middleware/auth.ts
+  Layer: core → api  (not allowed per layer rules)
+  Import: AuthMiddleware
+```
+
+Catch these before code review, not during.
+
+---
+
+## For teams: sharing impact analysis
+
+In a team environment, blast radius analysis is especially valuable during planning. Before a developer starts on a change, ask PureContext to assess the scope:
+
+> "We're planning to move the authentication service from JWT to session-based auth. What's the blast radius of changing the validateToken function?"
+
+The answer tells the team how many files need to be updated, which services are affected, and whether this is a one-person job or a coordinated migration. That's a planning conversation that used to require a senior engineer's memory of the codebase.
+
+---
+
+## For legacy codebases
+
+Legacy codebases are where blast radius analysis pays off most. Nobody knows all the call sites for a function that's been there for five years. PureContext does.
+
+Before refactoring anything in a legacy system:
+
+1. Run `find_dead_code` first — it often reveals that 20% of what you thought you needed to understand is actually unused
+2. Use blast radius on the symbols you do need to change — the dependency graph doesn't lie
+3. Use context bundle to understand the chain before proposing a change to your team
+
+This transforms "I think this change is safe but I'm not sure" into "I know exactly which 7 files this change affects and here they are."
+
+---
+
+→ Reference: [MCP Tools Reference](../docs/06-tools-reference.md) — `get_blast_radius`, `get_context_bundle`, `find_importers`, `find_dead_code`, `get_layer_violations`

package/guide/team-setup.md

@@ -0,0 +1,191 @@
+# Using PureContext with a Team
+
+Running PureContext locally is useful. Running it as a shared server is transformative. The difference is the difference between one person being able to navigate the codebase and the whole team navigating it — with the same index, the same symbol summaries, and the same dependency graph.
+
+---
+
+## The problem with local-only indexing
+
+When every developer runs PureContext locally, several problems emerge:
+
+**Inconsistent indexes.** Alice indexed last Tuesday. Bob indexed this morning. Charlie hasn't indexed at all since he joined. When the team asks the AI questions about the codebase, they're getting answers from three different versions of the truth.
+
+**Redundant work.** A 10,000-file codebase takes a minute to index from scratch. Every developer on a 20-person team does this independently. It's 20 minutes of CPU time and API calls (if AI summaries are enabled) that could have been done once.
+
+**No shared knowledge base.** Symbol summaries generated by AI are stored in the local index. The rich, useful summaries that help Alice navigate the codebase exist only on Alice's laptop. Bob gets a different quality of search because he hasn't generated summaries yet.
+
+**CI doesn't benefit.** A local index goes stale the moment you push code and someone else merges. There's no way to keep it current across a team without a server.
+
+---
+
+## The shared server model
+
+A shared PureContext server indexes the codebase once and serves all team members. Every developer connects with a personal API key and queries the same index.
+
+```
+Developer A (Claude Code) ──┐
+Developer B (Claude Code) ──┤── HTTPS ──► PureContext Server ──► Shared SQLite Index
+Developer C (Claude Code) ──┘                                          ↑
+                                                              CI auto-reindex on push
+```
+
+The index is updated automatically when code is pushed, either through webhooks or CI. When a developer starts a conversation about a feature, they're working with the current state of the main branch — not whatever they had locally last week.
+
+---
+
+## Deploying the server
+
+The fastest path is Docker:
+
+```bash
+docker run -d \
+  --name purecontext \
+  -p 3000:3000 \
+  -v "$(pwd)/data:/data" \
+  -e PCTX_ADMIN_KEY="$(openssl rand -hex 32)" \
+  --restart unless-stopped \
+  purecontext/purecontext-mcp:latest
+```
+
+Save the `PCTX_ADMIN_KEY` — it's the root credential for all server management.
+
+Verify:
+```bash
+curl http://localhost:3000/health
+# {"status":"ok","version":"1.x.x","repoCount":0}
+```
+
+For production, put the server behind nginx or Caddy for TLS. See [Docker Deployment](../docs/16-docker.md) for the full nginx and Caddy configuration.
+
+---
+
+## Setting up workspaces and API keys
+
+A **workspace** is the unit of isolation. Each team or project gets its own workspace — separate repos, separate API keys, no cross-workspace access.
+
+```bash
+# Create a workspace for your team
+curl -s -X POST http://localhost:3000/admin/workspaces \
+  -H "Authorization: Bearer $PCTX_ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "backend-team"}'
+
+# → {"id": "ws_abc123", "name": "backend-team"}
+```
+
+Then create a personal API key for each developer:
+
+```bash
+curl -s -X POST http://localhost:3000/admin/keys \
+  -H "Authorization: Bearer $PCTX_ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"label": "alice-macbook", "workspace_id": "ws_abc123", "permissions": ["read", "write"]}'
+
+# → {"key": "pctx_00000000_..._1234"}  ← shown once, save immediately
+```
+
+**Permission levels:**
+
+| Permission | What it allows |
+|------------|---------------|
+| `read` | Search and retrieve — for AI agents that navigate but don't index |
+| `write` | + Index new repos and trigger re-indexing |
+| `admin` | + Manage keys and workspaces |
+
+Most developers should have `read` permission. CI pipelines and the one developer responsible for keeping the index current get `write`.
+
+---
+
+## Connecting each developer
+
+Each developer runs this once:
+
+```bash
+claude mcp add purecontext-shared \
+  --transport http \
+  --url https://purecontext.yourcompany.com/mcp/sse \
+  --header "Authorization: Bearer pctx_theirpersonalkey"
+```
+
+From that point on, when any team member talks to Claude about the codebase, they're working from the shared index. No individual indexing. No staleness.
+
+---
+
+## Keeping the index current with webhooks
+
+Configure a webhook in your repository to trigger re-indexing automatically on every push to main:
+
+```json
+{
+  "webhooks": {
+    "enabled": true,
+    "secret": "${WEBHOOK_SECRET}",
+    "branches": ["main", "develop"]
+  }
+}
+```
+
+In GitHub: Settings → Webhooks → Add webhook → Payload URL: `https://purecontext.yourcompany.com/webhook/github`.
+
+After this, every merged PR triggers an incremental re-index within seconds. The index is always current. Developers never need to think about it.
+
+---
+
+## Using GitHub Actions for CI integration
+
+For teams that want index building as part of CI rather than webhooks, the official GitHub Action handles it:
+
+```yaml
+- uses: purecontext/purecontext-mcp@v1
+  with:
+    token: ${{ secrets.GITHUB_TOKEN }}
+    analyze-diff: 'true'          # posts blast radius as PR comment
+    detect-antipatterns: 'false'  # set to 'true' to fail CI on critical issues
+    upload-index: 'true'          # uploads .pcx bundle as artifact
+```
+
+When `analyze-diff` is enabled, every pull request gets an automated comment showing which symbols changed, their blast radius, and the review priority — before a human reviewer has read a line.
+
+---
+
+## Onboarding new developers
+
+With a shared index and AI summaries enabled, a new developer's first day is fundamentally different.
+
+**Without PureContext:** "Here's the codebase. Here are some key files to read. Find someone to give you a walkthrough."
+
+**With PureContext:** The developer opens Claude Code, connects to the shared server, and asks questions.
+
+> "I'm new here. Give me an overview of the payment service and explain how orders flow through it."
+
+Claude uses `get_repo_outline`, `get_context_bundle`, and `get_file_outline` to build a picture and explain it. The explanation draws from the actual current code, not documentation that may be outdated. The new developer doesn't need to find a senior engineer — they can get a coherent, accurate orientation on demand.
+
+This doesn't eliminate the value of pairing and walkthroughs — it eliminates the need for them to cover basic navigation. Senior engineers spend time sharing context that can't be indexed, not explaining where the auth service lives.
+
+---
+
+## Enterprise considerations
+
+**Rate limiting:** Each API key has a configurable token bucket. Heavy operations like indexing cost more tokens than searches. This prevents any single AI agent from monopolizing the server.
+
+```json
+{
+  "rateLimit": {
+    "maxTokens": 100,
+    "refillRate": 10,
+    "perToolLimits": { "index_folder": 10, "search_symbols": 1 }
+  }
+}
+```
+
+**Audit logging:** The HTTP server logs every tool call with the key label, tool name, repoId, and duration. Pipe these to your log aggregator for compliance trails.
+
+**Data isolation:** API keys from one workspace cannot access repos in another. Workspace isolation is enforced at the SQL query level — there's no path to cross-workspace data access.
+
+**No data leaves your infrastructure:** PureContext stores everything in SQLite on your server. If you enable AI summarization, those calls go to whichever AI provider you've configured — otherwise, no external connections are made.
+
+---
+
+→ Reference: [Team Setup & Multi-Tenant](../docs/15-team-setup.md) — admin API reference, full configuration  
+→ Reference: [Docker Deployment](../docs/16-docker.md) — reverse proxy configuration, resource requirements  
+→ Reference: [Security](../docs/24-security.md) — threat model, hardening checklist

package/guide/web-ui.md

@@ -0,0 +1,154 @@
+# The Web UI
+
+PureContext's primary interface is the AI agent — you talk to Claude and it calls the tools. But some questions are easier to answer visually than through conversation. The Web UI exists for those moments.
+
+It runs in a browser alongside the MCP server and requires no separate installation — start the server in HTTP mode and open `http://localhost:3000`.
+
+```bash
+purecontext-mcp --transport http --port 3000
+```
+
+---
+
+## When to use the UI instead of the chat
+
+**The chat is better for:** Specific questions, targeted retrieval, workflows that need AI reasoning alongside code navigation. "Find the authentication logic and explain why the session expiry is set the way it is."
+
+**The UI is better for:** Understanding the big picture, spotting patterns, navigating by clicking rather than typing, sharing a visual with your team, architecture reviews.
+
+The two complement each other. Start a session in the chat to understand a specific feature, then open the UI to see where that feature sits in the larger dependency map.
+
+---
+
+## Repository browser
+
+The sidebar lists every indexed repository with symbol counts, file counts, and language breakdown. Click a repository to open its file tree.
+
+The file tree is collapsible and shows symbol counts per directory. Click any file to open its **symbol outline** — all symbols in the file with their signatures and summaries, like a live table of contents. Click any symbol to open its source.
+
+This is the fastest way to get a feel for a module you haven't worked in before: expand the directory, scan the symbol outline, open the two or three symbols that seem most relevant.
+
+---
+
+## Symbol search
+
+The search bar at the top is always available. Start typing and results appear within 300ms — no need to press Enter.
+
+- **Keyword mode:** Searches symbol names and summaries. `processOrder` and `process order` return the same results.
+- **Semantic mode:** Toggle to search by meaning. "function that validates credentials" finds relevant symbols even if none of them have "validate" or "credentials" in their name.
+- **Filters:** Narrow by symbol kind (function, class, route, component, etc.) or file path pattern.
+
+Results are navigable by keyboard: arrow keys to move, Enter to open. Query terms are highlighted in results so you can see why each result matched.
+
+---
+
+## Symbol viewer
+
+Clicking any symbol opens a syntax-highlighted view of its source. The highlighter uses the same token definitions as VS Code — the rendering quality is the same as your editor.
+
+The right panel shows three related sets:
+- **Dependencies** — symbols this one imports, in order of relevance
+- **Importers** — symbols that import this one (the blast radius, one level)
+- **Same file** — other symbols defined in the same file
+
+Clicking any of these navigates to that symbol. This lets you trace a dependency chain by clicking through the graph rather than running a series of queries.
+
+URLs are shareable. Each symbol view has a stable URL — link a colleague directly to the function you want them to look at.
+
+---
+
+## Dependency graph viewer
+
+The graph view renders the dependency relationships between files and symbols as a force-directed network. Nodes are files or symbols; edges are import relationships.
+
+Open the graph viewer from any symbol with the **G** keyboard shortcut, or from the toolbar.
+
+### Navigating the graph
+
+| Action | How |
+|--------|-----|
+| Pan | Click and drag the background |
+| Zoom | Scroll wheel |
+| Fit everything in view | Double-click background |
+| Select a node | Click it |
+| Expand a node's connections | Click the **+** button on the node |
+| Switch between dependency/importer view | Toggle in toolbar |
+
+### Layout options
+
+- **Force-directed** (default): Nodes cluster by how connected they are. Highly-connected files naturally cluster toward the center. Leaf nodes float outward. This reveals the structure of your codebase without any manual arrangement.
+- **Hierarchical**: Root at top, dependencies flow downward. Clearer for trees with a single root.
+- **Radial**: Selected node at center, connected nodes radiate out. Good for exploring one module's connections.
+
+### Blast radius view
+
+Switch to blast radius mode to see everything that depends on the selected node — color gradient from red (directly imports this) to yellow (transitively imports this). This is the visual equivalent of `get_blast_radius`, and it makes the scope of a change immediately legible in a way that a file list cannot.
+
+**Practical use:** Before a code review or planning meeting, open the blast radius view for the symbols being changed. The visual immediately communicates whether this is a localized change or a cross-cutting concern.
+
+### Depth control
+
+The depth slider controls how many hops from the selected node are shown. At depth 1 you see direct connections. At depth 3 or 4 you see the full transitive graph. Large graphs at high depth can get dense — use the language and kind filters to focus on what matters.
+
+### Cycle detection
+
+Enable cycle detection to highlight circular dependencies in red. Circular dependencies are often a sign of architectural problems — modules that depend on each other can't be changed independently and are hard to test in isolation.
+
+---
+
+## Architecture heatmap
+
+The heatmap overlays your file tree with color-coded quality signals. Select a metric from the dropdown and every file in the tree gets a color:
+
+| Metric | What it shows |
+|--------|--------------|
+| **Churn** | Blue (stable) to red (high churn). High-churn files are actively changing or unstable. |
+| **Complexity** | Green to red. Red files have high cyclomatic complexity — hard to understand and test. |
+| **Quality score** | Green (healthy) to red (needs attention). Composite of complexity, coupling, and documentation coverage. |
+| **Test coverage** | Green (well-covered) to red (uncovered). Requires uploading an lcov coverage report. |
+
+Click any file cell in the heatmap to open its symbol outline. The heatmap is particularly effective for architecture reviews and sprint planning — it makes "where should we focus our technical debt effort?" a visual answer rather than a debate.
+
+**Uploading test coverage:** Generate an lcov report from your test suite (`npx vitest --coverage`, `pytest --cov`, etc.) and upload it in Settings → Coverage. The coverage overlay then appears as an option in the heatmap dropdown.
+
+---
+
+## Symbol timeline
+
+The symbol timeline shows a function's git history as a visual chart. Each commit that touched the symbol appears as a marker on the timeline.
+
+Hover any marker to see the commit message, author, and date. Click to expand the diff for that function at that point — what lines were added, what were removed, what the function looked like before.
+
+This is useful for three scenarios:
+
+**Understanding why something is the way it is.** Follow the timeline backward. The function grew in a particular direction for a reason — the commit messages explain the decisions that accumulated over time.
+
+**Finding when a bug was introduced.** Scan the timeline for changes around the date the bug was reported. The diff at that commit is usually the answer.
+
+**Onboarding walkthroughs.** Show a new team member the history of a core function as a story — "here's where we started, here's when we added caching, here's when we refactored for the multi-region launch."
+
+---
+
+## Multi-repo workspace
+
+When multiple repositories are indexed, the sidebar shows a repository switcher. The workspace view lists all repos with their key metrics. Cross-repo search results appear in a unified list with the source repository identified for each result.
+
+This is particularly useful for microservices architectures or monorepos with multiple packages — you can search across the entire system from a single interface without switching contexts.
+
+---
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| `/` | Focus search bar |
+| `↑` / `↓` | Navigate search results |
+| `Enter` | Open selected symbol |
+| `Esc` | Close panels / clear search |
+| `G` | Open graph view for current symbol |
+| `B` | Show blast radius for current symbol |
+| `H` | Toggle heatmap overlay |
+
+---
+
+→ Reference: [Web UI](../docs/17-web-ui.md) — full feature reference including build instructions