sdl-mcp 0.11.3 → 0.11.5

package/README.md

@@ -502,7 +502,7 @@ Features include typed argument coercion (string, number, boolean, string[], jso
 
 **Why it matters:**
 
-- 35 direct graph/action aliases plus `action.search` and `manual` metadata proxies accessible from **any terminal** - no server, transport, or SDK required
+- 36 direct graph/action aliases plus `action.search` and `manual` metadata proxies accessible from **any terminal** - no server, transport, or SDK required
 - Direct graph actions keep gateway-router/Zod parity; metadata proxies share the same MCP registration handlers
 - Four output formats (json, json-compact, pretty, table) for scripting and CI pipelines
 - Auto-resolves repoId from cwd, supports stdin JSON piping and per-action `--help`
@@ -513,12 +513,12 @@ Features include typed argument coercion (string, number, boolean, string[], jso
 
 ### Tool Gateway — Compact Tool Registration
 
-The tool gateway projects the 34 gateway-routable SDL actions into **4 namespace-scoped tools** (`sdl.query`, `sdl.code`, `sdl.repo`, `sdl.agent`), reducing `tools/list` overhead from the full flat schema surface to a compact gateway surface.
+The tool gateway projects the 35 gateway-routable SDL actions into **4 namespace-scoped tools** (`sdl.query`, `sdl.code`, `sdl.repo`, `sdl.agent`), reducing `tools/list` overhead from the full flat schema surface to a compact gateway surface.
 
 ```mermaid
 %%{init: {"theme":"base","themeVariables":{"background":"#ffffff","primaryColor":"#E7F8F2","primaryBorderColor":"#0F766E","primaryTextColor":"#102A43","secondaryColor":"#E8F1FF","secondaryBorderColor":"#2563EB","secondaryTextColor":"#102A43","tertiaryColor":"#FFF4D6","tertiaryBorderColor":"#B45309","tertiaryTextColor":"#102A43","lineColor":"#0F766E","textColor":"#102A43","fontFamily":"Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"},"flowchart":{"curve":"basis","htmlLabels":true}}}%%
 flowchart LR
-    Before["Flat mode<br/>37 tools<br/>2 universal + 35 flat"] e1@--> After["Gateway mode<br/>6 tools<br/>2 universal + 4 gateway"]
+    Before["Flat mode<br/>38 tools<br/>2 universal + 36 flat"] e1@--> After["Gateway mode<br/>6 tools<br/>2 universal + 4 gateway"]
     After e2@--> Savings["Smaller tools/list payload<br/>lower agent startup overhead"]
 
     classDef source fill:#E7F8F2,stroke:#0F766E,stroke-width:2px,color:#102A43;
@@ -536,7 +536,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 **Why it matters:**
 
 - Large reduction in `tools/list` overhead for gateway-first agents
-- 34 gateway-routable actions consolidated into 4 namespace-scoped tools for simpler agent selection
+- 35 gateway-routable actions consolidated into 4 namespace-scoped tools for simpler agent selection
 - Fewer tool choices means faster and more accurate tool dispatch by the agent
 - Choose Code Mode for task-shaped retrieval first; opt out of exclusive Code Mode when you also need regular flat or gateway tools
 
@@ -546,7 +546,7 @@ Each gateway tool accepts an `action` discriminator field (e.g., `{ action: "sym
 
 ### Observability Dashboard
 
-Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP behaviour without parsing stderr logs. GlitterKill dark UI at `/ui/observability` on the HTTP transport or the loopback-only `sdl-mcp serve --stdio --dashboard-port <port>` sidecar, plus REST + SSE APIs (`/api/observability/snapshot`, `/timeseries`, `/beam-explain`, `/stream`) for programmatic access. Surfaces cache hit rates, hybrid-retrieval breakdowns (FTS / vector / PPR / RRF), beam-search decision traces, indexing pipeline metrics, write-pool and drain saturation, packed-wire token efficiency, and runtime CPU/memory/event-loop probes. See [Observability Dashboard Deep Dive](./docs/feature-deep-dives/observability-dashboard.md).
+Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP behaviour without parsing stderr logs. GlitterKill dark UI at `/ui/observability` on the HTTP transport or the loopback-only `sdl-mcp serve --stdio --dashboard-port <port>` sidecar, plus REST + SSE APIs (`/api/observability/snapshot`, `/timeseries`, `/beam-explain`, `/stream`) for programmatic access. Surfaces cache hit rates, predictive-context outcome learning, hybrid-retrieval breakdowns (FTS / vector / PPR / RRF), beam-search decision traces, indexing pipeline metrics, write-pool and drain saturation, packed-wire token efficiency, and runtime CPU/memory/event-loop probes. See [Observability Dashboard Deep Dive](./docs/feature-deep-dives/observability-dashboard.md).
 
 <br/>
 
@@ -558,9 +558,9 @@ Built-in read-only dashboard surfaces every metric needed to diagnose SDL-MCP be
 
 | Mode                | Tool count | Composition                                                      |
 | :------------------ | :--------- | :--------------------------------------------------------------- |
-| Flat                | `37`       | `2` universal + `35` flat tools                                  |
+| Flat                | `38`       | `2` universal + `36` flat tools                                  |
 | Gateway             | `6`        | `2` universal + `4` gateway tools                                |
-| Gateway + legacy    | `41`       | `2` universal + `4` gateway + `35` flat tools                    |
+| Gateway + legacy    | `42`       | `2` universal + `4` gateway + `36` flat tools                    |
 | Code Mode exclusive | `5`        | `sdl.action.search`, `sdl.context`, `sdl.file`, `sdl.manual`, `sdl.workflow` |
 
 The generated source of truth is [`docs/generated/tool-inventory.md`](./docs/generated/tool-inventory.md).
@@ -578,9 +578,10 @@ The generated source of truth is [`docs/generated/tool-inventory.md`](./docs/gen
 <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="2"><strong>Symbols</strong></td>
+<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 one card or batch-fetch up to 100 cards with ETag-based conditional support</td></tr>
+<tr><td><code>sdl.symbol.edit</code></td><td>Preview/apply one symbol-scoped edit with AST, range, file, and draft preconditions</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>
@@ -650,7 +651,7 @@ The generated source of truth is [`docs/generated/tool-inventory.md`](./docs/gen
 | `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 35 direct action aliases ([docs](./docs/feature-deep-dives/cli-tool-access.md)) |
+| `sdl-mcp tool`      | Access 36 direct action aliases ([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                                  |
@@ -771,9 +772,10 @@ flowchart TD
 | [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                           |
+| [Provider-First Indexing](./docs/feature-deep-dives/provider-first-indexing.md)     | SCIP/LSP-first planning, provider facts, shadow DB readiness, fallback boundaries     |
 | [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 35 action aliases, output formats, stdin piping, scripting       |
-| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md)                           | 34 gateway-routable actions, 4 namespace tools, thin schemas, migration guide         |
+| [CLI Tool Access](./docs/feature-deep-dives/cli-tool-access.md)                     | Direct CLI access to 36 action aliases, output formats, stdin piping, scripting       |
+| [Tool Gateway](./docs/feature-deep-dives/tool-gateway.md)                           | 35 gateway-routable actions, 4 namespace tools, 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 |

package/config/sdlmcp.config.example.json

@@ -9,7 +9,12 @@
         "**/dist/**",
         "**/dist-*/**",
         "**/build/**",
+        "**/build-*/**",
+        "**/build_*/**",
+        "**/cmake-build-*/**",
         "**/out/**",
+        "**/out-*/**",
+        "**/out_*/**",
         "**/target/**",
         "**/coverage/**",
         "**/node_modules/**",
@@ -40,6 +45,7 @@
         "sh"
       ],
       "maxFileBytes": 2000000,
+      "sourceFileListPath": null,
       "postIndexSessionTimeoutMs": 900000,
       "includeNodeModulesTypes": true,
       "packageJsonPath": null,
@@ -69,13 +75,38 @@
     "patterns": []
   },
   "indexing": {
+    "pipeline": "auto",
+    "providerFirst": {
+      "activation": "shadowDb",
+      "readyState": "graphPlusAlgorithms",
+      "stagingFormat": "parquet",
+      "maxLegacyFallbackFiles": 1000000,
+      "maxSemanticEligibleFallbackFiles": 0,
+      "lsp": {
+        "mode": "primaryWithCaps",
+        "workspaceSymbolLimit": 5000,
+        "documentSymbolFileLimit": 500,
+        "referenceCandidateLimit": 200,
+        "diagnosticsLimit": 5000
+      }
+    },
     "concurrency": 8,
     "enableFileWatching": true,
     "maxWatchedFiles": 25000,
     "workerPoolSize": null,
     "engine": "rust",
     "watchDebounceMs": 300,
-    "pass2Concurrency": 1
+    "pass2Concurrency": 1,
+    "algorithmRefresh": {
+      "enabled": true,
+      "pageRank": { "enabled": true },
+      "kCore": { "enabled": true },
+      "louvain": {
+        "enabled": true,
+        "maxCallEdges": 10000
+      },
+      "workerTimeoutMs": 120000
+    }
   },
   "liveIndex": {
     "enabled": true,
@@ -111,13 +142,15 @@
   "plugins": {
     "paths": [],
     "enabled": true,
-    "strictVersioning": true
+    "strictVersioning": true,
+    "trustedRoots": []
   },
   "semantic": {
     "enabled": true,
     "provider": "local",
-    "model": "jina-embeddings-v2-base-code",
-    "additionalModels": ["nomic-embed-text-v1.5"],
+    "embeddingProfile": "specialized",
+    "symbolEmbeddingModels": ["jina-embeddings-v2-base-code"],
+    "fileSummaryEmbeddingModels": ["nomic-embed-text-v1.5"],
     "modelCacheDir": null,
     "generateSummaries": false,
     "summaryProvider": null,
@@ -187,7 +220,17 @@
   "prefetch": {
     "enabled": true,
     "maxBudgetPercent": 20,
-    "warmTopN": 0
+    "warmTopN": 0,
+    "policy": {
+      "enabled": true,
+      "mode": "safe",
+      "minSamples": 20,
+      "suppressionWasteRate": 0.8,
+      "boostHitRate": 0.35,
+      "retentionDays": 14,
+      "maxPriorityBoost": 25,
+      "maxBudgetTrimPercent": 50
+    }
   },
   "tracing": {
     "enabled": true,
@@ -285,10 +328,16 @@
       "args": [],
       "autoInstall": true,
       "timeoutMs": 600000,
-      "cleanupAfterIngest": true
+      "cleanupAfterIngest": true,
+      "cacheGeneratedIndexes": true
     }
   },
   "memory": {
     "enabled": false
+  },
+  "$": {
+    "prefetch": {
+      "policy": "{\"enabled\":true,\"mode\":\"safe\",\"minSamples\":20,\"suppressionWasteRate\":0.8,\"boostHitRate\":0.35,\"retentionDays\":14,\"maxPriorityBoost\":25,\"maxBudgetTrimPercent\":50}"
+    }
   }
 }

package/config/sdlmcp.config.json

@@ -145,8 +145,9 @@
     "provider": "mock",
     "executionProviders": ["cpu"],
     "modelVariant": "default",
-    "model": "jina-embeddings-v2-base-code",
-    "additionalModels": ["nomic-embed-text-v1.5"],
+    "embeddingProfile": "specialized",
+    "symbolEmbeddingModels": ["jina-embeddings-v2-base-code"],
+    "fileSummaryEmbeddingModels": ["nomic-embed-text-v1.5"],
     "generateSummaries": false
   },
   "prefetch": {

package/config/sdlmcp.config.schema.json

@@ -33,7 +33,12 @@
               "**/dist/**",
               "**/dist-*/**",
               "**/build/**",
+              "**/build-*/**",
+              "**/build_*/**",
+              "**/cmake-build-*/**",
               "**/out/**",
+              "**/out-*/**",
+              "**/out_*/**",
               "**/target/**",
               "**/coverage/**",
               "**/node_modules/**",
@@ -91,6 +96,10 @@
             "minimum": 1,
             "default": 2000000
           },
+          "sourceFileListPath": {
+            "type": ["string", "null"],
+            "description": "Optional benchmark/tuning file list. When set, repository scanning uses these repo-relative source paths instead of walking the full tree."
+          },
           "postIndexSessionTimeoutMs": {
             "type": "integer",
             "description": "Hard timeout for post-index finalization writes in milliseconds. Covers embeddings, summaries, deferred index builds, memory sync, and audit flushing after pass-1/pass-2 complete.",
@@ -261,6 +270,104 @@
       "type": "object",
       "description": "Indexing behavior configuration",
       "properties": {
+        "pipeline": {
+          "type": "string",
+          "description": "Indexing pipeline selector. auto uses provider-first when SCIP or LSP coverage is configured, otherwise legacy.",
+          "enum": ["legacy", "providerFirst", "auto"],
+          "default": "auto"
+        },
+        "providerFirst": {
+          "type": "object",
+          "description": "Provider-first indexing options for SCIP/LSP-backed graph facts and shadow database activation.",
+          "properties": {
+            "activation": {
+              "type": "string",
+              "description": "Activation strategy for full provider-first builds.",
+              "enum": ["shadowDb"],
+              "default": "shadowDb"
+            },
+            "readyState": {
+              "type": "string",
+              "description": "Readiness gate for the first usable index state.",
+              "enum": ["graphPlusAlgorithms"],
+              "default": "graphPlusAlgorithms"
+            },
+            "stagingFormat": {
+              "type": "string",
+              "description": "Preferred provider fact staging format for shadow bulk loads. CSV is the fallback when Parquet is unavailable.",
+              "enum": ["parquet", "csv"],
+              "default": "parquet"
+            },
+            "maxLegacyFallbackFiles": {
+              "type": "integer",
+              "description": "Emergency cap for uncovered or provider-unusable files parsed by same-run legacy fallback after provider-first materialization. Defaults high so full provider-first runs build a complete graph; lower it only for partial iteration or resource protection.",
+              "minimum": 0,
+              "maximum": 1000000,
+              "default": 1000000
+            },
+            "maxSemanticEligibleFallbackFiles": {
+              "type": "integer",
+              "description": "Maximum semantic-eligible uncovered or provider-unusable files parsed when the full provider-first fallback gap exceeds maxLegacyFallbackFiles. The default of 0 avoids a misleading partial semantic subset when the main fallback cap was intentionally lowered or exceeded.",
+              "minimum": 0,
+              "maximum": 1000000,
+              "default": 0
+            },
+            "lsp": {
+              "type": "object",
+              "description": "Caps for primary LSP provider collection. LSP servers are consumed from configured commands; SDL-MCP does not install them.",
+              "properties": {
+                "mode": {
+                  "type": "string",
+                  "enum": ["primaryWithCaps"],
+                  "default": "primaryWithCaps"
+                },
+                "workspaceSymbolLimit": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 100000,
+                  "default": 5000
+                },
+                "documentSymbolFileLimit": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 50000,
+                  "default": 500
+                },
+                "referenceCandidateLimit": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 10000,
+                  "default": 200
+                },
+                "diagnosticsLimit": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 100000,
+                  "default": 5000
+                }
+              },
+              "default": {
+                "mode": "primaryWithCaps",
+                "workspaceSymbolLimit": 5000,
+                "documentSymbolFileLimit": 500,
+                "referenceCandidateLimit": 200,
+                "diagnosticsLimit": 5000
+              }
+            }
+          },
+          "default": {
+            "activation": "shadowDb",
+            "readyState": "graphPlusAlgorithms",
+            "stagingFormat": "parquet",
+            "lsp": {
+              "mode": "primaryWithCaps",
+              "workspaceSymbolLimit": 5000,
+              "documentSymbolFileLimit": 500,
+              "referenceCandidateLimit": 200,
+              "diagnosticsLimit": 5000
+            }
+          }
+        },
         "concurrency": {
           "type": "integer",
           "description": "Number of concurrent indexing workers",
@@ -304,15 +411,86 @@
           "minimum": 1,
           "maximum": 16,
           "default": 1
+        },
+        "algorithmRefresh": {
+          "type": "object",
+          "description": "Optional post-index graph algorithm refresh. Canonical clusters/processes always run; PageRank/K-core use a bounded worker and Louvain is skipped above maxCallEdges.",
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "default": true
+            },
+            "pageRank": {
+              "type": "object",
+              "properties": {
+                "enabled": { "type": "boolean", "default": true }
+              },
+              "default": { "enabled": true }
+            },
+            "kCore": {
+              "type": "object",
+              "properties": {
+                "enabled": { "type": "boolean", "default": true }
+              },
+              "default": { "enabled": true }
+            },
+            "louvain": {
+              "type": "object",
+              "properties": {
+                "enabled": { "type": "boolean", "default": true },
+                "maxCallEdges": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "default": 10000
+                }
+              },
+              "default": { "enabled": true, "maxCallEdges": 10000 }
+            },
+            "workerTimeoutMs": {
+              "type": "integer",
+              "minimum": 1000,
+              "maximum": 1800000,
+              "default": 120000
+            }
+          },
+          "default": {
+            "enabled": true,
+            "pageRank": { "enabled": true },
+            "kCore": { "enabled": true },
+            "louvain": { "enabled": true, "maxCallEdges": 10000 },
+            "workerTimeoutMs": 120000
+          }
         }
       },
       "default": {
+        "pipeline": "auto",
+        "providerFirst": {
+          "activation": "shadowDb",
+          "readyState": "graphPlusAlgorithms",
+          "stagingFormat": "parquet",
+          "maxLegacyFallbackFiles": 1000000,
+          "maxSemanticEligibleFallbackFiles": 0,
+          "lsp": {
+            "mode": "primaryWithCaps",
+            "workspaceSymbolLimit": 5000,
+            "documentSymbolFileLimit": 500,
+            "referenceCandidateLimit": 200,
+            "diagnosticsLimit": 5000
+          }
+        },
         "concurrency": 8,
         "enableFileWatching": true,
         "maxWatchedFiles": 25000,
         "engine": "rust",
         "watchDebounceMs": 300,
-        "pass2Concurrency": 1
+        "pass2Concurrency": 1,
+        "algorithmRefresh": {
+          "enabled": true,
+          "pageRank": { "enabled": true },
+          "kCore": { "enabled": true },
+          "louvain": { "enabled": true, "maxCallEdges": 10000 },
+          "workerTimeoutMs": 120000
+        }
       }
     },
     "liveIndex": {
@@ -530,12 +708,21 @@
           "type": "boolean",
           "description": "Require plugin API version compatibility",
           "default": true
+        },
+        "trustedRoots": {
+          "type": "array",
+          "description": "Trusted plugin directories. Relative roots resolve from the config file directory; plugin entrypoints must resolve inside one root after symlinks are resolved.",
+          "items": {
+            "type": "string"
+          },
+          "default": []
         }
       },
       "default": {
         "paths": [],
         "enabled": true,
-        "strictVersioning": true
+        "strictVersioning": true,
+        "trustedRoots": []
       }
     },
     "semantic": {
@@ -552,20 +739,36 @@
           "enum": ["api", "local", "mock"],
           "default": "local"
         },
+        "embeddingProfile": {
+          "type": "string",
+          "enum": ["specialized", "max-recall"],
+          "default": "specialized",
+          "description": "Semantic embedding model profile. 'specialized' embeds Symbols with Jina and FileSummary nodes with Nomic. 'max-recall' restores both supported models on both lanes."
+        },
+        "symbolEmbeddingModels": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["jina-embeddings-v2-base-code"],
+          "description": "Embedding models to populate for Symbol nodes. Overrides embeddingProfile for the Symbol lane when set."
+        },
+        "fileSummaryEmbeddingModels": {
+          "type": "array",
+          "items": { "type": "string" },
+          "default": ["nomic-embed-text-v1.5"],
+          "description": "Embedding models to populate for FileSummary nodes. Overrides embeddingProfile for the FileSummary lane when set."
+        },
         "model": {
           "type": "string",
-          "enum": ["jina-embeddings-v2-base-code", "nomic-embed-text-v1.5"],
-          "default": "jina-embeddings-v2-base-code"
+          "description": "Deprecated legacy primary embedding model. When no embeddingProfile or per-lane model arrays are configured, model plus additionalModels are treated as one shared model list for both Symbol and FileSummary embeddings."
         },
         "additionalModels": {
           "type": "array",
           "items": { "type": "string" },
-          "default": ["nomic-embed-text-v1.5"],
-          "description": "Extra embedding models to populate at index time so multiple vector lanes can contribute to hybrid fusion. Primary `model` is always populated; each name listed here gets a separate pass. Unknown model names are skipped."
+          "description": "Deprecated legacy shared extra embedding models. Use embeddingProfile, symbolEmbeddingModels, or fileSummaryEmbeddingModels instead."
         },
         "modelCacheDir": {
           "type": "string",
-          "description": "Override directory for downloaded model files (nomic-embed-text-v1.5). Defaults to platform-specific cache."
+          "description": "Override directory for downloaded local embedding model files. Defaults to the platform-specific SDL-MCP model cache."
         },
         "generateSummaries": {
           "type": "boolean",
@@ -830,7 +1033,9 @@
       "default": {
         "enabled": true,
         "provider": "local",
-        "model": "jina-embeddings-v2-base-code",
+        "embeddingProfile": "specialized",
+        "symbolEmbeddingModels": ["jina-embeddings-v2-base-code"],
+        "fileSummaryEmbeddingModels": ["nomic-embed-text-v1.5"],
         "generateSummaries": false,
         "summaryModel": "claude-haiku-4-5-20251001",
         "summaryMaxConcurrency": 5,
@@ -996,12 +1201,67 @@
           "minimum": 0,
           "default": 0,
           "description": "Number of top-fan-in symbols to prefetch on serve start. Default 0 disables startup warming; raise only when you have evidence the warm set is consumed within the 5-minute stale window."
+        },
+        "policy": {
+          "type": "object",
+          "description": "Outcome-trained predictive context policy. Safe mode can suppress, trim, or boost existing prefetch strategies but cannot invent new strategy types.",
+          "additionalProperties": false,
+          "properties": {
+            "enabled": { "type": "boolean", "default": true },
+            "mode": { "enum": ["observe", "safe"], "default": "safe" },
+            "minSamples": { "type": "integer", "minimum": 1, "default": 20 },
+            "suppressionWasteRate": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.8
+            },
+            "boostHitRate": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 1,
+              "default": 0.35
+            },
+            "retentionDays": { "type": "integer", "minimum": 1, "default": 14 },
+            "maxPriorityBoost": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100,
+              "default": 25
+            },
+            "maxBudgetTrimPercent": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 100,
+              "default": 50
+            }
+          },
+          "default": {
+            "enabled": true,
+            "mode": "safe",
+            "minSamples": 20,
+            "suppressionWasteRate": 0.8,
+            "boostHitRate": 0.35,
+            "retentionDays": 14,
+            "maxPriorityBoost": 25,
+            "maxBudgetTrimPercent": 50
+          }
         }
       },
       "default": {
         "enabled": true,
         "maxBudgetPercent": 20,
-        "warmTopN": 0
+        "warmTopN": 0,
+        "policy": {
+          "enabled": true,
+          "mode": "safe",
+          "minSamples": 20,
+          "suppressionWasteRate": 0.8,
+          "boostHitRate": 0.35,
+          "retentionDays": 14,
+          "maxPriorityBoost": 25,
+          "maxBudgetTrimPercent": 50
+        }
       }
     },
     "observability": {
@@ -1513,13 +1773,18 @@
             "timeoutMs": {
               "type": "integer",
               "minimum": 1000,
-              "maximum": 1800000,
+              "maximum": 18000000,
               "default": 600000
             },
             "cleanupAfterIngest": {
               "type": "boolean",
               "description": "Delete <repoRoot>/index.scip after the post-refresh ingest consumes it. The file is regenerated every refresh, so keeping it just clutters the working tree. Only the default output location is cleaned up — passing --output via args opts you out of cleanup automatically.",
               "default": true
+            },
+            "cacheGeneratedIndexes": {
+              "type": "boolean",
+              "description": "Cache generated SCIP artifacts by source/config fingerprint and reuse them on later unchanged refreshes. The cache invalidates when tracked source files, common build manifests, generator args, or the scip-io binary change.",
+              "default": true
             }
           },
           "default": {
@@ -1528,7 +1793,8 @@
             "args": [],
             "autoInstall": true,
             "timeoutMs": 600000,
-            "cleanupAfterIngest": true
+            "cleanupAfterIngest": true,
+            "cacheGeneratedIndexes": true
           }
         }
       }