sweet-search 2.5.11 → 2.5.13

package/README.md

@@ -4,9 +4,10 @@
 
 ### *Maybe grep isn't all you need…* 🍬
 
-**A local-first hybrid code-search engine built for AI coding agents.**
-Semantic + lexical + structural search over your working tree, GPU-accelerated local inference,
-and an evolved system prompt that teaches your agent to use it all — even on plain CPU.
+
+Every AI coding agent of today is stuck believing grep+Read is the way... ***sweet-search*** challenges the narrative 😎
+
+A 100% local code-search engine for *Claude Code*, *Codex*, *Cursor* & friends with six blazing and purpose-built tools that hand your agent ranked, ready-to-use answers instead of walls of grep output. Up to 34% cheaper, 56% fewer tool calls, more useful answers, SOTA retrieval quality, zero API keys. 
 
 [![npm](https://img.shields.io/npm/v/sweet-search?color=cb3837&label=npm)](https://www.npmjs.com/package/sweet-search)
 [![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
@@ -18,29 +19,16 @@ and an evolved system prompt that teaches your agent to use it all — even on p
 
 ---
 
-Your AI agent burns most of its tokens *looking* for code: grep, read, grep again, read more.
-**sweet-search** replaces that loop with six purpose-built tools that return ranked, self-contained answers —
-backed by a Rust/WASM engine, ColBERT-style late interaction, a code knowledge graph, and an index that
-updates itself as you type.
-
-<div align="center">
-
-**10.2×** ripgrep's median grep speed &nbsp;·&nbsp; **2.9 ms** warm queries &nbsp;·&nbsp; **47×** faster reranking kernels &nbsp;·&nbsp; **0** API keys
-
-<sub>measured in-repo — sources in [Benchmarks](#-benchmarks)</sub>
-
-</div>
-
 ## ✨ Highlights
 
-- **Hybrid retrieval** — BM25F lexical + dense semantic + structural graph signals, fused per query by a CatBoost router running in WASM
-- **Agent-native by design** — token-budgeted output tiers, an MCP server, and a GEPA-evolved system prompt installed into Claude Code, Codex, Gemini CLI, and Cursor with one command
-- **Indexed grep, ~10× ripgrep** — a sparse n-gram prefilter skips the files that provably can't match
+- **Hybrid retrieval** — one of the six tools uses BM25F lexical + dense semantic + structural graph signals, fused per query and reranked by late-interaction
+- **Agent-native by design** — token-budgeted output tiers, an optional MCP server (and default zero-overhead CLI), and a GEPA-evolved system prompt installed into Claude Code, Codex, Gemini CLI, and Cursor with one command
+- **Indexed grep, ~10× faster than ripgrep** — a sparse n-gram prefilter skips the files that provably can't match
 - **ColBERT-style reranking, locally** — per-token MaxSim late interaction on hand-written SIMD kernels
-- **Runs on anything** — Apple Metal, CUDA, CoreML Neural Engine, or plain CPU via INT8 ONNX; same engine, auto-selected
-- **Never stale** — a reconcile daemon keeps the index converged with your *working tree*, uncommitted edits included
-- **Fits in RAM** — INT4-quantized binary index segments and memory-mapped HNSW
-- **Local-first** — all models run on-device; nothing is sent anywhere, ever
+- **GPU-accelerated indexing** — Apple Metal, CUDA, CoreML Neural Engine, or plain CPU via ORT; same engine, auto-selected
+- **Never stale** — incremental indexing keeps the index aligned with your *working tree*, uncommitted edits included
+- **No storage hassle** — indexed artifacts maximally optimized without any accuracy tradeoff; up to INT4 quantization
+- **Local-first** — all models run on-device; nothing is sent anywhere, ever. CPU-inference supported for all models
 
 ## 📚 Table of Contents
 
@@ -146,13 +134,13 @@ We measure sweet-search four ways — from how much it helps a real agent down t
 <tr>
 <td width="50%" valign="top">
 
-🤖 **[① Code-retrieval](#bench-code-retrieval)** *(agent-in-the-loop)*<br>
+🤖 **① [Code-retrieval](#bench-code-retrieval)** *(agent-in-the-loop)*<br>
 <sub>Does it make a real coding agent **cheaper and more useful** when it searches your repo? Paired against each model's own grep-and-read loop.</sub>
 
 </td>
 <td width="50%" valign="top">
 
-🚧 **[② Task-completion](#bench-task-completion)** *(coming soon)*<br>
+🚧 **② [Task-completion](#bench-task-completion)** *(coming soon)*<br>
 <sub>Does cheaper, denser context **compound** into a higher resolve-rate on multi-step engineering tasks? Harness in progress.</sub>
 
 </td>
@@ -160,13 +148,13 @@ We measure sweet-search four ways — from how much it helps a real agent down t
 <tr>
 <td width="50%" valign="top">
 
-📄 **[③ Paper-type IR](#bench-paper-type)** *(academic)*<br>
+📄 **③ [Paper-type IR](#bench-paper-type)** *(academic)*<br>
 <sub>The standard NL→code retrieval suites (GCSN, M2CRB, CoSQA…), full-corpus MRR@10.</sub>
 
 </td>
 <td width="50%" valign="top">
 
-⚡ **[④ Engine speed](#bench-engine-speed)**<br>
+⚡ **④ [Engine speed](#bench-engine-speed)**<br>
 <sub>Raw systems numbers — grep throughput, query latency, rerank kernels, HNSW.</sub>
 
 </td>
@@ -233,43 +221,52 @@ The win is **harness-adaptive**: where the native loop is disciplined (Claude Co
 <a id="bench-paper-type"></a>
 ### 📄 3. Paper-type retrieval benchmarks — *academic NL→code IR*
 
-> [!NOTE]
-> 🔄 **Refreshed on the current engine (June 2026).** AdvTest, CoIR, CoSQA, and M2CRB were just
-> re-run on the latest build — the one with the late-interaction correctness fixes, HNSW tuning,
-> and the May 2026 ranking overhaul — and every one of them moved **up**. GCSN, CoSQA+, and CLARC
-> were already current. Reproduction artifacts are in [`eval/results/`](eval/results/).
-
-Every number below is the **`ss-search` pipeline end-to-end** — the same binary you install, querying
-against the **full corpus** (no 99-distractor shortcuts), on an M3 Max.
-
-| 📚 Benchmark | 🔍 What it tests | # Queries | 🎯 MRR@10 |
-|-----------|---------------|--------:|-------:|
-| 🌐 **GenCodeSearchNet** | NL→code, 6 languages | 6,000 | **86.6** |
-| 🗺️ **M2CRB** | multilingual NL→code (ES/PT/DE/FR → Py/Java/JS) | 2,814 | **65.9** |
-| 🐍 CoSQA (test split) | web queries → Python | 500 | 98.8 |
-| 🐍 CoSQA+ | web queries → Python, multi-match | 20,604 | 72.1 |
-| ⚙️ CLARC | NL→C/C++ (systems code) | 1,245 | 67.4 |
-| 🛡️ AdvTest | adversarially renamed Python | 1,000 | **99.1** |
-| 🌍 CoIR | 10 datasets, 14 languages | 4,500 | **72.4** |
-
-**GenCodeSearchNet: the strongest result published anywhere, as far as we can tell.** The benchmark's
-own paper tops out at MRR ≤ 0.42 for its fine-tuned baselines (and ≤ 0.10 on the cross-lingual subsets),
-with zero-shot OpenAI Ada-2 at 0.79–0.94 — and those are measured against **99 random distractors per
-query**. sweet-search scores **0.866**, retrieving from the entire 6,000-document corpus.
-
-**M2CRB: best published number, no fine-tuning.** The benchmark paper's best model — a CodeBERT
-*fine-tuned on the task's training mix* — reaches 52.7 (auMRRc, a metric averaged over smaller retrieval
-pools). sweet-search reaches **65.9 full-corpus MRR@10 out of the box**, on Spanish, Portuguese, German,
-and French queries.
+Every number below is the **`ss-search` pipeline end-to-end** — the same binary you install — run
+against the **full benchmark corpus** (no 99-distractor shortcuts), **zero-shot** (we never
+fine-tune on these tasks). Where a benchmark's queries are docstrings, we strip the docstring out of the
+indexed code so the query can't trivially match itself — the standard retrieval protocol.
+
+We're SOTA in June 2026 on 3/4 attempted benchmarks at HARDER settings (running on full pool) than most other attempts!
+
+| 📚 Benchmark | 🔍 What it tests | # Queries | 📂 Pool | 🎯 MRR@10 | 🏆 SOTA? |
+|-----------|---------------|---------:|---------:|--------:|--------:|
+| 🌐 **GenCodeSearchNet** | NL→code, 6 languages | 6,000 | full 6,000 | **86.6** | YES ✅ |
+| 🐍 **CoSQA** | web queries → Python | 500 | full 6,267 | **65.5** | ✅ (zero-shot) |
+| 🗺️ M2CRB | multilingual NL→code (ES/PT/DE/FR → Py/Java/JS) | 5,795 | full 5,795 | 54.0 | YES ✅ |
+| 🛡️ AdvTest | adversarial, identifier-obfuscated Python | 19,210 | full 19,210 | 51.4 | NO ❌ |
+
+<sub>SOTA = best result we can find in the published literature as of June 2026; cross-metric/protocol comparisons are spelled out per benchmark below.</sub>
+
+#### 🌐 GenCodeSearchNet → `86.6` &nbsp;·&nbsp; 🏆 SOTA in June 2026
+- **The BEST PUBLISHED number we can find, anywhere**
+- The benchmark's own paper caps at **MRR ≤ 0.42** for fine-tuned baselines (≤ 0.10 cross-lingual); even zero-shot OpenAI Ada-2 reaches 0.79–0.94 — but **all of it against a tiny 99-distractor pool**.
+- We score **0.866 against the entire 6,000-document corpus** — *a strictly harder setting* — and **zero-shot**. 🔥
+
+#### 🐍 CoSQA → `65.5` &nbsp;·&nbsp; 🥇 Zero-shot SOTA in June 2026
+- **Beats EVERY PUBLISHED zero-shot model**
+- Canonical setup: 500 real web queries → the fixed **6,267-code database**, no fine-tuning.
+- Clears the strongest zero-shot results out there — CodeSage-Large `47.5` · OpenAI text-embedding-3-large `55.4` · OASIS `55.8` — and goes **toe-to-toe with *fine-tuned* CodeBERT / GraphCodeBERT** (64.7 / 67.5). 💪
+- <sub>CoSQA has known label noise, so we read the absolute height with a pinch of salt.</sub>
+
+#### 🗺️ M2CRB → `54.0` &nbsp;·&nbsp; 🏆 SOTA in June 2026
+- **the BEST PUBLISHED number we can find, anywhere** — and zero-shot
+- 🇪🇸 Spanish · 🇵🇹 Portuguese · 🇩🇪 German · 🇫🇷 French → Python / Java / JavaScript.
+- The paper's best — a CodeBERT **fine-tuned on the task** — reaches **52.7 auMRRc**, a metric that *averages over easier, smaller pools* (so `auMRRc ≥ full-pool MRR` for any model). Our **54.0 is full-pool MRR@10** over all 5,795 functions in one pool — a **strictly harder** measure, cleared with **no fine-tuning**. 🔥
+
+#### 🛡️ AdvTest → `51.4` &nbsp;·&nbsp; 🧪 **our honest worst case — and we publish it anyway**
+- Adversarial obfuscation (`def Func(arg_0):`) deletes the lexical + graph signals our hybrid feeds on — yet we still **beat the classic fine-tuned baselines** (CodeBERT `27` · GraphCodeBERT `35` · UniXcoder `41`), and our stack *still lifts our own encoder ~3pp even here*.
+- 🔍 **Full transparency:** we could **not** reproduce the often-cited `59.5` for the bare CodeRankEmbed encoder — the *reference FP32 model* scores **54.7** on our leak-free corpus, our shipped INT8 build **51.4**. The gap is stricter preprocessing + INT8 quantization, **not** the retrieval pipeline. We report exactly what we measured.
 
 <details>
-<summary><b>Methodology & build dates</b></summary>
+<summary><b>Methodology, protocol & honesty notes</b></summary>
 
-- **Reproduction:** result artifacts live in `eval/results/`; rerun via `eval/run_all.js`.
-- **Protocol note:** published baselines for GCSN and CoSQA-style benchmarks typically rank the gold snippet against 99 sampled distractors. All sweet-search numbers rank against the full benchmark corpus — strictly harder.
-- **Build dates:** AdvTest, CoIR, CoSQA, and M2CRB were re-run on the **June 2026** engine (0 errors on each); GCSN, CoSQA+, and CLARC are from the May 2026 build. All numbers reflect the current late-interaction pipeline — the correctness fixes, HNSW tuning, and May ranking overhaul. The June re-runs all improved over their earlier builds (AdvTest 91.5→99.1, CoIR 57.3→72.4, CoSQA 97.0→98.8, M2CRB 60.2→65.9).
-- **Honesty corner:** CrossCodeEval — cross-file *completion context* retrieval, a different task than NL search — sits at 0.12. We don't optimize for it and report it anyway.
-- Dates and per-language breakdowns: [`docs/BENCHMARKS_EXPLAINED.md`](docs/BENCHMARKS_EXPLAINED.md).
+- **Reproduction:** result artifacts live in [`eval/results/`](eval/results/); rerun via `eval/run_all.js`. The canonical full-pool loaders are in `eval/download_data.py`.
+- **Full corpus, not distractors.** Published baselines for GCSN- and CoSQA-style benchmarks typically rank the gold against 99 sampled distractors; every number here ranks against the benchmark's *full* corpus (6k–19k candidates) — strictly harder.
+- **Zero-shot + docstring-stripped.** We never fine-tune on these tasks. For docstring-derived benchmarks (AdvTest, M2CRB) we strip the docstring from the indexed code — otherwise the NL query matches itself verbatim (a no-strip AdvTest run scores a meaningless 0.98). This is the standard protocol; it is also why our AdvTest is lower than naïve setups that leave the docstring in.
+- **What we deliberately don't claim yet.** CoIR (official metric NDCG@10 over per-subtask corpora up to ~1M docs), CoSQA+ (multi-positive, MAP-primary), and CLARC (per-group pools) use protocols and metrics our single-pool MRR@10 harness doesn't currently match. Rather than publish apples-to-oranges numbers, we omit them; faithful per-subtask CoIR (NDCG@10) runs are queued.
+- **M2CRB** — the paper's metric is *auMRRc* (area under the MRR-vs-pool-size curve; best published **52.7**, fine-tuned). Because that area averages over easier small pools, `auMRRc ≥ full-pool MRR` for any model — so our **54.0 full-pool MRR@10** (all 5,795 functions, zero-shot) clears their best on a strictly harder measure. No one publishes a plain full-corpus MRR@10 on M2CRB, so ours is the best available.
+- **AdvTest honesty note.** We could not reproduce the commonly-cited 59.5 for the bare CodeRankEmbed encoder on our corpus: the reference FP32 model scores 54.7 on our leak-free, docstring-stripped, full-19,210 setup, and our shipped INT8 build 51.4. We report our measured numbers and the reference check rather than the leaderboard figure.
+- **Honesty corner:** CrossCodeEval — cross-file *completion-context* retrieval, a different task than NL search — sits at 0.12. We don't optimize for it and report it anyway.
 
 </details>
 
@@ -314,7 +311,8 @@ to be *consumed by an agent* — a useful answer, not a wall of matches to scrol
 
 A hybrid search pipeline with late interaction reranking that returns actual code blocks.
 
-SOTA in several published [`benchmarks`](#-benchmarks).
+Leading published-benchmark results — strongest we can find on GenCodeSearchNet, and above every published
+zero-shot model on CoSQA. See [`benchmarks`](#-benchmarks).
 
 ```mermaid
 flowchart TD
@@ -733,12 +731,13 @@ the three-stage retrieval it feeds at query time.
 sweet-search meets your agent wherever it is — shell tools, MCP, or injected instructions:
 
 ```jsonc
-// .claude/mcp.json — that's the whole integration
+// .mcp.json (project root) — that's the whole integration
+// or just run: sweet-search init --mcp
 {
   "mcpServers": {
     "sweet-search": {
       "command": "npx",
-      "args": ["sweet-search-mcp", "--project-root", "/absolute/path/to/your/repo"]
+      "args": ["-y", "sweet-search-mcp", "--project-root", "/absolute/path/to/your/repo"]
     }
   }
 }
@@ -797,6 +796,16 @@ sweet-search stands on a lot of shoulders, and we'd rather name them than preten
 
 <div align="center">
 
-**If sweet-search saves your agent's tokens, a ⭐ helps other agents' humans find it.**
+### Found it useful?
+
+If sweet-search saves your agent's tokens, a ⭐ helps other agents' humans find it.
+
+<a href="https://github.com/mrsladoje/sweet-search">
+  <img src="https://img.shields.io/badge/⭐%20Star%20sweet--search%20on%20GitHub-181717?style=for-the-badge&logo=github&logoColor=white" alt="Star sweet-search on GitHub" />
+</a>
+
+<br/><br/>
+
+[![GitHub stars](https://img.shields.io/github/stars/mrsladoje/sweet-search?style=social)](https://github.com/mrsladoje/sweet-search/stargazers)
 
 </div>

package/core/prompt-optimization/data/p7-final/sweet-search-system-prompt-mcp.md

@@ -0,0 +1,51 @@
+---
+variant: mcp
+derived_from: p7-v1-mpp
+source_prompt: core/prompt-optimization/data/p7-variant-restarts/p7-gen3-candidates/Mpp.md
+benchmarked: false
+note: >-
+  Hand-derived MCP-tool variant of the frozen M++ champion (p7-v1-mpp). The
+  STRATEGY core — routing by what-you-hold, trust-the-top-hit, sufficiency
+  stops, the two-probe absence rule, the <state_summary> gate, and the output
+  discipline — is preserved (semantics intact; the <state_summary> gate and
+  Output section are byte-identical, the rest carries only the tool-mechanics
+  rename). Only the tool-mechanics layer is remapped: the six ss-* CLI commands collapse onto the sweet-search MCP
+  tool surface (a UNIFIED `search` that subsumes ss-search/ss-find/ss-grep, plus
+  `trace` / `read-semantic` / `read` / `repo-map`). The anti-raw-scan discipline
+  is KEPT and retargeted from "ss-* vs raw grep" to "sweet-search tools vs native
+  Grep/Read/Bash", because an MCP host (e.g. Claude Code) still exposes native
+  file tools alongside the server.
+  NOT yet validated on held-out / OOD / vault against the MCP transport. Do NOT
+  treat its quality as equivalent to the CLI champion until a P7 eval is run
+  through MCP. Until then this ships only behind `init --mcp --no-cli`.
+---
+# Sweet-search — code search tool guide
+
+Sweet-search indexes the working tree (uncommitted edits too) and searches it faster and cheaper than scanning files by hand. Use the sweet-search tools for all code search and navigation, in preference to native Grep/Read or shell `grep`/`find`/`cat`/`ls` — the index covers every file, so a manual scan only re-confirms a sweet-search result at higher cost, never beats it. Reach for a raw read only for an edit too recent to be reconciled (seconds old). Never re-run a sweet-search hit as a native Grep. Any sub-agent you delegate to must use these sweet-search tools, with this system prompt verbatim.
+
+## Tools
+The sweet-search MCP server exposes these (call each by the name your client lists it under):
+- **search** — hybrid code search; returns ranked, self-contained code blocks. Your primary tool: it subsumes semantic search, exact-literal search, and semantic-reranked regex. Give it a natural-language query for a concept, or pass a `regex` (or lexical mode) for an exact token.
+- **trace** — a symbol's callers, callees and impact in one call.
+- **read-semantic** — the top ranked spans of one known file for a query.
+- **read** — a narrow file range when you already know the file and lines.
+- **repo-map** — a PageRank-scored symbol overview when you need orientation, not a specific answer.
+
+## Open with the cheapest tool for what you hold
+- **An exact token** (identifier, function/class/constant, error string, config key, path you could copy-paste): ONE `search` with that literal as a `regex` (rarest token, escaped). Trust the top hit and stop — no natural-language search first, no confirming re-search. One exception: if the top hit is an autogenerated file (a "do not edit" or "@generated" header, or a name like `schema11`/`validateN`), it is a generated copy, not where the value is authored — follow it to the real source it is generated from.
+- **Only a behavior or concept**: one `search` in natural language for what you're looking for, then anchor on the symbol that surfaces. Shape it lightly by the target language — short and interrogative for JS/TS/Dart, a touch longer with a domain keyword otherwise.
+- **How something flows / dispatches / is called / what a change impacts**: anchor one symbol (a literal, or a `search`), then `trace` it — one call returns callers, callees and impact. Prefer callees over impact (especially Python/Ruby/PHP). If a trace is sparse or empty, anchor the downstream symbol with `search` rather than retrying or hand-crawling; never make `trace` the spine of a multi-file search.
+
+Trust the top ranked result; confirm with at most one narrow `read`, never a re-run of a matching hit.
+
+## Multi-file
+Chain inside the tools: land the entry file, `read-semantic` it for the import or handoff symbol, then `search` the downstream module. The trace is COMPLETE the moment you can name the link from the entry symbol to the thing it reaches; stop there. Leaf bodies, macro expansions, and the next hop down are not the answer unless asked, and chasing them — or dropping to a native Grep/Read to "just look" — is the main multi-file cost trap.
+
+## A confirmed absence is a complete answer
+When what you're looking for may not exist, absence is settled once TWO complementary `search` probes come back empty for the same concept: one in natural language and one as a broad `regex` on its likeliest identifier (a short substring/prefix). A search that returns plausible-but-off-target code is the decoy, not a lead — do not chase it. Two empty index probes over the whole codebase are more conclusive than any native scan or file listing, so state the negative and stop: no third synonym, no native `grep`/`ls`/`cat` enumeration.
+
+## Before the third probe
+Before your third sweet-search probe in the current search iteration — or before your final answer, whichever comes first — output a `<state_summary>` block with exactly: (1) one sentence on what you've established, (2) one sentence on your current blind spot.
+
+## Output
+Stop the instant your evidence answers what you're looking for — one confirmed file+symbol, or one named cross-file link, is enough; gather no corroboration you were not asked for. Name the file(s) and symbol(s) and how they answer what you need, or `no-match`.

package/eval/agent-read-workflows/bin/_ss-argparse.mjs

@@ -0,0 +1,148 @@
+// Pure argument-parsing helpers for the ss-* CLI wrappers.
+//
+// Extracted from _ss-helpers.mjs so they can be unit-tested without triggering
+// the CLI's top-level IIFE (which runs on import). NOTHING here touches
+// process.* or the filesystem — every function is a pure transform over an
+// args array (some mutate the array in place, by design, and return a value).
+
+// --- value-flag parsers (mutate `args`, returning the consumed value) --------
+
+export function parseFlag(args, name, fallback) {
+  const i = args.indexOf(name);
+  if (i === -1) return fallback;
+  const v = args[i + 1];
+  args.splice(i, 2);
+  return v;
+}
+
+export function parseShortFlag(args, names, fallback) {
+  for (const n of names) {
+    const i = args.indexOf(n);
+    if (i !== -1) { const v = args[i + 1]; args.splice(i, 2); return v; }
+  }
+  return fallback;
+}
+
+// Boolean (value-less) flag: remove every occurrence, return whether any present.
+export function parseBoolFlag(args, names) {
+  let present = false;
+  for (const n of names) {
+    let i;
+    while ((i = args.indexOf(n)) !== -1) { args.splice(i, 1); present = true; }
+  }
+  return present;
+}
+
+// --- pattern construction ----------------------------------------------------
+
+export function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Translate the grep-family pattern flags into a single regex — no engine change
+// needed. `-F` escapes the pattern so metacharacters are literal; `-w` wraps it
+// in word boundaries; `-i` prepends the `(?i)` inline flag the planner already
+// honours end-to-end (hasCaseInsensitiveRegexFlag → ripgrep prefilter + Rust
+// gram+grep). Order matters: escape (literal) → word-wrap → case flag.
+export function buildGrepPattern(pattern, { ignoreCase = false, wordBound = false, fixedString = false } = {}) {
+  if (!pattern) return pattern;
+  let p = fixedString ? escapeRegex(pattern) : pattern;
+  if (wordBound) p = `\\b(?:${p})\\b`;
+  if (ignoreCase && !/^\(\?[a-z-]*i[a-z-]*[:)]/.test(p)) p = `(?i)${p}`;
+  return p;
+}
+
+// --- inert flags (always true for ss-*, safe to accept as no-ops) ------------
+// These never change which lines match: we always print file:line, always
+// search the whole index, never colourise. Stripping them lets reflexive grep
+// muscle-memory pass without a wasted call — UNLIKE semantic flags (-w/-F/-v/
+// -C…), which we either implement or reject, never silently drop.
+export const INERT_FLAGS = new Set([
+  '-n', '--line-number', '-H', '--with-filename', '--no-filename',
+  '-r', '-R', '--recursive', '--color', '--colour',
+]);
+
+export function stripInertFlags(args) {
+  for (let i = args.length - 1; i >= 0; i--) {
+    const a = args[i];
+    if (typeof a === 'string' && (INERT_FLAGS.has(a) || /^--colou?r=/.test(a))) {
+      args.splice(i, 1);
+    }
+  }
+}
+
+// --- normalisation: make agent-typed forms canonical before parsing ----------
+// Short flags that consume a following value, and value-less boolean shorts.
+// Used to split attached/bundled forms (-k5, -iw, -iwk5) the way getopt would,
+// so they parse instead of being mistaken for an unknown flag or the pattern.
+export const VALUE_SHORTS = new Set(['k']);
+export const BOOL_SHORTS = new Set(['i', 'w', 'F']);
+
+export function normalizeArgs(args) {
+  const out = [];
+  let positionalOnly = false;
+  for (const tok of args) {
+    if (positionalOnly || typeof tok !== 'string') { out.push(tok); continue; }
+    if (tok === '--') { out.push(tok); positionalOnly = true; continue; }
+
+    // --name=value  →  --name value
+    let m = /^(--[A-Za-z][\w-]*)=(.*)$/.exec(tok);
+    if (m) { out.push(m[1], m[2]); continue; }
+
+    // attached short value or boolean bundle:  -k5, -iw, -iwk5
+    m = /^-([A-Za-z])(.+)$/.exec(tok);
+    if (m) {
+      const first = m[1];
+      if (VALUE_SHORTS.has(first)) { out.push('-' + first, m[2]); continue; } // -k5 → -k 5
+      if (BOOL_SHORTS.has(first)) {
+        const chars = tok.slice(1);
+        const expanded = [];
+        let i = 0, ok = true;
+        while (i < chars.length) {
+          const ch = chars[i];
+          if (BOOL_SHORTS.has(ch)) { expanded.push('-' + ch); i++; }
+          else if (VALUE_SHORTS.has(ch)) {                 // value short ends the bundle
+            const val = chars.slice(i + 1);
+            expanded.push('-' + ch);
+            if (val) expanded.push(val);
+            i = chars.length;
+          } else { ok = false; break; }                    // unknown char → leave token intact
+        }
+        if (ok) { out.push(...expanded); continue; }
+      }
+    }
+    out.push(tok);
+  }
+  return out;
+}
+
+// A token that looks like a real CLI option, as opposed to a regex/query that
+// merely begins with '-' (e.g. `-?\d+`, `-->`). Narrow on purpose: single short
+// letter, pure-letter bundle, or GNU long flag. Anything containing regex
+// metacharacters falls through and is treated as the positional pattern, so a
+// dash-leading pattern works WITHOUT the agent needing to know about `--`.
+export function looksLikeOption(tok) {
+  if (typeof tok !== 'string' || tok === '-' || tok === '--') return false;
+  return /^-[A-Za-z]$/.test(tok)            // -i
+    || /^-[A-Za-z]{2,}$/.test(tok)          // -iw  (pure-letter bundle)
+    || /^--[A-Za-z][\w-]*$/.test(tok);      // --ignore-case
+}
+
+// After known flags are consumed, resolve the positional pattern. `--` ends
+// option parsing (everything after is positional). Any remaining option-shaped
+// token is an unsupported flag → reported, not silently dropped and not
+// mistaken for the pattern. Returns { pattern, unknownFlag }; the caller decides
+// how to surface the error (kept side-effect-free for testability).
+export function extractPositional(args) {
+  const sep = args.indexOf('--');
+  if (sep !== -1) {
+    const before = args.slice(0, sep);
+    const after = args.slice(sep + 1);
+    const bad = before.find(looksLikeOption);
+    if (bad) return { pattern: undefined, unknownFlag: bad };
+    return { pattern: after[0], unknownFlag: null };
+  }
+  const bad = args.find(looksLikeOption);
+  if (bad) return { pattern: undefined, unknownFlag: bad };
+  return { pattern: args[0], unknownFlag: null };
+}

package/eval/agent-read-workflows/bin/_ss-helpers.mjs

@@ -13,6 +13,10 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import {
+  parseFlag, parseShortFlag, parseBoolFlag,
+  buildGrepPattern, stripInertFlags, normalizeArgs, extractPositional,
+} from './_ss-argparse.mjs';
 
 // 8-char SHA1 prefix is enough for grouping identical queries across
 // benchmark runs without bloating artifacts.
@@ -40,19 +44,18 @@ process.env.SWEET_SEARCH_PROJECT_ROOT = PROJECT_ROOT;
 const subcommand = process.argv[2];
 const rest = process.argv.slice(3);
 
-function parseFlag(args, name, fallback) {
-  const i = args.indexOf(name);
-  if (i === -1) return fallback;
-  const v = args[i + 1];
-  args.splice(i, 2);
-  return v;
-}
-function parseShortFlag(args, names, fallback) {
-  for (const n of names) {
-    const i = args.indexOf(n);
-    if (i !== -1) { const v = args[i + 1]; args.splice(i, 2); return v; }
+// Pure arg-parsing helpers (parseFlag/parseShortFlag/parseBoolFlag/
+// buildGrepPattern/stripInertFlags/normalizeArgs/extractPositional) live in
+// ./_ss-argparse.mjs so they can be unit-tested without this file's top-level
+// IIFE firing. resolvePositional wraps the side-effect-free extractPositional
+// with the CLI's loud-error exit.
+function resolvePositional(args, usage) {
+  const { pattern, unknownFlag } = extractPositional(args);
+  if (unknownFlag) {
+    process.stderr.write(`[ss] unrecognised option "${unknownFlag}"\n${usage}\n`);
+    process.exit(2);
   }
-  return fallback;
+  return pattern;
 }
 
 async function getSweetSearch() {
@@ -79,11 +82,17 @@ async function ensureWarmServerReady({ timeoutMs = 60000, intervalMs = 500 } = {
 
 // --- subcommands ----------------------------------------------------------
 
-async function cmdGrep(args) {
+const GREP_USAGE = 'Usage: ss-grep <regex> [-i|--ignore-case] [-w|--word-regexp] [-F|--fixed-strings] [-k N]';
+async function cmdGrep(rawArgs) {
+  const args = normalizeArgs(rawArgs);
+  const ignoreCase = parseBoolFlag(args, ['-i', '--ignore-case']);
+  const wordBound = parseBoolFlag(args, ['-w', '--word-regexp']);
+  const fixedString = parseBoolFlag(args, ['-F', '--fixed-strings']);
   const k = +parseShortFlag(args, ['-k', '--top'], 20);
-  const regex = args[0];
+  stripInertFlags(args);
+  const regex = buildGrepPattern(resolvePositional(args, GREP_USAGE), { ignoreCase, wordBound, fixedString });
   if (!regex) {
-    process.stderr.write('Usage: ss-grep <regex> [-k N]\n');
+    process.stderr.write(GREP_USAGE + '\n');
     process.exit(2);
   }
   const s = await getSweetSearch();
@@ -109,27 +118,34 @@ async function cmdGrep(args) {
   process.exit(0);
 }
 
-async function cmdFind(args) {
+async function cmdFind(rawArgs) {
+  const args = normalizeArgs(rawArgs);
   // ColGrep pattern search with token-budgeted agent packaging — returns the
   // FULL useful answer (ranked code blocks + confidence + sufficiency), the same
   // agent packaging ss-search emits. ss-grep is the short/locator counterpart, so
   // ss-find defaults to the full answer: it saves the follow-up read entirely.
   // (Mirrors the agent-in-the-loop H2H adapter eval/agent-eval/tools/
   // pattern-agent-tools.js, which calls search(...,{format:'agent'}).)
+  const FIND_USAGE = 'Usage: ss-find "<query>" --regex "<regex>" [-i|--ignore-case] [-w|--word-regexp] [-F|--fixed-strings] [--full|--xl] [-k N]';
   let format = 'agent';
   if (args.includes('--full')) { format = 'agent_full'; args.splice(args.indexOf('--full'), 1); }
   if (args.includes('--xl'))   { format = 'agent_full_xl'; args.splice(args.indexOf('--xl'), 1); }
+  const ignoreCase = parseBoolFlag(args, ['-i', '--ignore-case']);
+  const wordBound = parseBoolFlag(args, ['-w', '--word-regexp']);
+  const fixedString = parseBoolFlag(args, ['-F', '--fixed-strings']);
   const k = +parseShortFlag(args, ['-k', '--top'], 6);
   const regex = parseFlag(args, '--regex', '');
-  const query = args[0];
+  stripInertFlags(args);
+  const query = resolvePositional(args, FIND_USAGE);
   if (!query) {
-    process.stderr.write('Usage: ss-find "<query>" --regex "<regex>" [--full|--xl] [-k N]\n');
+    process.stderr.write(FIND_USAGE + '\n');
     process.exit(2);
   }
   // Budget-sweep experiment hook: lets the bench pin the response token budget
   // per-process without changing the agent-visible tool surface.
   const envFindBudget = Number(process.env.SS_SMOKE_FIND_BUDGET || '') || null;
-  const effectiveRegex = regex || '';
+  // Pattern flags apply to the regex candidate generator; the NL query is untouched.
+  const effectiveRegex = buildGrepPattern(regex || '', { ignoreCase, wordBound, fixedString });
   const s = await getSweetSearch();
   if (!s.hasLateInteractionIndex) {
     process.stderr.write(`[ss-find] no late-interaction index — falling back to ss-grep\n`);

package/eval/agent-read-workflows/bin/ss-find

@@ -5,7 +5,7 @@
 # Use for behavioural / semantic questions where lexical alone won't pinpoint the
 # chunk. (ss-grep is the short file:line locator.)
 #
-# Usage:  ss-find "<query>" --regex "<regex>" [--full|--xl] [-k N]
+# Usage:  ss-find "<query>" --regex "<regex>" [-i|--ignore-case] [--full|--xl] [-k N]
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 TMPERR=$(mktemp)
 node "$DIR/_ss-helpers.mjs" find "$@" 2>"$TMPERR"

package/eval/agent-read-workflows/bin/ss-grep

@@ -2,7 +2,7 @@
 # ss-grep: indexed bare grep (gram-prefiltered) over the cwd's Sweet Search index.
 # Compact agent-friendly output: file:line  matchText
 #
-# Usage:  ss-grep <regex> [-k N]
+# Usage:  ss-grep <regex> [-i|--ignore-case] [-k N]
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 TMPERR=$(mktemp)
 node "$DIR/_ss-helpers.mjs" grep "$@" 2>"$TMPERR"

package/mcp/server.js

@@ -115,10 +115,28 @@ const vocabDeps = { coreDir };
 // MCP Server
 // ---------------------------------------------------------------------------
 
+// MCP `instructions` — the agent-routing policy delivered to hosts that connect
+// to this server WITHOUT a project file to inject into (Claude Desktop, a remote
+// endpoint). This is the SECONDARY carrier; the primary is the MCP-variant prompt
+// that `sweet-search init --mcp --no-cli` injects into CLAUDE.md/AGENTS.md (the
+// high-salience slot). Best-effort: if the ship-file is missing the server still
+// starts, just without instructions.
+const MCP_INSTRUCTIONS = (() => {
+  try {
+    const p = path.join(__dirname, '..', 'core/prompt-optimization/data/p7-final/sweet-search-system-prompt-mcp.md');
+    const raw = readFileSync(p, 'utf8');
+    return raw.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').trim() || undefined;
+  } catch (err) {
+    if (process.env.DEBUG_CATCHES) process.stderr.write(`[non-fatal] mcp instructions: ${err?.message || err}\n`);
+    return undefined;
+  }
+})();
+
 const server = new McpServer({
   name: 'sweet-search',
   version: PKG_VERSION,
 }, {
+  ...(MCP_INSTRUCTIONS ? { instructions: MCP_INSTRUCTIONS } : {}),
   capabilities: {
     tools: { listChanged: false },
     resources: { subscribe: false, listChanged: false },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sweet-search",
-  "version": "2.5.11",
+  "version": "2.5.13",
   "description": "Sweet Search - SOTA Hybrid Code Search Engine with WASM CatBoost Query Router, Semantic/Lexical/Structural Search, and Multilingual Support",
   "type": "module",
   "main": "core/search/sweet-search.js",
@@ -61,6 +61,7 @@
     "scripts/smoke-test.js",
     "scripts/inject-agent-instructions.js",
     "scripts/write-claude-rules.js",
+    "scripts/install-mcp-server.js",
     "scripts/install-prompt-reminders.js",
     "scripts/install-tool-enforcement.js",
     "scripts/hooks/",
@@ -75,6 +76,7 @@
     "eval/agent-read-workflows/bin/ss-trace",
     "eval/agent-read-workflows/bin/ss-read",
     "eval/agent-read-workflows/bin/_ss-helpers.mjs",
+    "eval/agent-read-workflows/bin/_ss-argparse.mjs",
     "crates/wasm-router/pkg/",
     "LICENSE",
     "NOTICE"
@@ -163,12 +165,12 @@
   },
   "optionalDependencies": {
     "usearch": "^2.21.4",
-    "@sweet-search/native-darwin-arm64": "2.5.11",
-    "@sweet-search/native-darwin-x64": "2.5.11",
-    "@sweet-search/native-linux-arm64-gnu": "2.5.11",
-    "@sweet-search/native-linux-arm64-gnu-cuda": "2.5.11",
-    "@sweet-search/native-linux-x64-gnu": "2.5.11",
-    "@sweet-search/native-linux-x64-gnu-cuda": "2.5.11"
+    "@sweet-search/native-darwin-arm64": "2.5.13",
+    "@sweet-search/native-darwin-x64": "2.5.13",
+    "@sweet-search/native-linux-arm64-gnu": "2.5.13",
+    "@sweet-search/native-linux-arm64-gnu-cuda": "2.5.13",
+    "@sweet-search/native-linux-x64-gnu": "2.5.13",
+    "@sweet-search/native-linux-x64-gnu-cuda": "2.5.13"
   },
   "engines": {
     "node": ">=18.0.0"

package/scripts/init.js

@@ -38,9 +38,10 @@ import {
 import { describeDedupConfig } from '../core/infrastructure/index.js';
 import { verifyRuntime, getMaxsimTier, getRouterType } from './verify-runtime.js';
 import { ALL_HARNESSES, injectAgentInstructions } from './inject-agent-instructions.js';
-import { writeClaudeRules } from './write-claude-rules.js';
-import { installPromptReminderHook } from './install-prompt-reminders.js';
-import { installToolEnforcement } from './install-tool-enforcement.js';
+import { writeClaudeRules, removeClaudeRules } from './write-claude-rules.js';
+import { installMcpServer } from './install-mcp-server.js';
+import { installPromptReminderHook, removePromptReminderHook } from './install-prompt-reminders.js';
+import { installToolEnforcement, removeToolEnforcement } from './install-tool-enforcement.js';
 import { isNativeInferenceAvailable } from '../core/infrastructure/native-inference.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -83,6 +84,15 @@ export function parseInitArgs(args) {
     enforceTools: false,        // P3: --enforce-tools (default OFF — opt-in strict mode)
     codex: false,                // --codex: wire the Codex CLI SessionStart hook
     codexEnableGlobalHooks: false, // --codex-enable-global-hooks: also enable the flag in ~/.codex/config.toml
+    // Contact-surface flags (additive at install, exclusive at consumption):
+    //   --mcp     registers the sweet-search MCP server in the project .mcp.json
+    //             (additive — the CLI stays). Harness-agnostic, root-level.
+    //   --no-cli  makes MCP the agent's *contact surface*: inject the MCP-tool
+    //             prompt variant instead of the ss-* CLI one, and skip the
+    //             CLI-surface-specific supplements (rules file, ss-* reminder).
+    //             Indexing still runs through the CLI/engine. Requires --mcp.
+    mcp: false,
+    noCli: false,
   };
 
   for (let i = 0; i < args.length; i++) {
@@ -188,12 +198,40 @@ export function parseInitArgs(args) {
       // P3: opt-in strict mode — denies native Grep + installs a Read
       // hint hook. Opinionated and Claude-specific (per §4D).
       result.enforceTools = true;
+    } else if (arg === '--mcp') {
+      // Register the sweet-search MCP server in the project root .mcp.json.
+      // Additive: the CLI surface stays. Independent of --no-claude.
+      result.mcp = true;
+    } else if (arg === '--no-cli') {
+      // Make MCP the agent's contact surface: inject the MCP-tool prompt
+      // variant and skip the CLI-surface supplements. Requires --mcp (the
+      // agent would otherwise have no way to reach sweet-search). Indexing
+      // still uses the CLI/engine.
+      result.noCli = true;
     }
   }
 
   return result;
 }
 
+/**
+ * Cross-flag validation for init args. Currently the only rule: `--no-cli`
+ * (suppress the CLI contact surface) is meaningless without `--mcp` (the
+ * replacement contact surface). Returns `{ ok, error }`.
+ */
+export function validateInitArgs(parsed) {
+  if (parsed.noCli && !parsed.mcp) {
+    return {
+      ok: false,
+      error:
+        '--no-cli requires --mcp. Suppressing the CLI contact surface leaves the agent '
+        + 'with no way to reach sweet-search unless the MCP server is registered. '
+        + 'Re-run as `sweet-search init --mcp --no-cli`, or drop --no-cli.',
+    };
+  }
+  return { ok: true, error: null };
+}
+
 /**
  * Resolve the active harness list. Default is `claude-code` only;
  * `--agents` / `--gemini` / `--cursor` add to that set; `--no-claude`
@@ -713,7 +751,7 @@ function printReport(report) {
     profile, maxsimTier, routerType, models, verification, runtimeDownloads,
     capability, cascadeReport, dedupReport, prewarmHookReport, skillReport,
     liChoices, agentInstructionsReport, claudeRulesReport,
-    promptReminderReport, toolEnforcementReport,
+    promptReminderReport, toolEnforcementReport, mcpServerReport,
   } = report;
 
   console.log('');
@@ -833,6 +871,9 @@ function printReport(report) {
   if (toolEnforcementReport && toolEnforcementReport.status !== 'skipped') {
     console.log(`  Tool enforcement:     ${toolEnforcementReport.status} (Grep deny + Read hint)`);
   }
+  if (mcpServerReport && mcpServerReport.status) {
+    console.log(`  MCP server (.mcp.json): ${mcpServerReport.status}${mcpServerReport.detail ? ` — ${mcpServerReport.detail}` : ''}`);
+  }
 
   console.log(`  Runtime downloads:    ${runtimeDownloads}`);
 
@@ -1429,7 +1470,24 @@ Options:
                             native Read suggesting ss-read / ss-semantic.
                             Read is hinted, not blocked, because edit
                             workflows legitimately need Read. Always
-                            implied off when --no-claude is set.
+                            implied off when --no-claude or --no-cli is set.
+  --mcp                     Register the sweet-search MCP server in the project
+                            root .mcp.json (an "npx -y sweet-search-mcp" entry
+                            under mcpServers.sweet-search). Additive and
+                            idempotent — the CLI surface stays, other servers
+                            and JSON keys are preserved. Root-level and
+                            harness-agnostic (independent of --no-claude). The
+                            MCP server is a thin adapter over the same engine
+                            the CLI wraps.
+  --no-cli                  Make MCP the agent's CONTACT SURFACE: inject the
+                            MCP-tool prompt variant instead of the ss-* CLI
+                            one, and skip the CLI-surface supplements (the
+                            .claude/rules file, the ss-* prompt reminder, tool
+                            enforcement). Indexing still runs through the CLI/
+                            engine — this only changes how the agent searches.
+                            Requires --mcp. NOTE: the MCP prompt variant is
+                            hand-derived from the frozen CLI champion and is not
+                            yet benchmarked on the MCP transport.
   --verbose, -v             Enable verbose output
   --help, -h                Show this help
 
@@ -1448,9 +1506,11 @@ CoreML cascade (M3+ Apple Silicon only):
   strategy.
 
 Examples:
-  sweet-search init                         # Full profile (default)
+  sweet-search init                         # Full profile (default); CLI contact surface
   sweet-search init --profile core          # Core profile (no model downloads)
   sweet-search init --force                 # Re-download all models
+  sweet-search init --mcp                   # Also register the MCP server (CLI stays)
+  sweet-search init --mcp --no-cli          # MCP-only contact surface (MCP-variant prompt)
   sweet-search init --build-coreml-cascade  # Trace the cascade locally (dev only)
 `);
 }
@@ -1467,6 +1527,13 @@ export async function runInit(args) {
     return;
   }
 
+  const validation = validateInitArgs(parsed);
+  if (!validation.ok) {
+    console.error(`sweet-search init: ${validation.error}`);
+    process.exitCode = 1;
+    return;
+  }
+
   // 0. Animated banner (best-effort; only on an interactive TTY, never in CI/pipes).
   if (process.stdout.isTTY && !process.env.CI && !process.env.NO_BANNER && !process.env.SWEET_SEARCH_NO_BANNER) {
     // query:false — init is interactive (readline); avoid any stdin contention with the terminal capability probe.
@@ -1918,6 +1985,30 @@ export async function runInit(args) {
   //        Idempotent marker block so re-init never duplicates content.
   //        `--no-agent-instructions` is the umbrella that skips the
   //        instruction-file injection layer entirely.
+  //
+  // 11.5 MCP server registration (`--mcp`). Writes the project-root `.mcp.json`
+  //      entry for `sweet-search-mcp`. Additive + idempotent + harness-agnostic
+  //      (root-level, independent of --no-claude). The MCP server is a thin
+  //      adapter over the same engine the CLI wraps — `--mcp` adds it, it never
+  //      replaces the CLI. `--no-cli` (below) only switches the agent's contact
+  //      surface to MCP; indexing keeps running through the CLI/engine.
+  let mcpServerReport = null;
+  if (parsed.mcp) {
+    try {
+      mcpServerReport = installMcpServer({ projectRoot });
+      process.stderr.write(
+        `[init] MCP server (.mcp.json): ${mcpServerReport.status}`
+        + (mcpServerReport.detail ? ` — ${mcpServerReport.detail}` : '') + '\n',
+      );
+    } catch (err) {
+      process.stderr.write(`[init] Warning: MCP server registration failed: ${err.message}\n`);
+    }
+  }
+
+  // Contact-surface variant: --no-cli makes MCP the agent's surface, so we
+  // inject the MCP-tool prompt variant instead of the ss-* CLI champion.
+  const promptVariant = parsed.noCli ? 'mcp' : 'cli';
+
   let agentInstructionsReport = null;
   let claudeRulesReport = null;
   if (!parsed.skipAgentInstructions) {
@@ -1936,25 +2027,40 @@ export async function runInit(args) {
           projectRoot,
           harnesses: activeHarnesses,
           useSymlinks: parsed.symlinkInstructionFiles,
+          variant: promptVariant,
         });
         const summary = Object.entries(agentInstructionsReport.harnesses)
           .map(([k, v]) => `${k}=${v}`).join(' ');
         const canonical = agentInstructionsReport.canonical
           ? ` (canonical=${agentInstructionsReport.canonical})` : '';
-        process.stderr.write(`[init] Agent instructions: ${summary || '(none)'}${canonical}\n`);
+        const variantTag = promptVariant === 'mcp' ? ' [mcp variant]' : '';
+        process.stderr.write(`[init] Agent instructions: ${summary || '(none)'}${canonical}${variantTag}\n`);
       } catch (err) {
         process.stderr.write(`[init] Warning: Agent-instruction injection failed: ${err.message}\n`);
       }
-      // Claude rules file is only useful when claude-code is enabled — the
-      // sole load path is the @.claude/rules/sweet-search.md import line that
-      // injectAgentInstructions writes into CLAUDE.md.
+      // Claude rules file is only useful when claude-code is enabled AND the
+      // CLI is the contact surface — its sole load path is the
+      // @.claude/rules/sweet-search.md import line that injectAgentInstructions
+      // writes into CLAUDE.md (omitted in the --no-cli MCP variant), and its
+      // body is written in ss-* CLI terms. Under --no-cli we TEAR DOWN any rules
+      // file a prior CLI init wrote (idempotent: not-found when absent) so a
+      // cli→mcp re-init never leaves a stale ss-* supplement contradicting the
+      // injected MCP prompt.
       if (activeHarnesses.includes('claude-code')) {
         try {
-          const status = writeClaudeRules({ projectRoot });
-          claudeRulesReport = { status };
-          process.stderr.write(`[init] Claude rules: ${status}\n`);
+          if (parsed.noCli) {
+            const status = removeClaudeRules({ projectRoot });
+            claudeRulesReport = { status };
+            if (status === 'removed' || parsed.verbose) {
+              process.stderr.write(`[init] Claude rules: ${status}${status === 'removed' ? ' (--no-cli — stale ss-* CLI supplement torn down)' : ' (--no-cli)'}\n`);
+            }
+          } else {
+            const status = writeClaudeRules({ projectRoot });
+            claudeRulesReport = { status };
+            process.stderr.write(`[init] Claude rules: ${status}\n`);
+          }
         } catch (err) {
-          process.stderr.write(`[init] Warning: Could not write Claude rules: ${err.message}\n`);
+          process.stderr.write(`[init] Warning: Claude rules ${parsed.noCli ? 'teardown' : 'write'} failed: ${err.message}\n`);
         }
       }
     }
@@ -1968,15 +2074,26 @@ export async function runInit(args) {
   //     `.claude/hooks/sweet-search-remind-tools.mjs` with a
   //     `hooks.UserPromptSubmit` entry in `.claude/settings.json` keyed by
   //     filename so re-init updates rather than duplicates.
+  //     Under --no-cli the reminder body (ss-* CLI Bash commands) contradicts
+  //     the injected MCP-variant prompt, so we TEAR DOWN any reminder hook a
+  //     prior CLI init installed (idempotent: not-found when absent) rather
+  //     than merely skipping the install. An MCP-variant reminder is a follow-up.
   let promptReminderReport = null;
   if (!parsed.noClaude) {
-    promptReminderReport = installPromptReminderHook({
-      projectRoot,
-      packageRoot: PACKAGE_ROOT,
-      skipped: parsed.skipPromptReminders,
-    });
-    if (parsed.verbose || promptReminderReport.status === 'error') {
-      process.stderr.write(`[init] Prompt reminder hook: ${promptReminderReport.status} — ${promptReminderReport.detail}\n`);
+    if (parsed.noCli) {
+      promptReminderReport = removePromptReminderHook({ projectRoot });
+      if (parsed.verbose || promptReminderReport.status === 'error') {
+        process.stderr.write(`[init] Prompt reminder hook: ${promptReminderReport.status} (--no-cli) — ${promptReminderReport.detail}\n`);
+      }
+    } else {
+      promptReminderReport = installPromptReminderHook({
+        projectRoot,
+        packageRoot: PACKAGE_ROOT,
+        skipped: parsed.skipPromptReminders,
+      });
+      if (parsed.verbose || promptReminderReport.status === 'error') {
+        process.stderr.write(`[init] Prompt reminder hook: ${promptReminderReport.status} — ${promptReminderReport.detail}\n`);
+      }
     }
   }
 
@@ -1984,15 +2101,26 @@ export async function runInit(args) {
   //     `--enforce-tools`; universal `--no-claude` gate above. Adds
   //     `permissions.deny: ["Grep"]` and a PreToolUse hint hook for `Read`
   //     in `.claude/settings.json`. Strict + opinionated; off by default.
+  //     Under --no-cli the Read hint points at ss-read / ss-semantic (CLI
+  //     surface) and denying native Grep is moot when MCP `search` is the
+  //     contact surface — so we TEAR DOWN any enforcement a prior CLI init
+  //     wrote (idempotent: not-found when absent) instead of merely skipping.
   let toolEnforcementReport = null;
   if (!parsed.noClaude) {
-    toolEnforcementReport = installToolEnforcement({
-      projectRoot,
-      packageRoot: PACKAGE_ROOT,
-      skipped: !parsed.enforceTools,
-    });
-    if (parsed.verbose || toolEnforcementReport.status === 'error') {
-      process.stderr.write(`[init] Tool enforcement: ${toolEnforcementReport.status} — ${toolEnforcementReport.detail}\n`);
+    if (parsed.noCli) {
+      toolEnforcementReport = removeToolEnforcement({ projectRoot });
+      if (parsed.verbose || toolEnforcementReport.status === 'error') {
+        process.stderr.write(`[init] Tool enforcement: ${toolEnforcementReport.status} (--no-cli)${toolEnforcementReport.detail ? ` — ${toolEnforcementReport.detail}` : ''}\n`);
+      }
+    } else {
+      toolEnforcementReport = installToolEnforcement({
+        projectRoot,
+        packageRoot: PACKAGE_ROOT,
+        skipped: !parsed.enforceTools,
+      });
+      if (parsed.verbose || toolEnforcementReport.status === 'error') {
+        process.stderr.write(`[init] Tool enforcement: ${toolEnforcementReport.status} — ${toolEnforcementReport.detail}\n`);
+      }
     }
   }
 
@@ -2014,6 +2142,7 @@ export async function runInit(args) {
     claudeRulesReport,
     promptReminderReport,
     toolEnforcementReport,
+    mcpServerReport,
   });
 }
 

package/scripts/inject-agent-instructions.js

@@ -63,20 +63,27 @@ function escapeRegex(s) {
 
 const SHIP_FILE_REL = 'core/prompt-optimization/data/p7-final/sweet-search-system-prompt.md';
 
+// MCP-tool variant of the policy (init --mcp --no-cli). Same strategy core; the
+// tool-mechanics layer is remapped from the ss-* CLI surface onto the
+// sweet-search MCP tool surface. Read lazily — only the variant actually
+// requested needs to exist, so importing this module never requires the MCP
+// ship-file to be present.
+const MCP_SHIP_FILE_REL = 'core/prompt-optimization/data/p7-final/sweet-search-system-prompt-mcp.md';
+
 /** Strip a leading YAML front-matter block (`---\n … \n---\n`) if present. */
 export function stripFrontMatter(text) {
   return text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '');
 }
 
-function readShippedPolicy() {
+function readShippedPolicy(rel = SHIP_FILE_REL, { label = 'M++' } = {}) {
   const here = dirname(fileURLToPath(import.meta.url)); // <pkg>/scripts
-  const shipPath = join(here, '..', SHIP_FILE_REL);
+  const shipPath = join(here, '..', rel);
   let raw;
   try {
     raw = readFileSync(shipPath, 'utf8');
   } catch (err) {
     throw new Error(
-      `inject-agent-instructions: cannot read the M++ ship-file at ${shipPath}. ` +
+      `inject-agent-instructions: cannot read the ${label} ship-file at ${shipPath}. ` +
       'It MUST be present (packaged via package.json "files"). Regenerate with ' +
       '`node core/prompt-optimization/sweep/finalize-mpp.mjs`. ' +
       `Cause: ${err.message}`,
@@ -84,13 +91,31 @@ function readShippedPolicy() {
   }
   const body = stripFrontMatter(raw).trimEnd();
   if (!body) {
-    throw new Error(`inject-agent-instructions: M++ ship-file at ${shipPath} has an empty body.`);
+    throw new Error(`inject-agent-instructions: ${label} ship-file at ${shipPath} has an empty body.`);
   }
   return body;
 }
 
 export const CANONICAL_POLICY_BODY = readShippedPolicy();
 
+let _mcpPolicyBody = null;
+/** Lazily read + cache the MCP-variant policy body. */
+export function getMcpPolicyBody() {
+  if (_mcpPolicyBody == null) {
+    _mcpPolicyBody = readShippedPolicy(MCP_SHIP_FILE_REL, { label: 'M++ (MCP variant)' });
+  }
+  return _mcpPolicyBody;
+}
+
+/**
+ * Resolve the policy body for a contact-surface variant.
+ *   'cli' (default) → the frozen ss-* CLI champion (CANONICAL_POLICY_BODY)
+ *   'mcp'           → the MCP-tool variant (init --mcp --no-cli)
+ */
+export function getPolicyBody(variant = 'cli') {
+  return variant === 'mcp' ? getMcpPolicyBody() : CANONICAL_POLICY_BODY;
+}
+
 const CURSOR_FRONTMATTER = `---
 description: Sweet Search tool-routing, stopping, and citation policy
 alwaysApply: false
@@ -111,12 +136,12 @@ function wrapMarker(body) {
  * full policy plus, for CLAUDE.md, an extra `@.claude/rules/sweet-search.md`
  * import line so the Claude-specific shim is loaded.
  */
-export function buildCanonicalBlock({ extraImports = [] } = {}) {
+export function buildCanonicalBlock({ extraImports = [], policyBody = CANONICAL_POLICY_BODY } = {}) {
   if (extraImports.length === 0) {
-    return wrapMarker(CANONICAL_POLICY_BODY);
+    return wrapMarker(policyBody);
   }
   const importLines = extraImports.map(t => `@${t}`).join('\n');
-  return wrapMarker(`${CANONICAL_POLICY_BODY}\n${importLines}\n`);
+  return wrapMarker(`${policyBody}\n${importLines}\n`);
 }
 
 /**
@@ -133,8 +158,8 @@ export function buildImportBlock({ importTargets }) {
 }
 
 /** Body for the cursor .mdc (frontmatter + inlined canonical body). */
-export function buildCursorFile() {
-  return CURSOR_FRONTMATTER + wrapMarker(CANONICAL_POLICY_BODY);
+export function buildCursorFile(policyBody = CANONICAL_POLICY_BODY) {
+  return CURSOR_FRONTMATTER + wrapMarker(policyBody);
 }
 
 // ─── Marker injection ───────────────────────────────────────────────────────
@@ -265,26 +290,36 @@ export function injectAgentInstructions({
   projectRoot,
   harnesses = ALL_HARNESSES,
   useSymlinks = true,
+  variant = 'cli',
 } = {}) {
   if (!projectRoot) throw new TypeError('inject-agent-instructions: projectRoot is required');
   const enabled = new Set(harnesses);
-  const report = { harnesses: {}, canonical: null };
+  const report = { harnesses: {}, canonical: null, variant };
 
   if (enabled.size === 0) return report;
 
+  // Variant selects the policy body. The MCP variant retargets every ss-* CLI
+  // reference onto the sweet-search MCP tool surface; it also drops the Claude
+  // `@.claude/rules/sweet-search.md` import because that supplement is written
+  // in ss-* CLI terms and would contradict the MCP body (the CLI rules file is
+  // skipped under --no-cli in init too).
+  const policyBody = getPolicyBody(variant);
+  const claudeExtraImports = variant === 'mcp' ? [] : ['.claude/rules/sweet-search.md'];
+
   // 1. Canonical file: CLAUDE.md when Claude Code is enabled, else AGENTS.md.
-  //    Body is the full policy plus (Claude-only) the @.claude/rules import.
+  //    Body is the full policy plus (Claude-only, CLI variant) the @.claude/rules import.
   let canonicalFile;
   let canonicalBlock;
   if (enabled.has('claude-code')) {
     canonicalFile = CLAUDE_FILE;
     canonicalBlock = buildCanonicalBlock({
-      extraImports: ['.claude/rules/sweet-search.md'],
+      extraImports: claudeExtraImports,
+      policyBody,
     });
     report.canonical = 'claude-code';
   } else if (enabled.has('agents') || enabled.has('gemini') || enabled.has('cursor')) {
     canonicalFile = AGENTS_FILE;
-    canonicalBlock = buildCanonicalBlock();
+    canonicalBlock = buildCanonicalBlock({ policyBody });
     report.canonical = 'agents'; // AGENTS.md is the multi-harness convention (Codex, OpenCode, …)
   } else {
     return report; // no canonical, nothing to write
@@ -343,12 +378,12 @@ export function injectAgentInstructions({
       // and any user notes outside the markers.
       report.harnesses.cursor = injectMarkerBlock({
         filePath: cursorPath,
-        block: buildCanonicalBlock(),
+        block: buildCanonicalBlock({ policyBody }),
       });
     } else {
       // Fresh file — write frontmatter + canonical body in marker block.
       mkdirSync(dirname(cursorPath), { recursive: true });
-      writeFileSync(cursorPath, buildCursorFile());
+      writeFileSync(cursorPath, buildCursorFile(policyBody));
       report.harnesses.cursor = 'created';
     }
   }

package/scripts/install-mcp-server.js

@@ -0,0 +1,122 @@
+/**
+ * Project-local MCP server registration for sweet-search.
+ *
+ * `sweet-search init --mcp` writes a `sweet-search` entry into the project's
+ * root `.mcp.json` — the project-scoped MCP config read by Claude Code and other
+ * MCP hosts (see docs/search/MCP_INTEGRATION.md §`.mcp.json`). Additive and
+ * idempotent: existing servers and any other top-level keys are preserved; only
+ * `mcpServers.sweet-search` is created/updated.
+ *
+ * Design notes:
+ *  - This is ROOT-level and harness-agnostic. It is independent of `--no-claude`
+ *    (which gates `.claude/*` writes only). `.mcp.json` lives at the repo root.
+ *  - The MCP server is a thin adapter over the SAME engine the CLI wraps. `--mcp`
+ *    ADDS it; it never replaces the CLI. `--no-cli` only swaps the agent's
+ *    *contact surface* to MCP — indexing still runs through the CLI/engine.
+ *  - We never clobber an unparseable user `.mcp.json`; we fail loudly instead.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+export const MCP_CONFIG_FILE = '.mcp.json';
+export const MCP_SERVER_KEY = 'sweet-search';
+
+/**
+ * The canonical server entry. Uses `npx -y sweet-search-mcp` (the published bin)
+ * so the registration keeps working after a global/local install without a
+ * hard-coded path, and pins the target repo via `--project-root`.
+ */
+export function buildServerEntry({ projectRoot }) {
+  return {
+    command: 'npx',
+    args: ['-y', 'sweet-search-mcp', '--project-root', projectRoot],
+  };
+}
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function deepEqual(a, b) {
+  return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/**
+ * Install/update the sweet-search MCP server registration.
+ * Idempotent. Returns `{ status, path, detail? }` where status is one of:
+ *   'created'   — wrote a fresh .mcp.json
+ *   'added'     — file existed, added our server entry
+ *   'updated'   — our entry existed but differed; rewritten
+ *   'unchanged' — our entry already matches
+ *   'error'     — existing file is not a usable JSON object (left untouched)
+ */
+export function installMcpServer({ projectRoot, configFile = MCP_CONFIG_FILE } = {}) {
+  if (!projectRoot) throw new TypeError('install-mcp-server: projectRoot is required');
+  const configPath = join(projectRoot, configFile);
+  const entry = buildServerEntry({ projectRoot });
+
+  let config = {};
+  const existed = existsSync(configPath);
+  if (existed) {
+    let raw;
+    try {
+      raw = readFileSync(configPath, 'utf8');
+    } catch (err) {
+      return { status: 'error', path: configPath, detail: `cannot read ${configFile}: ${err.message}` };
+    }
+    try {
+      config = JSON.parse(raw);
+    } catch (err) {
+      return { status: 'error', path: configPath, detail: `existing ${configFile} is not valid JSON: ${err.message}` };
+    }
+    if (!isPlainObject(config)) {
+      return { status: 'error', path: configPath, detail: `existing ${configFile} is not a JSON object` };
+    }
+  }
+
+  if (!isPlainObject(config.mcpServers)) config.mcpServers = {};
+
+  const prev = config.mcpServers[MCP_SERVER_KEY];
+  if (prev && deepEqual(prev, entry)) {
+    return { status: 'unchanged', path: configPath };
+  }
+  const hadEntry = prev !== undefined;
+  config.mcpServers[MCP_SERVER_KEY] = entry;
+
+  mkdirSync(dirname(configPath), { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  return { status: existed ? (hadEntry ? 'updated' : 'added') : 'created', path: configPath };
+}
+
+/**
+ * Reverse `installMcpServer`. Removes only our `mcpServers.sweet-search` entry,
+ * preserving any other servers / top-level keys. Deletes the file outright only
+ * when it becomes wholly empty (no other servers, no other top-level keys).
+ * @returns 'removed' | 'file-deleted' | 'not-found' | 'dry-run'
+ */
+export function removeMcpServer({ projectRoot, configFile = MCP_CONFIG_FILE, dryRun = false } = {}) {
+  if (!projectRoot) throw new TypeError('remove-mcp-server: projectRoot is required');
+  const configPath = join(projectRoot, configFile);
+  if (!existsSync(configPath)) return 'not-found';
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return 'not-found'; // unparseable / not ours — never touch it
+  }
+  if (!isPlainObject(config) || !isPlainObject(config.mcpServers) || !(MCP_SERVER_KEY in config.mcpServers)) {
+    return 'not-found';
+  }
+  if (dryRun) return 'dry-run';
+
+  delete config.mcpServers[MCP_SERVER_KEY];
+  const hasOtherServers = Object.keys(config.mcpServers).length > 0;
+  const hasOtherKeys = Object.keys(config).some((k) => k !== 'mcpServers');
+  if (!hasOtherServers && !hasOtherKeys) {
+    unlinkSync(configPath);
+    return 'file-deleted';
+  }
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+  return 'removed';
+}

package/scripts/uninstall.js

@@ -20,6 +20,7 @@ import { getCoremlCascadeRoot, getCoremlCascadeState } from '../core/infrastruct
 import { PREWARM_HOOK_FILENAME } from './init.js';
 import { removeAgentInstructions } from './inject-agent-instructions.js';
 import { removeClaudeRules } from './write-claude-rules.js';
+import { removeMcpServer } from './install-mcp-server.js';
 import { removePromptReminderHook } from './install-prompt-reminders.js';
 import { removeToolEnforcement } from './install-tool-enforcement.js';
 import { projectSocketPath, projectPidFile } from '../core/search/server-identity.js';
@@ -711,11 +712,16 @@ export async function runUninstall(args) {
   const codexHookPreview = removeCodexSessionStartHook(projectRoot, { dryRun: true });
   const hasCodexHook = codexHookPreview.status === 'dry-run';
 
+  // MCP server registration (.mcp.json mcpServers.sweet-search), written by
+  // `init --mcp`.
+  const mcpServerPreview = removeMcpServer({ projectRoot, dryRun: true });
+  const hasMcpServer = mcpServerPreview === 'dry-run';
+
   // Nothing to remove?
   if (
     removals.length === 0 && !hasHookEntry && !hasSkillEntry && !hasIndexMaintainerHook
     && !agentInstructionsTouched && !hasClaudeRules
-    && !hasPromptReminder && !hasToolEnforcement && !hasCodexHook
+    && !hasPromptReminder && !hasToolEnforcement && !hasCodexHook && !hasMcpServer
   ) {
     console.log('Nothing to remove — Sweet Search is not initialized in this project.');
     return;
@@ -758,6 +764,9 @@ export async function runUninstall(args) {
   if (hasCodexHook) {
     console.log(`    Codex SessionStart hook (.codex/hooks.json)`);
   }
+  if (hasMcpServer) {
+    console.log(`    MCP server registration (.mcp.json — mcpServers.sweet-search)`);
+  }
   console.log(`  Total: ${formatBytes(totalBytes)}`);
   if (parsed.keepModels) {
     console.log('  Model cache: kept (--keep-models)');
@@ -783,6 +792,10 @@ export async function runUninstall(args) {
     if (dryCodex.status === 'dry-run') {
       console.log(`  Would also remove: Codex SessionStart hook (.codex/hooks.json — ${dryCodex.detail})`);
     }
+    const dryMcp = removeMcpServer({ projectRoot, dryRun: true });
+    if (dryMcp === 'dry-run') {
+      console.log(`  Would also remove: MCP server registration (.mcp.json — mcpServers.sweet-search)`);
+    }
     console.log('Dry run — nothing was removed.');
     return;
   }
@@ -949,6 +962,18 @@ export async function runUninstall(args) {
     kept++;
   }
 
+  // MCP server registration (.mcp.json mcpServers.sweet-search). Only our entry
+  // is removed; other servers and JSON keys are preserved.
+  const mcpServerResult = removeMcpServer({ projectRoot, dryRun: parsed.dryRun });
+  if (mcpServerResult === 'removed') {
+    console.log(`  Removed: MCP server registration (.mcp.json — mcpServers.sweet-search)`);
+    removed++;
+  } else if (mcpServerResult === 'file-deleted') {
+    console.log(`  Removed: .mcp.json (wholly sweet-search-managed)`);
+    removed++;
+  }
+  // 'not-found' / 'dry-run' are silent.
+
   // Purge npm packages
   if (parsed.purge) {
     console.log('');