sdl-mcp 0.10.3 → 0.10.5

package/README.md

@@ -7,7 +7,7 @@
 
 ### **Cards-first code context for AI coding agents**
 
-*Stop feeding entire files into the context window.<br/>Start giving agents exactly the code intelligence they need.*
+_Stop feeding entire files into the context window.<br/>Start giving agents exactly the code intelligence they need._
 
 <br/>
 
@@ -19,10 +19,6 @@
 
 ---
 
-
-
-
-
 <br/>
 
 ## What's the problem?
@@ -46,7 +42,7 @@ flowchart TD
     Codebase["Your Codebase"]
     Indexer["Indexer<br/>12 languages<br/>Rust native or Tree-sitter fallback"]
     Graph["LadybugDB graph<br/>symbols, edges, metrics, versions"]
-    MCP["34 flat MCP tools<br/>plus optional gateway and code-mode surfaces"]
+    MCP["38 unique MCP tool surfaces<br/>flat, gateway, and code-mode"]
     CLI["13 CLI commands"]
     HTTP["HTTP API and graph UI"]
     Agent["AI coding agent<br/>Claude Code, Claude Desktop, Cursor, Windsurf, Codex, Gemini"]
@@ -109,13 +105,14 @@ flowchart TB
 
 > **Most questions are answered at Rungs 1-2** without ever reading raw code. That's where the token savings come from.
 
-| 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** |
+| 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**  |
 
 **Why it matters:**
+
 - **4–20x token savings** on typical code understanding queries
 - Most questions answered at Rungs 1–2 without ever reading raw code
 - Controlled escalation prevents agents from over-consuming context
@@ -133,7 +130,7 @@ flowchart TB
 
 ### Symbol Cards — The Atoms of Understanding
 
-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.
+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.
 
 ```mermaid
 flowchart TB
@@ -155,6 +152,7 @@ flowchart TB
 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).
 
 **Why it matters:**
+
 - **~100 tokens per symbol** vs. ~2,000 tokens to read the full file
 - Confidence-scored dependency edges trace real call relationships across files
 - Community detection and call-chain tracing reveal architectural structure
@@ -167,7 +165,7 @@ Cards include **confidence-scored call resolution** (the pass-2 resolver traces
 
 ### Graph Slicing — The Right Context for Every Task
 
-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.
+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.
 
 ```mermaid
 flowchart TD
@@ -184,6 +182,7 @@ flowchart TD
 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.
 
 **Why it matters:**
+
 - Follows the **dependency graph**, not directory boundaries, for cross-cutting context
 - Weighted edge scoring (call > config > import) prioritizes the most relevant symbols
 - Token-budgeted: returns only what fits within your budget (~800 tokens vs. ~16,000 for raw files)
