sdl-mcp 0.8.6 → 0.8.9

package/README.md

@@ -1,267 +1,492 @@
 <div align="center">
 <img src="https://github.com/GlitterKill/sdl-mcp/blob/main/docs/Symbol_Delta_Ledger_MCP.jpg" alt="Symbol Delta Ledger MCP">
-</div>
-<div align="center">
-</div>
+
+<br/>
 
 # SDL-MCP
 
-![npm version](https://img.shields.io/npm/v/sdl-mcp.svg) ![npm downloads](https://img.shields.io/npm/dm/sdl-mcp.svg) ![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/GlitterKill/sdl-mcp/ci.yml?label=CI%20Builds)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/GlitterKill/sdl-mcp/publish-native.yml?label=Rust%20Indexer%20Builds) ![GitHub commit activity](https://img.shields.io/github/commit-activity/w/GlitterKill/sdl-mcp)
+### **Cards-first code context for AI coding agents**
 
-<div align="right">
-<details>
-<summary><strong>Documentation</strong></summary>
+*Stop feeding entire files into the context window.<br/>Start giving agents exactly the code intelligence they need.*
 
-- [Overview (this page)](./README.md)
-- [Documentation Hub](./docs/README.md)
-  - [Getting Started](./docs/getting-started.md)
-  - [CLI Reference](./docs/cli-reference.md)
-  - [MCP Tools Reference](./docs/mcp-tools-reference.md)
-  - [Configuration Reference](./docs/configuration-reference.md)
-  - [Agent Workflows](./docs/agent-workflows.md)
-  - [Troubleshooting](./docs/troubleshooting.md)
-- [Legacy User Guide](./docs/USER_GUIDE.md)
+<br/>
+
+![npm version](https://img.shields.io/npm/v/sdl-mcp.svg)
+![npm downloads](https://img.shields.io/npm/dm/sdl-mcp.svg)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/GlitterKill/sdl-mcp/ci.yml?label=CI%20Builds)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/GlitterKill/sdl-mcp/publish-native.yml?label=Rust%20Indexer%20Builds)
+![GitHub commit activity](https://img.shields.io/github/commit-activity/w/GlitterKill/sdl-mcp)
 
-</details>
 </div>
 
-## Claude Opus 4.6 High Overview
+---
+
+<br/>
+
+## What's the problem?
 
-Question: "Review the code for SDL-MCP and explain to potential new users what this MCP server does and the benefits of
-using it."
+Every time an AI coding agent reads a file to answer a question, it consumes thousands of tokens. Most of those tokens are irrelevant to the task. The agent doesn't need 500 lines of a file to know that `validateToken` takes a `string` and returns a `Promise<User>` — but it reads them anyway, because that's all it has.
 
-Response: "# What is SDL-MCP?
+**Multiply that across a debugging session touching 20 files and you've burned 40,000+ tokens on context gathering alone.**
 
-**SDL-MCP** (Symbol Delta Ledger - Model Context Protocol) is an MCP server that gives AI coding agents a structured,
-token-efficient way to understand your codebase. Instead of feeding entire files into the context window, SDL-MCP
-indexes your repository into a **searchable knowledge graph** of symbols and their relationships, then serves exactly
-the right amount of context through a controlled escalation path.
+SDL-MCP fixes this. It indexes your codebase into a searchable **symbol graph** and serves precisely the right amount of context through a controlled escalation path. An agent that uses SDL-MCP understands your code better while consuming a fraction of the tokens.
 
-It ships as an npm package (`npm install -g sdl-mcp`) with a CLI for setup and a server that any MCP-compatible client
-(Claude Code, Claude Desktop, etc.) can connect to.
+<br/>
 
 ---
 
-## The Problem It Solves
+<br/>
 
-When AI assistants work with code, they typically read whole files — often many of them — to gather enough context.
-This has three costs:
+## How it works — in 30 seconds
 
-1. **Context windows fill up fast.** A modest codebase can exceed token limits quickly.
-2. **Irrelevant code dilutes focus.** Tokens are spent on code unrelated to the task.
-3. **No incremental understanding.** Every interaction starts fresh with no memory of what was already analyzed.
+```
+                Your Codebase
+                     │
+              ┌──────┴──────┐
+              │   Indexer    │   Native Rust (fast) or Tree-sitter (universal)
+              │   12 langs   │   TS · JS · Python · Go · Java · C# · C · C++ · PHP · Rust · Kotlin · Shell
+              └──────┬──────┘
+                     │
+                     ▼
+         ┌───────────────────────┐
+         │   Symbol Graph (DB)   │   Functions, classes, interfaces, types, edges, metrics
+         │   LadybugDB (graph)   │   Persisted. Incremental. Versioned.
+         └───────────┬───────────┘
+                     │
+          ┌──────────┼──────────┐
+          │          │          │
+          ▼          ▼          ▼
+      25 MCP      10 CLI    HTTP API
+       Tools     Commands   + Graph UI
+          │
+          ▼
+    AI Coding Agent
+    (Claude Code, Claude Desktop, Cursor, Windsurf, any MCP client)
+```
 
-SDL-MCP addresses all three by maintaining a **persistent, indexed graph** of your codebase and controlling context
-retrieval through the **Iris Gate Ladder**.
+1. **Index once** — SDL-MCP parses every symbol in your repo and stores it as a compact metadata record (a "Symbol Card") in a graph database
+2. **Query efficiently** — Agents use MCP tools to search, slice, and retrieve exactly the context they need
+3. **Escalate only when necessary** — A four-rung ladder controls how much code the agent sees, from a 100-token card to full source (with justification required)
+
+<br/>
 
 ---
 
-## How It Works
+<br/>
 
-### 1. Repository Indexing
+## Quick Start
 
-SDL-MCP parses your codebase using either a **native Rust indexer** (default, fast, multi-threaded) or a **tree-sitter
-TypeScript fallback**, and extracts every function, class, interface, type, and variable into **Symbol Cards** —
-compact metadata records containing signatures, summaries, dependency edges, and metrics like fan-in/out.
+```bash
+# Install
+npm install -g sdl-mcp
 
-**12 languages supported:** TypeScript, JavaScript, Python, Go, Java, C#, C, C++, PHP, Rust, Kotlin, and Shell.
+# Initialize, auto-detect languages, index your repo, and run health checks
+sdl-mcp init -y --auto-index
 
-Indexing happens once and is persisted in a **LadybugDB embedded graph database**. Incremental re-indexing picks up only
-what changed.
+# Start the MCP server for your coding agent
+sdl-mcp serve --stdio
+```
+
+Point your MCP client at the server and the agent gains access to all SDL-MCP tools. That's it.
 
-### 2. The Iris Gate Ladder (4 Rungs)
+> **npx users:** Replace `sdl-mcp` with `npx --yes sdl-mcp@latest` in all commands above.
 
-Context is served in escalating detail — agents start small and only request more when needed:
+[Full Getting Started Guide →](./docs/getting-started.md)
 
-| Rung                    | Tool                   | ~Tokens     | What It Provides                                |
-| :---------------------- | :--------------------- | :---------- | :---------------------------------------------- |
-| **1. Symbol Cards**     | `sdl.symbol.getCard`   | 50–150      | Name, signature, summary, dependencies, metrics |
-| **2. Skeleton IR**      | `sdl.code.getSkeleton` | 200–400     | Signatures + control flow, bodies elided        |
-| **3. Hot-Path Excerpt** | `sdl.code.getHotPath`  | 400–800     | Lines matching specific identifiers + context   |
-| **4. Raw Code Window**  | `sdl.code.needWindow`  | 1,000–4,000 | Full source code (policy-gated, requires        |
-| justification)          |
+<br/>
+
+---
 
-> [!TIP]
-> Most questions are answered at rungs 1–2 without ever reading raw code.
+<br/>
 
-### 3. Graph Slices
+## The Iris Gate Ladder
 
-When the agent needs broader context for a task, `sdl.slice.build` performs a **BFS/beam search** from entry symbols
-across weighted dependency edges (call > config > import), bounded by a token budget. The result is the 20–30 most
-relevant symbols for the task — not an arbitrary directory listing.
+The core innovation. Named after the adjustable aperture that controls light flow in optics, the Iris Gate Ladder lets agents dial their context "aperture" from a pinhole to wide-open.
+
+```
+    Token Cost    What the Agent Sees
+                  ────────────────────────────────────────────────
+         ~100     RUNG 1 ▸ Symbol Card
+                  Name, signature, summary, dependencies, metrics
+                  "What does this function do and what does it call?"
+
+         ~300     RUNG 2 ▸ Skeleton IR
+                  Signatures + control flow, bodies replaced with /* ... */
+                  "What's the shape of this class?"
+
+         ~600     RUNG 3 ▸ Hot-Path Excerpt
+                  Only lines matching specific identifiers + context
+                  "Where exactly is `this.cache` initialized?"
+
+       ~2,000     RUNG 4 ▸ Raw Code Window  Policy-gated
+                  Full source code, requires justification
+                  "I need to rewrite this error handler"
+```
 
-### 4. Delta Packs & Blast Radius
+> **Most questions are answered at Rungs 1-2** without ever reading raw code. That's where the token savings come from.
 
-When code changes, SDL-MCP computes **semantic diffs at the symbol level** — not line-level diffs, but changes to
-signatures, invariants, and side effects. It also computes a **blast radius**: which other symbols are affected,
-ranked by proximity, fan-in, and test coverage.
+| Scenario | Reading the file | Using the Ladder | Savings |
+|:---------|:----------------:|:----------------:|:-------:|
+| "What does `parseConfig` accept?" | ~2,000 tok | ~100 tok | **20x** |
+| "Show me the shape of `AuthService`" | ~4,000 tok | ~300 tok | **13x** |
+| "Where is `this.cache` set?" | ~2,000 tok | ~500 tok | **4x** |
 
-### 5. Proof-of-Need Gating
+[Iris Gate Ladder Deep Dive →](./docs/feature-deep-dives/iris-gate-ladder.md)
 
-Raw code access (rung 4) requires the agent to justify _why_ it needs the code, _what identifiers_ it expects to find,
-and _how many lines_. Requests are audited. This enforces disciplined token usage.
+<br/>
 
 ---
 
-## Key Benefits
+<br/>
 
-### Token Efficiency
+## Feature Tour
 
-- **10–50x fewer tokens** per coding task compared to reading raw files
-- **2,782x compression ratio** for a repository overview vs. a full card dump
+### Symbol Cards — The Atoms of Understanding
 
-### Better Relevance
+Every function, class, interface, type, and variable becomes a **Symbol Card**: a compact metadata record (~100 tokens) containing everything an agent needs to *understand* a symbol without reading its code.
 
-- Graph-based slicing finds related code that directory-based approaches miss
-- Confidence-scored call resolution filters noise from low-confidence edges
+```
+  ┌─────────────────────────────────────────────────────────┐
+  │  Symbol Card: validateToken                             │
+  │─────────────────────────────────────────────────────────│
+  │  Kind:       function (exported)                        │
+  │  File:       src/auth/jwt.ts:42-67                      │
+  │  Signature:  (token: string, opts?: ValidateOpts)       │
+  │              → Promise<DecodedToken>                    │
+  │  Summary:    Validates JWT signature and expiration,    │
+  │              returns decoded payload or throws          │
+  │  Invariants: ["throws on expired token"]                │
+  │  Side FX:    ["logs to audit trail"]                    │
+  │  Deps:       calls: [verifySignature, checkExpiry]      │
+  │              imports: [jsonwebtoken, AuditLogger]        │
+  │  Metrics:    fan-in: 12 │ fan-out: 4 │ churn: 3/30d    │
+  │  Cluster:    auth-module (8 members)                    │
+  │  Process:    request-pipeline (intermediate, depth 1)   │
+  │  Test:       auth.test.ts (distance: 1, proximity: 0.9)│
+  │  ETag:       a7f3c2... (for conditional requests)       │
+  └─────────────────────────────────────────────────────────┘
+```
 
-### Incremental Understanding
+Cards include **confidence-scored call resolution** (the pass-2 resolver traces imports, aliases, barrel re-exports, and tagged templates to produce accurate dependency edges), **community detection** (cluster membership), and **call-chain tracing** (process participation with entry/intermediate/exit roles).
 
-- Delta packs mean the agent doesn't re-read unchanged code
-- Slice handles with leases and refresh support avoid rebuilding context from scratch
+[Indexing & Language Support Deep Dive →](./docs/feature-deep-dives/indexing-languages.md)
+
+---
 
-### Governance & Auditability
+### Graph Slicing — The Right Context for Every Task
 
-- Configurable policies control what agents can access
-- Every raw code request is logged with justification
-- Blast radius analysis shows ripple effects before changes land
+Instead of reading files in the same directory, SDL-MCP follows the *dependency graph*. Starting from symbols relevant to your task, it traverses weighted edges (call: 1.0, config: 0.8, import: 0.6), scores each symbol by relevance, and returns the N most important within a token budget.
+
+```
+  "Fix the auth middleware"     →   slice.build
+                                         │
+                                    BFS over graph
+                                         │
+                      ┌──────────────────┼──────────────────┐
+                      ▼                  ▼                  ▼
+                 authenticate      validateToken        JwtConfig
+                      │                  │                  │
+                      ▼                  ▼                  ▼
+                 hashPassword       getUserById         envLoader
+                                                            │
+                                                         ◆ frontier
+                                                    (outside budget)
+
+                 8 cards returned  ·  ~800 tokens
+            vs.  reading 8 files  ·  ~16,000 tokens
+```
 
-### Multi-Language
+Slices have handles, leases, refresh (delta-only updates), and spillover (paged overflow). You can also skip the symbol search entirely — pass a `taskText` string and SDL-MCP auto-discovers the relevant entry symbols.
 
-- 12 language adapters with a generalized pass-2 resolver for cross-file semantic resolution
+[Graph Slicing Deep Dive →](./docs/feature-deep-dives/graph-slicing.md)
 
 ---
 
-## Feature Summary
+### Delta Packs & Blast Radius — Semantic Change Intelligence
 
-| Category            | Features                                                                                            |
-| :------------------ | :-------------------------------------------------------------------------------------------------- |
-| **Indexing**        | Native Rust + tree-sitter fallback, incremental indexing, live editor-buffer overlay, file watching |
-| **Context**         | Symbol cards, skeleton IR, hot-path excerpts, gated raw windows                                     |
-| **Graph**           | Slices with handles/leases/refresh/spillover, cluster detection, call-chain tracing                 |
-| **Change Tracking** | Delta packs, blast radius analysis, PR risk scoring                                                 |
-| **Intelligence**    | Semantic search reranking, LLM-generated summaries, predictive prefetch                             |
-| **Governance**      | Policy engine, proof-of-need gating, audit logging                                                  |
-| **Agent Support**   | `sdl.agent.orchestrate` autopilot, `sdl.context.summary` for copy/paste context                     |
-| **Tools**           | 17+ MCP tools, 10 CLI commands, HTTP API with graph explorer UI                                     |
-| **Integrations**    | VSCode extension, Claude Code/Desktop, any MCP client                                               |
+`git diff` tells you what lines changed. SDL-MCP tells you what that change *means* and who's affected.
+
+```
+  Modified: validateToken() signature
+       │
+       ├── signatureDiff: added `options?: object` parameter
+       ├── invariantDiff: added "throws on expired"
+       └── sideEffectDiff: added "logs to audit trail"
+              │
+              ▼
+       Blast Radius (ranked):
+       1. authenticate()    ← direct caller, distance 1
+       2. refreshSession()  ← direct caller, distance 1
+       3. AuthMiddleware     ← calls authenticate, distance 2
+       4. auth.test.ts      ← test coverage, flagged for re-run
+```
+
+**PR risk analysis** (`sdl.pr.risk.analyze`) wraps this into a scored assessment with findings, evidence, and test recommendations. **Fan-in trend analysis** detects "amplifier" symbols whose growing dependency count means changes ripple further over time.
+
+[Delta & Blast Radius Deep Dive →](./docs/feature-deep-dives/delta-blast-radius.md)
+
+---
+
+### Live Indexing — Real-Time Code Intelligence
+
+SDL-MCP doesn't wait for you to save. As you type in your editor, buffer updates are pushed to an in-memory overlay store, parsed in the background, and merged with the durable database. Search, cards, and slices reflect your *current* code, not your last save.
+
+```
+  Editor keystrokes → sdl.buffer.push → Overlay Store → merged reads
+                                              │
+                                         on save / idle
+                                              │
+                                              ▼
+                                        LadybugDB (durable)
+```
+
+[Live Indexing Deep Dive →](./docs/feature-deep-dives/live-indexing.md)
+
+---
+
+### Governance & Policy — Controlled Access
+
+Raw code access (Rung 4) is **policy-gated**. Agents must provide:
+- A **reason** explaining why they need raw code
+- **Identifiers** they expect to find in the code
+- An **expected line count** within configured limits
+
+Requests that don't meet policy are denied with actionable guidance ("try `getHotPath` with these identifiers instead"). Every access is audit-logged.
+
+The sandboxed runtime execution tool (`sdl.runtime.execute`) has its own governance layer: disabled by default, executable allowlisting, CWD jailing, environment scrubbing, concurrency limits, and timeout enforcement.
+
+[Governance & Policy Deep Dive →](./docs/feature-deep-dives/governance-policy.md)
+
+---
+
+### Agent Orchestration — Autopilot Mode
+
+`sdl.agent.orchestrate` is an autonomous task engine. Give it a task type (`debug`, `review`, `implement`, `explain`), a description, and a budget — it plans the optimal Iris Gate path, executes it, collects evidence, and returns a synthesized answer.
+
+The feedback loop (`sdl.agent.feedback`) records which symbols were useful and which were missing, improving future slice quality.
+
+`sdl.context.summary` generates portable, token-bounded context briefings in markdown, JSON, or clipboard format for use outside MCP environments.
+
+[Agent Orchestration Deep Dive →](./docs/feature-deep-dives/agent-orchestration.md)
 
 ---
 
-## Getting Started
+### Sandboxed Runtime Execution
+
+Run tests, linters, and scripts through SDL-MCP's governance layer instead of uncontrolled shell access. Three runtimes (Node.js, Python, Shell), code-mode or args-mode, smart output summarization with keyword-matched excerpts, and gzip artifact persistence.
+
+[Runtime Execution Deep Dive →](./docs/feature-deep-dives/runtime-execution.md)
+
+---
+
+### CLI Tool Access — No MCP Server Required
+
+Access all 25 tool actions directly from the command line with `sdl-mcp tool`. No MCP server, transport, or SDK — just your terminal.
 
 ```bash
-# Install globally
-npm install -g sdl-mcp
+# Search for symbols
+sdl-mcp tool symbol.search --query "handleAuth" --output-format pretty
 
-# Initialize config + index your repo
-sdl-mcp init -y --auto-index
+# Build a task-scoped slice
+sdl-mcp tool slice.build --task-text "debug auth flow" --max-cards 50
 
-# Start the MCP server
-sdl-mcp serve --stdio
+# Pipe JSON args, chain commands
+echo '{"repoId":"my-repo"}' | sdl-mcp tool symbol.search --query "auth"
+```
 
-Then point your MCP client at the server — the agent gains access to all SDL-MCP tools and can navigate your codebase
-through the Iris Gate Ladder instead of bulk file reads.
+Features include typed argument coercion (string, number, boolean, string[], json), budget flag merging, stdin JSON piping with CLI-flags-win precedence, auto-resolved `repoId` from cwd, four output formats (json, json-compact, pretty, table), typo suggestions, and per-action `--help`. The CLI dispatches through the same gateway router and Zod schemas as the MCP server — identical code paths, identical validation.
 
-[!NOTE]
-See the full ./docs/getting-started.md and ./docs/mcp-tools-reference.md for detailed setup and usage instructions.
+[CLI Tool Access Deep Dive →](./docs/feature-deep-dives/cli-tool-access.md)
+
+---
 
+### Tool Gateway — 81% Token Reduction
+
+The tool gateway consolidates all 25 MCP tools into **4 namespace-scoped tools** (`sdl.query`, `sdl.code`, `sdl.repo`, `sdl.agent`), reducing `tools/list` overhead from **~3,742 tokens to ~713 tokens** — an **81% reduction**.
+
+```
+  Before:  25 tools × full JSON Schema = ~3,742 tokens at conversation start
+  After:    4 tools × thin schema       = ~713 tokens at conversation start
+                                          ─────────────
+                                          ~3,029 tokens saved per conversation
 ```
 
-## Core Feature Set
-
-- Multi-language repository indexing with tree-sitter adapters
-- Native Rust pass-1 indexing engine by default (`indexing.engine: "rust"`, with TypeScript fallback)
-- Live editor-buffer indexing with draft-aware symbol/search/slice reads, save-time LadybugDB patching, background reconciliation, and automatic checkpoint compaction (`liveIndex.*`)
-- Symbol cards with signatures, deps, metrics, and versioning
-- Graph slices with handles, leases, refresh, and spillover
-- Graph enrichment: clusters (community detection) + processes (call-chain traces) surfaced in cards/slices/overview/blast radius
-- Generalized pass2 resolver registry with TypeScript/JavaScript semantic pass2 plus Go pass2, and confidence-scored call metadata available through `symbol.getCard` and `slice.build`
-- Delta analysis and blast radius support with amplifier scoring
-- Semantic symbol search reranking (`sdl.symbol.search` with `semantic: true`)
-- LLM-generated symbol summaries with configurable concurrency and batching (`semantic.summaryModel`, `summaryMaxConcurrency`, `summaryBatchSize`)
-- Code access ladder: `getSkeleton` -> `getHotPath` -> `needWindow`
-- Policy management (`sdl.policy.get` / `sdl.policy.set`)
-- Repository overview and hotspot inspection (`sdl.repo.overview`)
-- PR risk analysis (`sdl.pr.risk.analyze`)
-- Agent orchestration tool (`sdl.agent.orchestrate`)
-- Predictive prefetch heuristics with status metrics (`prefetchStats`)
-- File watch debouncing for efficient incremental indexing (`indexing.watchDebounceMs`)
-- Live overlay controls for editor-buffer parsing and idle checkpointing (`liveIndex.debounceMs`, `liveIndex.idleCheckpointMs`, `liveIndex.maxDraftFiles`)
-- Canonical test mapping in symbol cards (`metrics.canonicalTest`)
-- Graph HTTP surface and browser explorer (`/api/graph/*`, `/ui/graph`)
-- VSCode extension MVP in `sdl-mcp-vscode/`
-- Sync artifact export/import/pull workflows
+Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "symbol.search", repoId: "x", query: "auth" }`) and routes to the same handlers with double Zod validation. Thin wire schemas in `tools/list` keep the registration compact while full validation happens server-side. Legacy flat tool names are optionally emitted alongside for backward compatibility.
+
+[Tool Gateway Deep Dive →](./docs/feature-deep-dives/tool-gateway.md)
+
+<br/>
+
+---
+
+<br/>
+
+## All 25 MCP Tools at a Glance
+
+<table>
+<tr><th>Category</th><th>Tool</th><th>One-Line Description</th></tr>
+<tr><td rowspan="4"><strong>Repository</strong></td>
+    <td><code>sdl.repo.register</code></td><td>Register a codebase for indexing</td></tr>
+<tr><td><code>sdl.repo.status</code></td><td>Health, versions, watcher, prefetch, live-index stats</td></tr>
+<tr><td><code>sdl.repo.overview</code></td><td>Codebase summary: stats, directories, hotspots, clusters</td></tr>
+<tr><td><code>sdl.index.refresh</code></td><td>Trigger full or incremental re-indexing</td></tr>
+
+<tr><td rowspan="3"><strong>Live Buffer</strong></td>
+    <td><code>sdl.buffer.push</code></td><td>Push unsaved editor content for real-time indexing</td></tr>
+<tr><td><code>sdl.buffer.checkpoint</code></td><td>Force-write pending buffers to the durable database</td></tr>
+<tr><td><code>sdl.buffer.status</code></td><td>Live indexing diagnostics and queue depth</td></tr>
+
+<tr><td rowspan="3"><strong>Symbols</strong></td>
+    <td><code>sdl.symbol.search</code></td><td>Search symbols by name (with optional semantic reranking)</td></tr>
+<tr><td><code>sdl.symbol.getCard</code></td><td>Get a symbol card with ETag-based conditional support</td></tr>
+<tr><td><code>sdl.symbol.getCards</code></td><td>Batch-fetch up to 100 cards in one round trip</td></tr>
+
+<tr><td rowspan="3"><strong>Slices</strong></td>
+    <td><code>sdl.slice.build</code></td><td>Build a task-scoped dependency subgraph</td></tr>
+<tr><td><code>sdl.slice.refresh</code></td><td>Delta-only update of an existing slice</td></tr>
+<tr><td><code>sdl.slice.spillover.get</code></td><td>Page through overflow symbols beyond the budget</td></tr>
+
+<tr><td rowspan="3"><strong>Code Access</strong></td>
+    <td><code>sdl.code.getSkeleton</code></td><td>Signatures + control flow, bodies elided</td></tr>
+<tr><td><code>sdl.code.getHotPath</code></td><td>Lines matching specific identifiers + context</td></tr>
+<tr><td><code>sdl.code.needWindow</code></td><td>Full source code (policy-gated, requires justification)</td></tr>
+
+<tr><td><strong>Deltas</strong></td>
+    <td><code>sdl.delta.get</code></td><td>Semantic diff + blast radius between versions</td></tr>
+
+<tr><td rowspan="2"><strong>Policy</strong></td>
+    <td><code>sdl.policy.get</code></td><td>Read current gating policy</td></tr>
+<tr><td><code>sdl.policy.set</code></td><td>Update line/token limits and identifier requirements</td></tr>
+
+<tr><td><strong>Risk</strong></td>
+    <td><code>sdl.pr.risk.analyze</code></td><td>Scored PR risk with findings and test recommendations</td></tr>
+
+<tr><td><strong>Context</strong></td>
+    <td><code>sdl.context.summary</code></td><td>Token-bounded portable briefing (markdown/JSON/clipboard)</td></tr>
+
+<tr><td rowspan="3"><strong>Agent</strong></td>
+    <td><code>sdl.agent.orchestrate</code></td><td>Autonomous task execution with budget control</td></tr>
+<tr><td><code>sdl.agent.feedback</code></td><td>Record which symbols were useful or missing</td></tr>
+<tr><td><code>sdl.agent.feedback.query</code></td><td>Query aggregated feedback statistics</td></tr>
+
+<tr><td><strong>Runtime</strong></td>
+    <td><code>sdl.runtime.execute</code></td><td>Sandboxed subprocess execution (Node/Python/Shell)</td></tr>
+</table>
+
+[Complete MCP Tools Reference (detailed parameters & responses) →](./docs/mcp-tools-detailed.md)
+
+<br/>
+
+---
+
+<br/>
 
 ## CLI Commands
 
-- `init` - bootstrap config and optional client template
-- `doctor` - validate runtime, config, DB path, grammars, repo access, and call-resolution capabilities
-- `index` - index repositories (optionally watch)
-- `serve` - run MCP server (`--stdio` or `--http`)
-- `export` - export sync artifact
-- `import` - import sync artifact
-- `pull` - pull by version/commit with fallback behavior
-- `benchmark:ci` - run CI benchmark checks, including edge-accuracy regression gating
-- `summary` - generate token-bounded copy/paste context summaries
-- `health` - compute composite index health score and badge/json output
-- `version` - show version and environment info
-
-## MCP Tools
-
-- Repository: `sdl.repo.register`, `sdl.repo.status`, `sdl.repo.overview`, `sdl.index.refresh`
-- Symbols: `sdl.symbol.search`, `sdl.symbol.getCard`
-- Context: `sdl.context.summary`
-- Slice: `sdl.slice.build`, `sdl.slice.refresh`, `sdl.slice.spillover.get`
-- Delta: `sdl.delta.get`
-- Code: `sdl.code.needWindow`, `sdl.code.getSkeleton`, `sdl.code.getHotPath`
-- Policy: `sdl.policy.get`, `sdl.policy.set`
-- Risk/Agent: `sdl.pr.risk.analyze`, `sdl.agent.orchestrate`
-
-See: [MCP Tools Reference](./docs/mcp-tools-reference.md)
+| Command | Description |
+|:--------|:------------|
+| `sdl-mcp init` | Bootstrap config, detect repo/languages, optionally auto-index |
+| `sdl-mcp doctor` | Validate runtime, config, DB, grammars, repo access |
+| `sdl-mcp index` | Index repositories (with optional `--watch` mode) |
+| `sdl-mcp serve` | Start MCP server (`--stdio` or `--http`) |
+| `sdl-mcp tool` | Access all 25 MCP tool actions directly ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
+| `sdl-mcp summary` | Generate copy/paste context summaries from the CLI |
+| `sdl-mcp health` | Compute composite health score with badge/JSON output |
+| `sdl-mcp export` | Export sync artifact |
+| `sdl-mcp import` | Import sync artifact |
+| `sdl-mcp pull` | Pull by version/commit with fallback |
+| `sdl-mcp version` | Show version and environment info |
 
-## Documentation
+[CLI Reference →](./docs/cli-reference.md) · [Configuration Reference →](./docs/configuration-reference.md)
 
-- [Documentation Hub](./docs/README.md)
-- [Iris Gate Ladder](./docs/IRIS_GATE_LADDER.md) - Context escalation methodology
-- [Architecture](./docs/ARCHITECTURE.md) - Tech stack and data flow
-- [Getting Started](./docs/getting-started.md)
-- [CLI Reference](./docs/cli-reference.md)
-- [MCP Tools Reference](./docs/mcp-tools-reference.md)
-- [Configuration Reference](./docs/configuration-reference.md)
-- [Agent Workflows](./docs/agent-workflows.md)
-- [Troubleshooting](./docs/troubleshooting.md)
-- [VSCode Extension README](./sdl-mcp-vscode/README.md)
-- [Legacy User Guide](./docs/USER_GUIDE.md)
+<br/>
 
-## Development
+---
 
-```bash
-npm run build
-npm run typecheck
-npm run lint
-npm test
-# Optional native addon + parity checks
-npm run build:native
-npm run test:native-parity
-```
+<br/>
+
+## Compatible With
+
+SDL-MCP works with any MCP-compatible client:
 
-Benchmark tooling (npm scripts):
+| Client | Transport | Setup |
+|:-------|:----------|:------|
+| **Claude Code** | stdio | `sdl-mcp init --client claude-code` |
+| **Claude Desktop** | stdio | `sdl-mcp init --client claude-code` |
+| **Cursor** | stdio | Standard MCP server config |
+| **Windsurf** | stdio | Standard MCP server config |
+| **Codex CLI** | stdio | `sdl-mcp init --client codex` |
+| **Gemini CLI** | stdio | `sdl-mcp init --client gemini` |
+| **OpenCode** | stdio | `sdl-mcp init --client opencode` |
+| **Any MCP client** | stdio / http | `sdl-mcp serve --stdio` or `--http` |
 
-- `npm run benchmark:real`
-- `npm run benchmark:matrix`
-- `npm run benchmark:sweep`
+A **VSCode extension** (`sdl-mcp-vscode/`) provides live buffer integration for real-time indexing of unsaved edits.
 
-Phase A benchmark lockfile:
+<br/>
+
+---
+
+<br/>
+
+## Tech Stack
+
+| Component | Technology |
+|:----------|:-----------|
+| Runtime | Node.js 20+ / TypeScript 5.9+ (strict ESM) |
+| Graph Database | LadybugDB (embedded, single-file) |
+| Indexer (default) | Rust via napi-rs (multi-threaded) |
+| Indexer (fallback) | tree-sitter + tree-sitter-typescript |
+| MCP SDK | @modelcontextprotocol/sdk |
+| Validation | Zod schemas for all payloads |
+| Transports | stdio (agents) · HTTP (dev/network) |
+
+<br/>
+
+---
+
+<br/>
+
+## Documentation
+
+| Document | Description |
+|:---------|:------------|
+| [Getting Started](./docs/getting-started.md) | Installation, 5-minute setup, MCP client config |
+| [MCP Tools Reference](./docs/mcp-tools-detailed.md) | Detailed docs for all 25 tools (parameters, responses, examples) |
+| [CLI Reference](./docs/cli-reference.md) | All CLI commands and options |
+| [Configuration Reference](./docs/configuration-reference.md) | Every config option with defaults and guidance |
+| [Agent Workflows](./docs/agent-workflows.md) | Workflow instructions for CLAUDE.md / AGENTS.md |
+| [Architecture](./docs/ARCHITECTURE.md) | Tech stack, data flow, component diagram |
+| [Iris Gate Ladder](./docs/IRIS_GATE_LADDER.md) | Context escalation methodology |
+| [Troubleshooting](./docs/troubleshooting.md) | Common issues and fixes |
+
+### Feature Deep Dives
+
+| Topic | What You'll Learn |
+|:------|:------------------|
+| [Iris Gate Ladder](./docs/feature-deep-dives/iris-gate-ladder.md) | Four-rung context escalation with token savings analysis |
+| [Graph Slicing](./docs/feature-deep-dives/graph-slicing.md) | BFS/beam search, edge weights, wire formats, auto-discovery |
+| [Delta & Blast Radius](./docs/feature-deep-dives/delta-blast-radius.md) | Semantic diffs, ranked impact analysis, PR risk scoring |
+| [Live Indexing](./docs/feature-deep-dives/live-indexing.md) | Real-time editor buffer integration and overlay architecture |
+| [Governance & Policy](./docs/feature-deep-dives/governance-policy.md) | Proof-of-need gating, audit logging, runtime sandboxing |
+| [Agent Orchestration](./docs/feature-deep-dives/agent-orchestration.md) | Autopilot mode, feedback loops, portable context summaries |
+| [Indexing & Languages](./docs/feature-deep-dives/indexing-languages.md) | Rust/TS engines, two-pass architecture, 12-language support |
+| [Runtime Execution](./docs/feature-deep-dives/runtime-execution.md) | Sandboxed subprocess execution with governance |
+| [CLI Tool Access](./docs/feature-deep-dives/cli-tool-access.md) | Direct CLI access to all 25 actions, output formats, stdin piping, scripting |
+| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md) | 25→4 tool consolidation, 81% token reduction, thin schemas, migration guide |
+| [Semantic Engine](./docs/feature-deep-dives/semantic-engine.md) | Pass-2 call resolution, embedding search, LLM summaries, confidence scoring |
+| [Semantic Embeddings Setup](./docs/feature-deep-dives/semantic-embeddings-setup.md) | Dependencies, model installation, provider configuration, tier-by-tier setup |
+
+<br/>
+
+---
 
-- `scripts/benchmark/phase-a-benchmark-lock.json` pins TS/Python/Tier-3 repos for reproducible baseline runs.
+<br/>
 
 ## License
 
 This project is **source-available**.
 
 - **Free Use (Community License):** You may use, run, and modify this software for any purpose, including **internal business use**, under the terms in [`LICENSE`](./LICENSE).
-- **Commercial Distribution / Embedding:** You must obtain a **commercial license** _before_ you **sell, license, sublicense, bundle, embed, or distribute** this software (or a modified version) **as part of a for-sale or monetized product or offering**. See [`COMMERCIAL_LICENSE.md`](./COMMERCIAL_LICENSE.md).
+- **Commercial Distribution / Embedding:** You must obtain a **commercial license** before you **sell, license, sublicense, bundle, embed, or distribute** this software as part of a for-sale or monetized product. See [`COMMERCIAL_LICENSE.md`](./COMMERCIAL_LICENSE.md).
 
-If you're unsure whether your use is "Commercial Distribution / Embedding", contact **gmullins.gkc@gmail.com**.
+Questions? Contact **gmullins.gkc@gmail.com**.