sdl-mcp 0.10.2 → 0.10.4

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,10 +152,12 @@ 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
 - ETag-based conditional requests avoid re-fetching unchanged symbols
+- Workflow ETag caching now seeds `slice.build` with `knownCardEtags` so repeated slice builds can skip unchanged cards
 
 [Indexing & Language Support Deep Dive →](./docs/feature-deep-dives/indexing-languages.md)
 
@@ -166,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
@@ -183,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)
@@ -194,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
@@ -223,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
@@ -234,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
@@ -246,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
@@ -257,15 +259,17 @@ 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
 
 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. The `outputMode` parameter (`"minimal"` | `"summary"` | `"intent"`) defaults to `"minimal"` for ~95% token savings, with `sdl.runtime.queryOutput` enabling on-demand output retrieval when needed.
+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
@@ -284,6 +288,7 @@ The feedback loop (`sdl.agent.feedback`) records which symbols were useful and w
 `sdl.context.summary` 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
@@ -297,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
@@ -306,9 +312,9 @@ Run tests, linters, and scripts through SDL-MCP's governance layer instead of un
 
 ---
 
-### Development Memories — Cross-Session Knowledge Persistence
+### Development Memories — Cross-Session Knowledge Persistence (Opt-In)
 
-Agents forget everything between sessions. SDL-MCP fixes this with a **graph-backed memory system** that lets agents store decisions, bugfix context, and task notes linked directly to the symbols and files they relate to. Memories are stored both in the graph database (for fast querying) and as checked-in markdown files (for version control and team sharing).
+Agents forget everything between sessions. SDL-MCP fixes this with an **opt-in graph-backed memory system** that lets agents store decisions, bugfix context, and task notes linked directly to the symbols and files they relate to. Memory is **disabled by default** and must be explicitly enabled in the configuration. When enabled, memories are stored both in the graph database (for fast querying) and as checked-in markdown files (for version control and team sharing).
 
 ```mermaid
 flowchart LR
@@ -322,11 +328,13 @@ flowchart LR
     Graph --> Recall["Relevant memory surfaced<br/>race condition fix in authenticate()"]
 ```
 
-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.
+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
-- Automatically surfaced inside graph slices when touching related symbols
+- Opt-in and disabled by default — enable via `"memory": { "enabled": true }` in config
+- When enabled, automatically surfaced inside graph slices when touching related symbols
 - Stale memories flagged when linked symbols change during re-indexing
 - Dual storage: graph DB for fast querying + markdown files for version control and team sharing
 
@@ -334,6 +342,31 @@ Memories are **automatically surfaced** inside graph slices — when an agent bu
 
 ---
 
+### 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.
@@ -352,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
@@ -374,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
@@ -387,14 +422,14 @@ 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>
 <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.repo.overview</code></td><td>Codebase summary: stats, directories, hotspots, clusters, with conditional ETag fetch support</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>
@@ -413,8 +448,8 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 <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>
+    <td><code>sdl.code.getSkeleton</code></td><td>Signatures + control flow, bodies elided, with conditional ETag fetch support</td></tr>
+<tr><td><code>sdl.code.getHotPath</code></td><td>Lines matching specific identifiers + context, with conditional ETag fetch support</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>
@@ -428,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)</td></tr>
+    <td><code>sdl.context.summary</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</td></tr>
+    <td><code>sdl.agent.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>
 
@@ -450,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>
@@ -466,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)
 
@@ -494,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.
@@ -515,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/>
 
@@ -560,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

@@ -32,7 +32,12 @@
       "includeNodeModulesTypes": true,
       "packageJsonPath": null,
       "tsconfigPath": null,
-      "workspaceGlobs": null
+      "workspaceGlobs": null,
+      "memory": {
+        "enabled": true,
+        "surfacingEnabled": true,
+        "fileSyncEnabled": false
+      }
     }
   ],
   "graphDatabase": {
@@ -118,7 +123,8 @@
       "vector": {
         "enabled": true,
         "topK": 75,
-        "efs": 200,
+        "efc": 200,
+              "efs": 200,
         "indexes": {
           "all-MiniLM-L6-v2": {
             "indexName": "symbol_vec_minilm_l6_v2"
@@ -160,11 +166,8 @@
     "toolQueueTimeoutMs": 30000
   },
   "runtime": {
-    "enabled": false,
-    "allowedRuntimes": [
-      "node",
-      "python"
-    ],
+    "enabled": true,
+    "allowedRuntimes": ["node", "typescript", "python", "shell"],
     "allowedExecutables": [],
     "maxDurationMs": 30000,
     "maxStdoutBytes": 1048576,
@@ -194,5 +197,30 @@
   },
   "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
   }
 }