@@ -195,7 +194,7 @@ Slices have handles, leases, refresh (delta-only updates), and spillover (paged
 
 ### Delta Packs & Blast Radius — Semantic Change Intelligence
 
-`git diff` tells you what lines changed. SDL-MCP tells you what that change *means* and who's affected.
+`git diff` tells you what lines changed. SDL-MCP tells you what that change _means_ and who's affected.
 
 ```mermaid
 flowchart TD
@@ -224,6 +223,7 @@ flowchart TD
 **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.
 
 **Why it matters:**
+
 - Semantic diffs show what a change **means**, not just what lines moved
 - Ranked blast radius identifies which dependent symbols are most at risk
 - Fan-in trend analysis detects "amplifier" symbols whose changes ripple further over time
@@ -235,7 +235,7 @@ flowchart TD
 
 ### 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.
+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.
 
 ```mermaid
 flowchart LR
@@ -247,6 +247,7 @@ flowchart LR
 ```
 
 **Why it matters:**
+
 - Search, cards, and slices reflect **unsaved editor changes** in real time
 - No manual re-index needed during active development
 - Background AST parsing with in-memory overlay keeps queries fast
@@ -258,6 +259,7 @@ flowchart LR
 ### 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
@@ -267,6 +269,7 @@ Requests that don't meet policy are denied with actionable guidance ("try `getHo
 The sandboxed runtime execution tool (`sdl.runtime.execute`) has its own governance layer: enabled by default, but still guarded by executable allowlisting, CWD jailing, environment scrubbing, concurrency limits, and timeout enforcement. The `outputMode` parameter (`"minimal"` | `"summary"` | `"intent"`) defaults to `"minimal"` for ~95% token savings, with `sdl.runtime.queryOutput` enabling on-demand output retrieval when needed.
 
 **Why it matters:**
+
 - Proof-of-need gating prevents agents from wastefully reading raw code
 - Denied requests include **actionable next-best-action** guidance
 - Full audit logging of every code access decision
@@ -278,13 +281,14 @@ The sandboxed runtime execution tool (`sdl.runtime.execute`) has its own governa
 
 ### Agent Context — Task-Shaped Retrieval
 
-`sdl.agent.context` is SDL-MCP's task-shaped context engine. Give it a task type (`debug`, `review`, `implement`, `explain`), a description, and a budget — it selects the right Iris Gate rungs, collects evidence, and returns context tuned to the job. In Code Mode, `sdl.context` provides the same retrieval surface without dropping into `sdl.workflow`.
+`sdl.context` is SDL-MCP's task-shaped context engine. Give it a task type (`debug`, `review`, `implement`, `explain`), a description, and a budget — it selects the right Iris Gate rungs, collects evidence, and returns context tuned to the job. In Code Mode, `sdl.context` provides the same retrieval surface without dropping into `sdl.workflow`.
 
 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.
+ generates portable, token-bounded context briefings in markdown, JSON, or clipboard format for use outside MCP environments.
 
 **Why it matters:**
+
 - Task-shaped context retrieval plans the **right Iris Gate path** within a token budget
 - Feedback loop records what was useful/missing, improving future slice quality
 - Portable context summaries export findings for use outside MCP environments
@@ -298,6 +302,7 @@ The feedback loop (`sdl.agent.feedback`) records which symbols were useful and w
 Run tests, linters, and scripts through SDL-MCP's governance layer instead of uncontrolled shell access. 16 runtimes (Node.js, Python, Go, Java, Rust, Shell, and more), code-mode or args-mode, smart output summarization with keyword-matched excerpts, and gzip artifact persistence.
 
 **Why it matters:**
+
 - Run tests, linters, and scripts **under governance** instead of uncontrolled shell access
 - 16 runtimes supported (Node, Python, Go, Java, Rust, Shell, and more)
 - Executable allowlisting, CWD jailing, timeout enforcement, and environment scrubbing
@@ -326,6 +331,7 @@ flowchart LR
 When enabled, memories are **automatically surfaced** inside graph slices — when an agent builds a slice touching symbols with linked memories, those memories appear alongside the cards. During re-indexing, memories linked to changed symbols are **flagged as stale**, prompting agents to review and update them. Four MCP tools (`store`, `query`, `remove`, `surface`) provide full CRUD plus intelligent ranking by confidence, recency, and symbol overlap. Memory tools are only available when memory is enabled in the configuration.
 
 **Why it matters:**
+
 - Structured knowledge **persists across sessions**, linked directly to symbols and files
 - Opt-in and disabled by default — enable via `"memory": { "enabled": true }` in config
 - When enabled, automatically surfaced inside graph slices when touching related symbols
@@ -336,6 +342,31 @@ When enabled, memories are **automatically surfaced** inside graph slices — wh
 
 ---
 
+### SCIP Integration — Compiler-Grade Cross-References
+
+Tree-sitter gives SDL-MCP fast, syntax-level symbol extraction across 11 languages. SCIP (Source Code Intelligence Protocol) supplements this with **compiler-grade cross-references** from tools like scip-typescript, scip-go, and rust-analyzer. Generate a `.scip` index file, point SDL-MCP at it, and heuristic edges are upgraded to exact compiler-verified edges, external dependency symbols become first-class graph nodes, and new `implements` edges reveal interface/trait relationships that syntax analysis cannot discover.
+
+```mermaid
+flowchart LR
+    Compiler["Compiler / Type Checker"] --> SCIP[".scip index file"]
+    SCIP --> Ingest["sdl.scip.ingest"]
+    Ingest --> Upgrade["Heuristic edges → exact edges"]
+    Ingest --> External["External dependency nodes"]
+    Ingest --> Implements["implements edges"]
+```
+
+**Why it matters:**
+
+- Upgrades heuristic call resolution to **compiler-verified exact edges** (confidence 0.95)
+- External dependencies (npm packages, Go modules, crate deps) become searchable graph nodes
+- Interface/trait implementations tracked via `implements` edges
+- Auto-ingest on `sdl.index.refresh` keeps SCIP data current with zero manual steps
+- Complementary: tree-sitter provides structure, SCIP provides semantic precision
+
+[SCIP Integration Deep Dive →](./docs/feature-deep-dives/scip-integration.md)
+
+---
+
 ### CLI Tool Access — No MCP Server Required
 
 Access all 32 flat SDL action tools directly from the command line with `sdl-mcp tool`. No MCP server, transport, or SDK is required.
@@ -354,6 +385,7 @@ echo '{"repoId":"my-repo"}' | sdl-mcp tool symbol.search --query "auth"
 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.
 
 **Why it matters:**
+
 - All MCP tool actions accessible from **any terminal** — no server, transport, or SDK required
 - Same code paths and Zod validation as the MCP server — identical behavior
 - Four output formats (json, json-compact, pretty, table) for scripting and CI pipelines
@@ -376,6 +408,7 @@ flowchart LR
 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.
 
 **Why it matters:**
+
 - Large reduction in `tools/list` overhead for gateway-first agents
 - 32 flat action tools consolidated into 4 namespace-scoped tools for simpler agent selection
 - Fewer tool choices means faster and more accurate tool dispatch by the agent
@@ -389,7 +422,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 
 <br/>
 
-## All 36 Unique Tool Surfaces at a Glance
+## All 38 Unique Tool Surfaces at a Glance
 
 <table>
 <tr><th>Category</th><th>Tool</th><th>One-Line Description</th></tr>
@@ -407,7 +440,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 <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><code>sdl.symbol.getCard</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>
@@ -430,10 +463,10 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
     <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) with conditional ETag fetch support</td></tr>
+    <td><code></code></td><td>Token-bounded portable briefing (markdown/JSON/clipboard) with conditional ETag fetch support</td></tr>
 
 <tr><td rowspan="3"><strong>Agent</strong></td>
-    <td><code>sdl.agent.context</code></td><td>Task-shaped context retrieval with budget-controlled rung planning and conditional ETag fetch support</td></tr>
+    <td><code>sdl.context</code></td><td>Task-shaped context retrieval with budget-controlled rung planning and conditional ETag fetch support</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>
 
@@ -452,6 +485,12 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 <tr><td><code>sdl.workflow</code></td><td>Multi-step operations with budget tracking, ETag caching, and transforms</td></tr>
 <tr><td><code>sdl.manual</code></td><td>Self-documentation — query usage guide, action schemas, output format reference</td></tr>
 
+<tr><td><strong>SCIP</strong></td>
+    <td><code>sdl.scip.ingest</code></td><td>Ingest a pre-built SCIP index for compiler-grade cross-references (with dry-run support)</td></tr>
+
+<tr><td><strong>File</strong></td>
+    <td><code>sdl.file.read</code></td><td>Read non-indexed files (configs, docs, templates) with line-range, search, or JSON-path modes</td></tr>
+
 <tr><td rowspan="3"><strong>Meta</strong></td>
     <td><code>sdl.info</code></td><td>Runtime diagnostics — version, Node.js, platform, database, config paths</td></tr>
 <tr><td><code>sdl.usage.stats</code></td><td>Session and lifetime token savings statistics</td></tr>
@@ -468,21 +507,21 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 
 ## CLI Commands
 
-| 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 35 MCP tool actions directly ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
-| `sdl-mcp info` | Runtime diagnostics — version, Node.js, platform, database, config |
-| `sdl-mcp summary` | Generate copy/paste context summaries from the CLI |
-| `sdl-mcp health` | Compute composite health score with badge/JSON output |
-| `sdl-mcp benchmark` | Run CI regression benchmarks |
-| `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 |
+| 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 35 MCP tool actions directly ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
+| `sdl-mcp info`      | Runtime diagnostics — version, Node.js, platform, database, config                             |
+| `sdl-mcp summary`   | Generate copy/paste context summaries from the CLI                                             |
+| `sdl-mcp health`    | Compute composite health score with badge/JSON output                                          |
+| `sdl-mcp benchmark` | Run CI regression benchmarks                                                                   |
+| `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                                                              |
 
 [CLI Reference →](./docs/cli-reference.md) · [Configuration Reference →](./docs/configuration-reference.md)
 
@@ -496,15 +535,15 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 
 SDL-MCP works with any MCP-compatible client:
 
-| 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` |
+| 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` |
 
 A **VSCode extension** (`sdl-mcp-vscode/`) provides live buffer integration for real-time indexing of unsaved edits.
@@ -517,15 +556,15 @@ A **VSCode extension** (`sdl-mcp-vscode/`) provides live buffer integration for
 
 ## Tech Stack
 
-| Component | Technology |
-|:----------|:-----------|
-| Runtime | Node.js 24+ / 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) |
+| Component          | Technology                                 |
+| :----------------- | :----------------------------------------- |
+| Runtime            | Node.js 24+ / 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/>
 
@@ -562,37 +601,38 @@ flowchart TD
 
 ## 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 36 unique tool surfaces (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/feature-deep-dives/iris-gate-ladder.md) | Context escalation methodology |
-| [Troubleshooting](./docs/troubleshooting.md) | Common issues and fixes |
+| 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 37 unique tool surfaces (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/feature-deep-dives/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 Context](./docs/feature-deep-dives/agent-context.md) | Task-shaped context retrieval, feedback loops, portable context summaries |
-| [Context Modes](./docs/feature-deep-dives/context-modes.md) | Precise vs broad retrieval, adaptive symbol ranking, benchmark trade-offs |
-| [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 tool actions, output formats, stdin piping, scripting |
-| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md) | 35→4 tool consolidation, 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 |
-| [Code Mode](./docs/feature-deep-dives/code-mode.md) | `sdl.context`, `sdl.workflow`, action discovery, manual reference, one-call workflows |
-| [Development Memories](./docs/feature-deep-dives/development-memories.md) | Graph-backed cross-session memory, file sync, staleness detection, auto-surfacing |
-| [Token Savings Meter](./docs/feature-deep-dives/token-savings-meter.md) | Per-call meter, session summaries, lifetime tracking, `sdl.usage.stats` |
+| 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 Context](./docs/feature-deep-dives/agent-context.md)                         | Task-shaped context retrieval, feedback loops, portable context summaries             |
+| [Context Modes](./docs/feature-deep-dives/context-modes.md)                         | Precise vs broad retrieval, adaptive symbol ranking, benchmark trade-offs             |
+| [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 tool actions, output formats, stdin piping, scripting        |
+| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md)                           | 35→4 tool consolidation, 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          |
+| [Code Mode](./docs/feature-deep-dives/code-mode.md)                                 | `sdl.context`, `sdl.workflow`, action discovery, manual reference, one-call workflows |
+| [Development Memories](./docs/feature-deep-dives/development-memories.md)           | Graph-backed cross-session memory, file sync, staleness detection, auto-surfacing     |
+| [SCIP Integration](./docs/feature-deep-dives/scip-integration.md)                   | Compiler-grade cross-references, external deps, implements edges, auto-ingest         |
+| [Token Savings Meter](./docs/feature-deep-dives/token-savings-meter.md)             | Per-call meter, session summaries, lifetime tracking, `sdl.usage.stats`               |
 
 <br/>
 

package/config/sdlmcp.config.example.json

@@ -102,7 +102,7 @@
   "semantic": {
     "enabled": true,
     "provider": "local",
-    "model": "all-MiniLM-L6-v2",
+    "model": "jina-embeddings-v2-base-code",
     "modelCacheDir": null,
     "generateSummaries": false,
     "summaryProvider": null,
@@ -123,10 +123,11 @@
       "vector": {
         "enabled": true,
         "topK": 75,
+        "efc": 200,
         "efs": 200,
         "indexes": {
-          "all-MiniLM-L6-v2": {
-            "indexName": "symbol_vec_minilm_l6_v2"
+          "jina-embeddings-v2-base-code": {
+            "indexName": "symbol_vec_jina_code_v2"
           },
           "nomic-embed-text-v1.5": {
             "indexName": "symbol_vec_nomic_embed_v15"
@@ -166,12 +167,7 @@
   },
   "runtime": {
     "enabled": true,
-    "allowedRuntimes": [
-      "node",
-      "typescript",
-      "python",
-      "shell"
-    ],
+    "allowedRuntimes": ["node", "typescript", "python", "shell"],
     "allowedExecutables": [],
     "maxDurationMs": 30000,
     "maxStdoutBytes": 1048576,
@@ -202,6 +198,28 @@
   "security": {
     "allowedRepoRoots": []
   },
+  "scip": {
+    "enabled": false,
+    "indexes": [
+      {
+        "path": "index.scip",
+        "label": "typescript"
+      }
+    ],
+    "externalSymbols": {
+      "enabled": true,
+      "maxPerIndex": 10000
+    },
+    "confidence": 0.95,
+    "autoIngestOnRefresh": true,
+    "generator": {
+      "enabled": false,
+      "binary": "scip-io",
+      "args": [],
+      "autoInstall": true,
+      "timeoutMs": 600000
+    }
+  },
   "memory": {
     "enabled": false
   }

package/config/sdlmcp.config.json

@@ -42,11 +42,7 @@
         "**/*.test.ts",
         "**/*.spec.ts"
       ],
-      "languages": [
-        "ts",
-        "tsx",
-        "js"
-      ]
+      "languages": ["ts", "tsx", "js"]
     },
     {
       "repoId": "preact-oss",
@@ -61,12 +57,7 @@
         "**/*.test.tsx",
         "**/*.spec.tsx"
       ],
-      "languages": [
-        "ts",
-        "tsx",
-        "js",
-        "jsx"
-      ]
+      "languages": ["ts", "tsx", "js", "jsx"]
     },
     {
       "repoId": "flask-oss",
@@ -81,9 +72,7 @@
         "**/*.pyc",
         "**/tests/**"
       ],
-      "languages": [
-        "py"
-      ]
+      "languages": ["py"]
     },
     {
       "repoId": "ansible-lint-oss",
@@ -100,10 +89,7 @@
         "**/tests/**",
         "**/.tox/**"
       ],
-      "languages": [
-        "py",
-        "sh"
-      ]
+      "languages": ["py", "sh"]
     }
   ],
   "graphDatabase": {
@@ -145,7 +131,7 @@
     "enabled": true,
     "alpha": 0.6,
     "provider": "mock",
-    "model": "all-MiniLM-L6-v2",
+    "model": "jina-embeddings-v2-base-code",
     "generateSummaries": false
   },
   "prefetch": {