diff --git a/.doctrine/project.json b/.doctrine/project.json
index ae25377..899af3f 100644
--- a/.doctrine/project.json
+++ b/.doctrine/project.json
@@ -1,155 +1,155 @@
 {
-  "schemaVersion": 1,
-  "project": {
-    "repo": "SylphxAI/coderag",
-    "name": "SylphxAI CodeRAG",
-    "lifecycle": "active",
-    "layer": "tooling",
-    "policyPool": "agent-tool",
-    "summary": "TypeScript/Bun monorepo for hybrid code search and an MCP server for AI assistant code retrieval.",
-    "goals": [
-      "Provide the @sylphx/coderag core package for hybrid TF-IDF, vector, AST chunking, indexing, and persistent search.",
-      "Provide the @sylphx/coderag-mcp package as an MCP server surface for AI assistants and IDEs.",
-      "Maintain docs, examples, tests, and package release workflows for the CodeRAG ecosystem."
-    ],
-    "nonGoals": [
-      "Own IDE products, AI assistant runtime policy, or downstream coding-agent behavior.",
-      "Own embedding provider accounts, external vector services, or customer-specific codebase indexes.",
-      "Own enterprise engineering doctrine, standards, or project manifest schema."
-    ]
-  },
-  "boundaries": {
-    "owns": [
-      {
-        "name": "coderag-core",
-        "description": "The core indexing, TF-IDF/vector search, AST chunking, embeddings, storage, cache, and language configuration packages under packages/core."
-      },
-      {
-        "name": "coderag-mcp-server",
-        "description": "The MCP server package, tool surface, installation docs, configuration docs, and integration examples under packages/mcp-server and docs/mcp."
-      }
-    ],
-    "doesNotOwn": [
-      "IDE products, assistant UX, model routing policy, or coding-agent runtime behavior.",
-      "Embedding provider accounts, external vector databases, or customer-specific codebase indexes.",
-      "Enterprise doctrine and manifest schema owned by SylphxAI/doctrine."
-    ],
-    "publicSurfaces": [
-      {
-        "type": "documentation",
-        "name": "Repository README",
-        "location": "README.md"
-      },
-      {
-        "type": "manifest",
-        "name": "Root package manifest and scripts",
-        "location": "package.json"
-      },
-      {
-        "type": "package",
-        "name": "@sylphx/coderag",
-        "location": "packages/core/"
-      },
-      {
-        "type": "package",
-        "name": "@sylphx/coderag-mcp",
-        "location": "packages/mcp-server/"
-      },
-      {
-        "type": "documentation",
-        "name": "Documentation site",
-        "location": "docs/"
-      },
-      {
-        "type": "documentation",
-        "name": "MCP integration docs",
-        "location": "docs/mcp/"
-      },
-      {
-        "type": "test",
-        "name": "Package tests",
-        "location": "packages/*/src/*.test.ts"
-      },
-      {
-        "type": "workflow",
-        "name": "CI and release workflows",
-        "location": ".github/workflows/"
-      }
-    ],
-    "allowedDependencies": [
-      {
-        "repo": "SylphxAI/doctrine",
-        "surface": "project manifest schema and engineering doctrine",
-        "direction": "peer-public"
-      },
-      {
-        "repo": "SylphxAI/.github",
-        "surface": "reusable release workflow",
-        "direction": "upstream-shared"
-      },
-      {
-        "repo": "SylphxAI/synth",
-        "surface": "parser packages for AST chunking",
-        "direction": "upstream-shared"
-      }
-    ],
-    "forbiddenCouplings": [
-      "Do not encode a specific IDE, assistant, model provider, or customer codebase policy into the core search engine.",
-      "Do not store or assume embedding provider credentials in package code or docs examples.",
-      "Do not fork doctrine standards into this repository."
-    ]
-  },
-  "documentation": {
-    "adr": {
-      "path": "docs/adr/",
-      "status": "planned"
-    },
-    "specs": {
-      "path": "docs/guide/",
-      "status": "present"
-    },
-    "catalog": {
-      "path": ".doctrine/project.json",
-      "status": "present"
-    },
-    "runbooks": {
-      "path": "docs/mcp/",
-      "status": "present"
-    },
-    "generatedReferences": {
-      "path": "docs/api/",
-      "status": "present"
-    }
-  },
-  "delivery": {
-    "ciModel": "legacy-ci",
-    "requiredContexts": [],
-    "deployPath": "Pull requests and merge queue run Bun/Turborepo CI; main-branch Release delegates to SylphxAI/.github reusable release workflow for package publication.",
-    "productionProof": "Passing typecheck, tests, package build, MCP smoke/config validation when MCP behavior changes, successful release workflow, and package-registry/docs readback for published versions.",
-    "recoveryClass": "forward-fix-only",
-    "deployable": false
-  },
-  "adoption": {
-    "status": "baseline",
-    "gaps": [
-      {
-        "id": "required-contexts-not-recorded",
-        "description": "CI exists for pull requests and merge queue, but required branch protection contexts are not recorded in this manifest baseline.",
-        "owner": "SylphxAI/coderag",
-        "target": "central ADR-29 required-context rollout or repo-local branch protection audit"
-      },
-      {
-        "id": "embedding-provider-boundary",
-        "description": "Optional vector search can involve provider credentials or external services; keep provider configuration outside package internals and validate through MCP/config tests.",
-        "owner": "SylphxAI/coderag",
-        "target": "next embedding-provider or MCP config change"
-      },
-      {
-        "id": "package-release-forward-fix",
-        "description": "Published package versions and MCP behavior are forward-only for consumers; add release recovery/runbook proof before production lifecycle promotion.",
-        "owner": "SylphxAI/coderag",
-        "target": "before production lifecycle promotion"
-      }
-    ]
-  }
+	"schemaVersion": 1,
+	"project": {
+		"repo": "SylphxAI/coderag",
+		"name": "SylphxAI CodeRAG",
+		"lifecycle": "active",
+		"layer": "tooling",
+		"policyPool": "agent-tool",
+		"summary": "TypeScript/Bun monorepo for hybrid code search and an MCP server for AI assistant code retrieval.",
+		"goals": [
+			"Provide the @sylphx/coderag core package for hybrid TF-IDF, vector, AST chunking, indexing, and persistent search.",
+			"Provide the @sylphx/coderag-mcp package as an MCP server surface for AI assistants and IDEs.",
+			"Maintain docs, examples, tests, and package release workflows for the CodeRAG ecosystem."
+		],
+		"nonGoals": [
+			"Own IDE products, AI assistant runtime policy, or downstream coding-agent behavior.",
+			"Own embedding provider accounts, external vector services, or customer-specific codebase indexes.",
+			"Own enterprise engineering doctrine, standards, or project manifest schema."
+		]
+	},
+	"boundaries": {
+		"owns": [
+			{
+				"name": "coderag-core",
+				"description": "The core indexing, TF-IDF/vector search, AST chunking, embeddings, storage, cache, and language configuration packages under packages/core."
+			},
+			{
+				"name": "coderag-mcp-server",
+				"description": "The MCP server package, tool surface, installation docs, configuration docs, and integration examples under packages/mcp-server and docs/mcp."
+			}
+		],
+		"doesNotOwn": [
+			"IDE products, assistant UX, model routing policy, or coding-agent runtime behavior.",
+			"Embedding provider accounts, external vector databases, or customer-specific codebase indexes.",
+			"Enterprise doctrine and manifest schema owned by SylphxAI/doctrine."
+		],
+		"publicSurfaces": [
+			{
+				"type": "documentation",
+				"name": "Repository README",
+				"location": "README.md"
+			},
+			{
+				"type": "manifest",
+				"name": "Root package manifest and scripts",
+				"location": "package.json"
+			},
+			{
+				"type": "package",
+				"name": "@sylphx/coderag",
+				"location": "packages/core/"
+			},
+			{
+				"type": "package",
+				"name": "@sylphx/coderag-mcp",
+				"location": "packages/mcp-server/"
+			},
+			{
+				"type": "documentation",
+				"name": "Documentation site",
+				"location": "docs/"
+			},
+			{
+				"type": "documentation",
+				"name": "MCP integration docs",
+				"location": "docs/mcp/"
+			},
+			{
+				"type": "test",
+				"name": "Package tests",
+				"location": "packages/*/src/*.test.ts"
+			},
+			{
+				"type": "workflow",
+				"name": "CI and release workflows",
+				"location": ".github/workflows/"
+			}
+		],
+		"allowedDependencies": [
+			{
+				"repo": "SylphxAI/doctrine",
+				"surface": "project manifest schema and engineering doctrine",
+				"direction": "peer-public"
+			},
+			{
+				"repo": "SylphxAI/.github",
+				"surface": "reusable release workflow",
+				"direction": "upstream-shared"
+			},
+			{
+				"repo": "SylphxAI/synth",
+				"surface": "parser packages for AST chunking",
+				"direction": "upstream-shared"
+			}
+		],
+		"forbiddenCouplings": [
+			"Do not encode a specific IDE, assistant, model provider, or customer codebase policy into the core search engine.",
+			"Do not store or assume embedding provider credentials in package code or docs examples.",
+			"Do not fork doctrine standards into this repository."
+		]
+	},
+	"documentation": {
+		"adr": {
+			"path": "docs/adr/",
+			"status": "planned"
+		},
+		"specs": {
+			"path": "docs/guide/",
+			"status": "present"
+		},
+		"catalog": {
+			"path": ".doctrine/project.json",
+			"status": "present"
+		},
+		"runbooks": {
+			"path": "docs/mcp/",
+			"status": "present"
+		},
+		"generatedReferences": {
+			"path": "docs/api/",
+			"status": "present"
+		}
+	},
+	"delivery": {
+		"ciModel": "legacy-ci",
+		"requiredContexts": [],
+		"deployPath": "Pull requests and merge queue run Bun/Turborepo CI; main-branch Release delegates to SylphxAI/.github reusable release workflow for package publication.",
+		"productionProof": "Passing typecheck, tests, package build, MCP smoke/config validation when MCP behavior changes, successful release workflow, and package-registry/docs readback for published versions.",
+		"recoveryClass": "forward-fix-only",
+		"deployable": false
+	},
+	"adoption": {
+		"status": "baseline",
+		"gaps": [
+			{
+				"id": "required-contexts-not-recorded",
+				"description": "CI exists for pull requests and merge queue, but required branch protection contexts are not recorded in this manifest baseline.",
+				"owner": "SylphxAI/coderag",
+				"target": "central ADR-29 required-context rollout or repo-local branch protection audit"
+			},
+			{
+				"id": "embedding-provider-boundary",
+				"description": "Optional vector search can involve provider credentials or external services; keep provider configuration outside package internals and validate through MCP/config tests.",
+				"owner": "SylphxAI/coderag",
+				"target": "next embedding-provider or MCP config change"
+			},
+			{
+				"id": "package-release-forward-fix",
+				"description": "Published package versions and MCP behavior are forward-only for consumers; add release recovery/runbook proof before production lifecycle promotion.",
+				"owner": "SylphxAI/coderag",
+				"target": "before production lifecycle promotion"
+			}
+		]
+	}
 }
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 20e3cf1..6129f0e 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,14 +23,38 @@ jobs:
       - name: Install dependencies
         run: bun install --frozen-lockfile
 
+      - name: Set up Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Build Rust retrieval core
+        run: cargo build --release
+
+      - name: Rust core tests
+        run: cargo test
+
+      - name: Golden retrieval evals
+        run: bun test test/golden-retrieval.test.ts
+
       - name: Type check
         run: bun run type-check
 
+      - name: Build packages
+        run: bun run build
+
       - name: Run tests
         run: bun run test
 
-      - name: Build packages
-        run: bun run build
+      - name: Public surface audit (README discovery)
+        run: bun run test:public-surface
+
+      - name: Public benchmark proof
+        run: bun run benchmark:public-proof
+
+      - name: Release gate
+        run: bun run benchmark:release-gate
+
+      - name: Docs build
+        run: bun run docs:build
 
       - name: Upload coverage
         uses: codecov/codecov-action@v4
diff --git a/.gitignore b/.gitignore
index 00971bb..48443e2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,5 @@
 node_modules/
+target/
 dist/
 *.log
 .DS_Store
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..cab3813
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,995 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "android_system_properties"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a4385e2e34eb35d6b3efe798b9eb88096925d87726c0798709bf56d9ed84af3"
+
+[[package]]
+name = "async-trait"
+version = "0.1.89"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bitflags"
+version = "2.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
+
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
+[[package]]
+name = "bumpalo"
+version = "3.20.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
+
+[[package]]
+name = "bytes"
+version = "1.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
+
+[[package]]
+name = "cc"
+version = "1.2.66"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f5d6cac793997bd970000024b2934968efe83b382de4fdcf4fcb46b6ee4ad996"
+dependencies = [
+ "find-msvc-tools",
+ "shlex",
+]
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "chrono"
+version = "0.4.45"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1aa79e62e7697b8e29b513a68abacf485adcd1fe8284a4316c5ae868e6633327"
+dependencies = [
+ "iana-time-zone",
+ "js-sys",
+ "num-traits",
+ "serde",
+ "wasm-bindgen",
+ "windows-link",
+]
+
+[[package]]
+name = "coderag-cli"
+version = "0.1.0"
+dependencies = [
+ "coderag-core",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "coderag-core"
+version = "0.1.0"
+dependencies = [
+ "regex",
+ "serde",
+ "serde_json",
+ "sha2",
+ "walkdir",
+]
+
+[[package]]
+name = "coderag-mcp-server"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "coderag-core",
+ "rmcp",
+ "serde",
+ "serde_json",
+ "tokio",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "darling"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "25ae13da2f202d56bd7f91c25fba009e7717a1e4a1cc98a76d844b65ae912e9d"
+dependencies = [
+ "darling_core",
+ "darling_macro",
+]
+
+[[package]]
+name = "darling_core"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9865a50f7c335f53564bb694ef660825eb8610e0a53d3e11bf1b0d3df31e03b0"
+dependencies = [
+ "ident_case",
+ "proc-macro2",
+ "quote",
+ "strsim",
+ "syn",
+]
+
+[[package]]
+name = "darling_macro"
+version = "0.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3984ec7bd6cfa798e62b4a642426a5be0e68f9401cfc2a01e3fa9ea2fcdb8d"
+dependencies = [
+ "darling_core",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
+[[package]]
+name = "dyn-clone"
+version = "1.0.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0881ea181b1df73ff77ffaaf9c7544ecc11e82fba9b5f27b262a3c73a332555"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
+
+[[package]]
+name = "futures"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b147ee9d1f6d097cef9ce628cd2ee62288d963e16fb287bd9286455b241382d"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-executor",
+ "futures-io",
+ "futures-sink",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-channel"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07bbe89c50d7a535e539b8c17bc0b49bdb77747034daa8087407d655f3f7cc1d"
+dependencies = [
+ "futures-core",
+ "futures-sink",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7e3450815272ef58cec6d564423f6e755e25379b217b0bc688e295ba24df6b1d"
+
+[[package]]
+name = "futures-executor"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "baf29c38818342a3b26b5b923639e7b1f4a61fc5e76102d4b1981c6dc7a7579d"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "futures-util",
+]
+
+[[package]]
+name = "futures-io"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cecba35d7ad927e23624b22ad55235f2239cfa44fd10428eecbeba6d6a717718"
+
+[[package]]
+name = "futures-macro"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e835b70203e41293343137df5c0664546da5745f82ec9b84d40be8336958447b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "futures-sink"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c39754e157331b013978ec91992bde1ac089843443c49cbc7f46150b0fad0893"
+
+[[package]]
+name = "futures-task"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "037711b3d59c33004d3856fbdc83b99d4ff37a24768fa1be9ce3538a1cde4393"
+
+[[package]]
+name = "futures-util"
+version = "0.3.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "389ca41296e6190b48053de0321d02a77f32f8a5d2461dd38762c0593805c6d6"
+dependencies = [
+ "futures-channel",
+ "futures-core",
+ "futures-io",
+ "futures-macro",
+ "futures-sink",
+ "futures-task",
+ "memchr",
+ "pin-project-lite",
+ "slab",
+]
+
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
+[[package]]
+name = "iana-time-zone"
+version = "0.1.65"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e31bc9ad994ba00e440a8aa5c9ef0ec67d5cb5e5cb0cc7f8b744a35b389cc470"
+dependencies = [
+ "android_system_properties",
+ "core-foundation-sys",
+ "iana-time-zone-haiku",
+ "js-sys",
+ "log",
+ "wasm-bindgen",
+ "windows-core",
+]
+
+[[package]]
+name = "iana-time-zone-haiku"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f31827a206f56af32e590ba56d5d2d085f558508192593743f16b2306495269f"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "ident_case"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e0384b61958566e926dc50660321d12159025e767c18e043daf26b70104c39"
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "js-sys"
+version = "0.3.103"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "53b44bfcdb3f8d5837a46dae1ca9660a837176eee74a28b229bc626816589102"
+dependencies = [
+ "cfg-if",
+ "futures-util",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.186"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66"
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.33"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "mio"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "02bd0af71c67b473010cbbc60715ee815645a4dc942899111f494b4b737d6fda"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link",
+]
+
+[[package]]
+name = "pastey"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.46"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbc457d0c7a0759a614551b11a6409e5951f6c7537be1f1b7682b9ae9230368"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "ref-cast"
+version = "1.0.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f354300ae66f76f1c85c5f84693f0ce81d747e2c3f21a45fef496d89c960bf7d"
+dependencies = [
+ "ref-cast-impl",
+]
+
+[[package]]
+name = "ref-cast-impl"
+version = "1.0.25"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7186006dcb21920990093f30e3dea63b7d6e977bf1256be20c3563a5db070da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "regex"
+version = "1.12.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1292b7759ae1cb9ec195452d1390a074f0cd8541ab7a5a8c31cd6db45d4a6ba"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6e1dd4122fc1595e8162618945476892eefca7b88c52820e74af6262213cae8f"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
+
+[[package]]
+name = "rmcp"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc4c9c94680f75470ee8083a0667988b5d7b5beb70b9f998a8e51de7c682ce60"
+dependencies = [
+ "async-trait",
+ "base64",
+ "chrono",
+ "futures",
+ "pastey",
+ "pin-project-lite",
+ "rmcp-macros",
+ "schemars",
+ "serde",
+ "serde_json",
+ "thiserror",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
+[[package]]
+name = "rmcp-macros"
+version = "0.16.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "90c23c8f26cae4da838fbc3eadfaecf2d549d97c04b558e7bd90526a9c28b42a"
+dependencies = [
+ "darling",
+ "proc-macro2",
+ "quote",
+ "serde_json",
+ "syn",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "schemars"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2b42f36aa1cd011945615b92222f6bf73c599a102a300334cd7f8dbeec726cc"
+dependencies = [
+ "chrono",
+ "dyn-clone",
+ "ref-cast",
+ "schemars_derive",
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "schemars_derive"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7d115b50f4aaeea07e79c1912f645c7513d81715d0420f8bc77a18c6260b307f"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "serde_derive_internals",
+ "syn",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_derive_internals"
+version = "0.29.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "18d26a20a969b9e3fdf2fc2d9f21eda6c40e2de84c9408bb5d3b05d499aae711"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.150"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e8014e44b4736ed0538adeecded0fce2a272f22dc9578a7eb6b2d9993c74cfb9"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "shlex"
+version = "2.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "slab"
+version = "0.4.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
+
+[[package]]
+name = "smallvec"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
+
+[[package]]
+name = "socket2"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "52d1cfed4120b4d927bf7c0f86d2087a4a7d6027c906d9f9d525a80573b9be51"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "syn"
+version = "2.0.118"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4288b5bcbc7920c07a1149a35cf9590a2aa808e0bc1eafaade0b80947865fbc4"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ebc4ee7f67670e9b64d05fa4253e753e016c6c95ff35b89b7941d6b856dec1d5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tokio"
+version = "1.52.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8fc7f01b389ac15039e4dc9531aa973a135d7a4135281b12d7c1bc79fd57fffe"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "parking_lot",
+ "pin-project-lite",
+ "signal-hook-registry",
+ "socket2",
+ "tokio-macros",
+ "windows-sys",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.7.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "385a6cb71ab9ab790c5fe8d67f1645e6c450a7ce006a33de03daa956cf70a496"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tokio-util"
+version = "0.7.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ae9cec805b01e8fc3fd2fe289f89149a9b66dd16786abd8b19cfa7b48cb0098"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "futures-sink",
+ "pin-project-lite",
+ "tokio",
+]
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-attributes",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-attributes"
+version = "0.1.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7490cfa5ec963746568740651ac6781f701c9c5ea257c58e057f3ba8cf69e8da"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
+
+[[package]]
+name = "version_check"
+version = "0.9.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b067c0c11094aef6b7a801c1e34a26affafdf3d051dba08456b868789aaf9a4"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "167ce5e579f6bcf889c4f7175a8a5a585de84e8ff93976ce393efa5f2837aab1"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f3997c7839262f4ef12cf90b818d6340c18e80f263f1a94bf157d0ec4420380e"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.126"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc1b4cb0cc549fcf58d7dfc081778139b3d283a081644e833e84682ad71cea24"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.62.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8e83a14d34d0623b51dce9581199302a221863196a1dde71a7663a4c2be9deb"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-result"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7781fa89eaf60850ac3d2da7af8e5242a5ea78d1a11c49bf2910bb5a73853eb5"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7837d08f69c77cf6b07689544538e017c1bfcf57e34b4c0ff58e6c2cd3b37091"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa"
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..8b32fde
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,12 @@
+[workspace]
+members = [
+    "crates/coderag-core",
+    "crates/coderag-cli",
+    "crates/coderag-mcp-server",
+]
+resolver = "2"
+
+[workspace.package]
+edition = "2021"
+license = "MIT"
+repository = "https://github.com/SylphxAI/coderag"
\ No newline at end of file
diff --git a/README.md b/README.md
index 4df3be3..96ae611 100644
--- a/README.md
+++ b/README.md
@@ -2,474 +2,263 @@
 
 # CodeRAG
 
-**Lightning-fast hybrid code search for AI assistants**
+### Your agent searched the codebase. **Did it find the right code?**
+
+Local-first hybrid code search for AI assistants. One MCP call indexes your repo
+and returns **semantic chunks** — functions, classes, and methods — not noisy
+grep dumps or slow cloud pipelines.
 
 [![npm version](https://img.shields.io/npm/v/@sylphx/coderag?style=flat-square&label=core)](https://www.npmjs.com/package/@sylphx/coderag)
 [![npm version](https://img.shields.io/npm/v/@sylphx/coderag-mcp?style=flat-square&label=mcp)](https://www.npmjs.com/package/@sylphx/coderag-mcp)
 [![CI](https://img.shields.io/github/actions/workflow/status/SylphxAI/coderag/ci.yml?style=flat-square)](https://github.com/SylphxAI/coderag/actions)
 [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
 
-**Zero dependencies** • **<50ms search** • **Hybrid TF-IDF + Vector** • **MCP ready**
+**Local-first** · **MCP-first** · **Hybrid TF-IDF + Vector** · **~200 tests** · **Reproducible benchmark**
 
-[Quick Start](#-quick-start) • [Features](#-features) • [MCP Setup](#-mcp-server-setup) • [Roadmap](docs/roadmap/sota-family-roadmap.md) • [API](#-api-reference)
+[⭐ Star this repo](https://github.com/SylphxAI/coderag) if agents should find code with evidence, not guess from keyword hits.
+· [Quick start](#quick-start) · [See it work](#see-it-work) · [Why not grep alone?](#why-not-grep-alone)
+· [Roadmap](docs/roadmap/sota-family-roadmap.md)
 
 </div>
 
 ---
 
-## Why CodeRAG?
+## The problem
 
-Traditional code search tools are either **slow** (full-text grep), **inaccurate** (keyword matching), or **complex** (require external services).
+Agents search codebases thousands of times per session. Most paths give you one
+of two bad outcomes:
 
-CodeRAG is different:
+1. **grep/ripgrep** — fast, but literal. Misses `authenticateUser` when you ask
+   for "login flow". Returns whole files, not the function you need.
+2. **Cloud RAG** — semantic, but needs Docker, vector DBs, embedding APIs, and
+   10–30s cold starts before the first search.
 
-```
-❌ Old way: Docker + ChromaDB + Ollama + 30 second startup
-✅ CodeRAG: npx @sylphx/coderag-mcp (instant)
-```
+The model still guesses which snippet matters. Wrong chunk → wrong patch → wasted
+context.
 
-| Feature | grep/ripgrep | Cloud RAG | CodeRAG |
-|---------|-------------|-----------|---------|
-| **Semantic understanding** | ❌ | ✅ | ✅ |
-| **Zero external deps** | ✅ | ❌ | ✅ |
-| **Offline support** | ✅ | ❌ | ✅ |
-| **Startup time** | Instant | 10-30s | <1s |
-| **Search latency** | ~100ms | ~500ms | <50ms |
+**CodeRAG is built for the moment your agent needs the right code block, not a
+directory of keyword hits.**
 
----
+## Why not grep alone?
 
-## ✨ Features
-
-### Search
-- 🔍 **Hybrid Search** - TF-IDF + optional vector embeddings
-- 🧠 **StarCoder2 Tokenizer** - Code-aware tokenization (4.7MB, trained on code)
-- 📊 **Smoothed IDF** - No term gets ignored, stable ranking
-- ⚡ **<50ms Latency** - Instant results even on large codebases
-
-### Indexing
-- 🚀 **1000-2000 files/sec** - Fast initial indexing
-- 💾 **SQLite Persistence** - Instant startup (<100ms) with cached index
-- ⚡ **Incremental Updates** - Smart diff detection, no full rebuilds
-- 👁️ **File Watching** - Real-time index updates on file changes
+| | grep/ripgrep | Cloud RAG | CodeRAG |
+| --- | --- | --- | --- |
+| **Semantic understanding** | ❌ Literal match | ✅ Embeddings | ✅ TF-IDF + optional vectors |
+| **Zero external deps** | ✅ | ❌ Vector DB + embed API | ✅ Local by default |
+| **Offline support** | ✅ | ❌ | ✅ |
+| **Result shape** | Whole files / lines | Often whole files | AST chunks (functions, classes) |
+| **Agent setup** | Shell tool | Docker + services | `npx @sylphx/coderag-mcp` |
 
-### Integration
-- 📦 **MCP Server** - Works with Claude Desktop, Cursor, VS Code, Windsurf
-- 🧠 **Vector Search** - Optional OpenAI embeddings for semantic search
-- 🌳 **AST Chunking** - Smart code splitting using [Synth](https://github.com/SylphxAI/synth) parsers (15+ languages)
-- 💻 **Low Memory Mode** - SQL-based search for resource-constrained environments
+Search latency and indexing throughput: reproduce with
+[`bun run benchmark:public-proof`](#benchmark-proof) — do not trust hand-waved
+ms claims.
 
----
+Full comparison: [how search works](docs/guide/how-search-works.md).
 
-## 🚀 Quick Start
+## See it work
 
-### Option 1: MCP Server (Recommended for AI Assistants)
+**Install once. Point at your repo.**
 
 ```bash
-npx @sylphx/coderag-mcp --root=/path/to/project
+claude mcp add coderag -- npx @sylphx/coderag-mcp --root=/absolute/path/to/project
 ```
 
-Or add to your MCP config:
+Search with the `codebase_search` tool:
 
 ```json
 {
-  "mcpServers": {
-    "coderag": {
-      "command": "npx",
-      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
-    }
-  }
+  "query": "user authentication login",
+  "limit": 5,
+  "file_extensions": [".ts", ".tsx"],
+  "exclude_paths": ["node_modules", "dist"]
 }
 ```
 
-See [MCP Server Setup](#-mcp-server-setup) for Claude Desktop, Cursor, VS Code, etc.
-
-### Option 2: As a Library
+Returns ranked chunks — not entire files:
 
-```bash
-npm install @sylphx/coderag
-# or
-bun add @sylphx/coderag
-```
+```markdown
+# Search: "user authentication login" (3 results)
 
+## src/auth/login.ts:1-12
 ```typescript
-import { CodebaseIndexer, PersistentStorage } from '@sylphx/coderag'
-
-// Create indexer with persistent storage
-const storage = new PersistentStorage({ codebaseRoot: './my-project' })
-const indexer = new CodebaseIndexer({
-  codebaseRoot: './my-project',
-  storage,
-})
-
-// Index codebase (instant on subsequent runs)
-await indexer.index({ watch: true })
-
-// Search
-const results = await indexer.search('authentication logic', { limit: 10 })
-console.log(results)
-// [{ path: 'src/auth/login.ts', score: 0.87, matchedTerms: ['authentication', 'logic'], snippet: '...' }]
-```
-
----
-
-## 📦 Packages
-
-| Package | Description | Install |
-|---------|-------------|---------|
-| [@sylphx/coderag](./packages/core) | Core search library | `npm i @sylphx/coderag` |
-| [@sylphx/coderag-mcp](./packages/mcp-server) | MCP server for AI assistants | `npx @sylphx/coderag-mcp` |
-
----
-
-## 🔌 MCP Server Setup
-
-### Claude Desktop
-
-Add to `claude_desktop_config.json`:
-
-**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
-
-```json
-{
-  "mcpServers": {
-    "coderag": {
-      "command": "npx",
-      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
-    }
-  }
+export async function authenticate(username: string, password: string) {
+  const user = await findUserByEmail(username)
+  return validatePassword(user, password)
 }
 ```
+```
 
-### Cursor
-
-Add to `~/.cursor/mcp.json` (macOS) or `%USERPROFILE%\.cursor\mcp.json` (Windows):
+## Why agents use it
 
-```json
-{
-  "mcpServers": {
-    "coderag": {
-      "command": "npx",
-      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
-    }
-  }
-}
-```
+| Need | What you get |
+| --- | --- |
+| Find implementation | AST chunks at semantic boundaries (functions, classes, methods) |
+| Keyword + meaning | Hybrid TF-IDF with optional OpenAI embeddings |
+| Fast iteration | Local index, incremental updates, file watching |
+| Low setup | MCP server via `npx` — no Docker or ChromaDB required |
+| Ship with proof | ~200 tests, reproducible public benchmark script |
 
-### VS Code
+## Quick Start
 
-Add to VS Code settings (JSON) or `.vscode/mcp.json`:
+### Claude Code (recommended)
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "coderag": {
-        "command": "npx",
-        "args": ["-y", "@sylphx/coderag-mcp", "--root=${workspaceFolder}"]
-      }
-    }
-  }
-}
+```bash
+claude mcp add coderag -- npx @sylphx/coderag-mcp --root=/absolute/path/to/project
 ```
 
-### Windsurf
+### Claude Desktop
 
-Add to `~/.codeium/windsurf/mcp_config.json`:
+Add to `claude_desktop_config.json`:
 
 ```json
 {
   "mcpServers": {
     "coderag": {
       "command": "npx",
-      "args": ["-y", "@sylphx/coderag-mcp", "--root=/path/to/project"]
+      "args": ["-y", "@sylphx/coderag-mcp", "--root=/absolute/path/to/project"]
     }
   }
 }
 ```
 
-### Claude Code
+### Any MCP Client
 
 ```bash
-claude mcp add coderag -- npx -y @sylphx/coderag-mcp --root=/path/to/project
-```
-
----
-
-## 🛠️ MCP Tool: `codebase_search`
-
-Search project source files with hybrid TF-IDF + vector ranking.
-
-### Parameters
-
-| Parameter | Type | Required | Default | Description |
-|-----------|------|----------|---------|-------------|
-| `query` | string | Yes | - | Search query |
-| `limit` | number | No | 10 | Max results |
-| `include_content` | boolean | No | true | Include code snippets |
-| `file_extensions` | string[] | No | - | Filter by extension (e.g., `[".ts", ".tsx"]`) |
-| `path_filter` | string | No | - | Filter by path pattern |
-| `exclude_paths` | string[] | No | - | Exclude paths (e.g., `["node_modules", "dist"]`) |
-
-### Example
-
-```json
-{
-  "query": "user authentication login",
-  "limit": 5,
-  "file_extensions": [".ts", ".tsx"],
-  "exclude_paths": ["node_modules", "dist", "test"]
-}
-```
-
-### Response Format
-
-LLM-optimized output (minimal tokens, maximum content):
-
-```markdown
-# Search: "user authentication login" (3 results)
-
-## src/auth/login.ts:15-28
-```typescript
-15: export async function authenticate(credentials) {
-16:   const user = await findUser(credentials.email)
-17:   return validatePassword(user, credentials.password)
-18: }
+npx @sylphx/coderag-mcp --root=/absolute/path/to/project
 ```
 
-## src/middleware/auth.ts:42-55 [md→typescript]
-```typescript
-42: // Embedded code from markdown docs
-43: const authMiddleware = (req, res, next) => {
-```
-
-## src/utils/large.ts:1-200 [truncated]
-```typescript
-1: // First 70% shown...
+Need Cursor, VS Code, Windsurf, or library usage? See the
+[installation guide](docs/guide/installation.md) and [MCP docs](docs/mcp/overview.md).
 
-... [800 chars truncated] ...
+### As a Library
 
-195: // Last 20% shown
-```
+```bash
+bun add @sylphx/coderag
 ```
 
----
-
-## 📚 API Reference
-
-### `CodebaseIndexer`
-
-Main class for indexing and searching.
-
 ```typescript
 import { CodebaseIndexer, PersistentStorage } from '@sylphx/coderag'
 
-const storage = new PersistentStorage({ codebaseRoot: './project' })
-const indexer = new CodebaseIndexer({
-  codebaseRoot: './project',
-  storage,
-  maxFileSize: 1024 * 1024, // 1MB default
-})
+const storage = new PersistentStorage({ codebaseRoot: './my-project' })
+const indexer = new CodebaseIndexer({ codebaseRoot: './my-project', storage })
 
-// Index with file watching
 await indexer.index({ watch: true })
-
-// Search with options
-const results = await indexer.search('query', {
-  limit: 10,
-  includeContent: true,
-  fileExtensions: ['.ts', '.js'],
-  excludePaths: ['node_modules'],
-})
-
-// Stop watching
-await indexer.stopWatch()
+const results = await indexer.search('authentication logic', { limit: 10 })
 ```
 
-### `PersistentStorage`
+---
 
-SQLite-backed storage for instant startup.
+## MCP Tool: `codebase_search`
 
-```typescript
-import { PersistentStorage } from '@sylphx/coderag'
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `query` | string | — | Search query (required) |
+| `limit` | number | 10 | Max results |
+| `include_content` | boolean | true | Include code snippets |
+| `file_extensions` | string[] | — | Filter by extension |
+| `path_filter` | string | — | Filter by path pattern |
+| `exclude_paths` | string[] | — | Exclude paths |
 
-const storage = new PersistentStorage({
-  codebaseRoot: './project',  // Creates .coderag/ folder
-  dbPath: './custom.db',      // Optional custom path
-})
-```
+Full tool reference: [docs/mcp/tools.md](docs/mcp/tools.md).
 
-### Low-Level TF-IDF Functions
-
-```typescript
-import { buildSearchIndex, searchDocuments, initializeTokenizer } from '@sylphx/coderag'
+---
 
-// Initialize StarCoder2 tokenizer (4.7MB, one-time download)
-await initializeTokenizer()
+## Benchmark Proof
 
-// Build index
-const documents = [
-  { uri: 'file://auth.ts', content: 'export function authenticate...' },
-  { uri: 'file://user.ts', content: 'export class User...' },
-]
-const index = await buildSearchIndex(documents)
+Performance claims in this README are backed only by the checked-in public
+benchmark script — not hand-waved marketing numbers.
 
-// Search
-const results = await searchDocuments('authenticate user', index, { limit: 5 })
+```bash
+bun run benchmark:public-proof
 ```
 
-### Vector Search (Optional)
+The script indexes `fixtures/benchmark-corpus/` (30 TypeScript files), runs
+hybrid TF-IDF search 20 times (3 warmup), and prints indexing throughput plus
+search p50/min/max latency.
 
-For semantic search with embeddings:
-
-```typescript
-import { hybridSearch, createEmbeddingProvider } from '@sylphx/coderag'
-
-// Requires OPENAI_API_KEY environment variable
-const results = await hybridSearch('authentication flow', indexer, {
-  vectorWeight: 0.7,  // 70% vector, 30% TF-IDF
-  limit: 10,
-})
-```
+See [benchmark proof](docs/benchmark.md) for methodology and latest reproduced
+results.
 
 ---
 
-## ⚙️ Configuration
-
-### MCP Server Options
+## Packages
 
-| Option | Default | Description |
-|--------|---------|-------------|
-| `--root=<path>` | Current directory | Codebase root path |
-| `--max-size=<bytes>` | 1048576 (1MB) | Max file size to index |
-| `--no-auto-index` | false | Disable auto-indexing on startup |
-
-### Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `OPENAI_API_KEY` | Enable vector search with OpenAI embeddings |
-| `OPENAI_BASE_URL` | Custom OpenAI-compatible endpoint |
-| `EMBEDDING_MODEL` | Embedding model (default: `text-embedding-3-small`) |
-| `EMBEDDING_DIMENSIONS` | Custom embedding dimensions |
+| Package | Description | Install |
+| --- | --- | --- |
+| [@sylphx/coderag](packages/core) | Core search library | `npm i @sylphx/coderag` |
+| [@sylphx/coderag-mcp](packages/mcp-server) | MCP server for AI assistants | `npx @sylphx/coderag-mcp` |
 
 ---
 
-## 📊 Performance
-
-| Metric | Value |
-|--------|-------|
-| **Initial indexing** | ~1000-2000 files/sec |
-| **Startup with cache** | <100ms |
-| **Search latency** | <50ms |
-| **Memory per 1000 files** | ~1-2 MB |
-| **Tokenizer size** | 4.7MB (StarCoder2) |
+## Documentation
 
-### Benchmarks
-
-Tested on MacBook Pro M1, 16GB RAM:
-
-| Codebase | Files | Index Time | Search Time |
-|----------|-------|------------|-------------|
-| Small (100 files) | 100 | 0.5s | <10ms |
-| Medium (1000 files) | 1,000 | 2s | <30ms |
-| Large (10000 files) | 10,000 | 15s | <50ms |
+| Topic | Link |
+| --- | --- |
+| Docs site | [coderag.sylphx.com](https://coderag.sylphx.com) |
+| Getting started | [docs/guide/getting-started.md](docs/guide/getting-started.md) |
+| MCP server | [docs/mcp/overview.md](docs/mcp/overview.md) |
+| How search works | [docs/guide/how-search-works.md](docs/guide/how-search-works.md) |
+| Benchmark proof | [docs/benchmark.md](docs/benchmark.md) |
+| Stop code-search guessing | [docs/articles/stop-code-search-guessing.md](docs/articles/stop-code-search-guessing.md) |
+| API reference | [docs/api/overview.md](docs/api/overview.md) |
 
 ---
 
-## 🏗️ Architecture
-
-```
-coderag/
-├── packages/
-│   ├── core/                     # @sylphx/coderag
-│   │   ├── src/
-│   │   │   ├── indexer.ts           # Main indexer with file watching
-│   │   │   ├── tfidf.ts             # TF-IDF with StarCoder2 tokenizer
-│   │   │   ├── code-tokenizer.ts    # StarCoder2 tokenization
-│   │   │   ├── hybrid-search.ts     # Vector + TF-IDF fusion
-│   │   │   ├── incremental-tfidf.ts # Smart incremental updates
-│   │   │   ├── storage-persistent.ts # SQLite storage
-│   │   │   ├── vector-storage.ts    # LanceDB vector storage
-│   │   │   ├── embeddings.ts        # OpenAI embeddings
-│   │   │   ├── ast-chunking.ts      # Synth AST chunking
-│   │   │   └── language-config.ts   # Language registry (15+ languages)
-│   │   └── package.json
-│   │
-│   └── mcp-server/               # @sylphx/coderag-mcp
-│       ├── src/
-│       │   └── index.ts             # MCP server
-│       └── package.json
-```
-
-### How It Works
-
-1. **Indexing**: Scans codebase, tokenizes with StarCoder2, builds TF-IDF index
-2. **AST Chunking**: Splits code at semantic boundaries (functions, classes, etc.)
-3. **Storage**: Persists to SQLite (`.coderag/` folder) for instant startup
-4. **Watching**: Detects file changes, performs incremental updates
-5. **Search**: Hybrid TF-IDF + optional vector search with score fusion
-
-### Supported Languages
-
-AST-based chunking with semantic boundary detection:
+## Security model
 
-| Category | Languages |
-|----------|-----------|
-| **JavaScript** | JavaScript, TypeScript, JSX, TSX |
-| **Systems** | Python, Go, Java, C |
-| **Markup** | Markdown, HTML, XML |
-| **Data/Config** | JSON, YAML, TOML, INI |
-| **Other** | Protobuf |
+- **Root confinement** — `--root` pins indexing and search to one repository tree.
+- **Exclude paths** — `exclude_paths` and default ignores skip `node_modules`, build output, and VCS metadata.
+- **Local-first** — TF-IDF indexing runs on your machine; embeddings are optional and caller-configured.
+- **Evidence fields** — results include file path, line range, symbol, score route, and index freshness for verification.
 
-**Embedded Code Support**: Automatically parses code blocks in Markdown and `<script>`/`<style>` tags in HTML.
+Example MCP request: [`examples/codebase-search-request.json`](examples/codebase-search-request.json).
 
 ---
 
-## 🔧 Development
+## Development
 
 ```bash
-# Clone
 git clone https://github.com/SylphxAI/coderag.git
 cd coderag
-
-# Install
 bun install
-
-# Build
 bun run build
+bun test
+```
 
-# Test
-bun run test
+Useful checks:
 
-# Lint & Format
+```bash
 bun run lint
-bun run format
+bun run typecheck
+bun run docs:build
+bun run benchmark:public-proof
+bun test test/readmeDiscovery.test.ts
 ```
 
 ---
 
-## 🤝 Contributing
+## Help this reach more builders
 
-Contributions are welcome! Please:
+If wrong code snippets have wasted your agent context, your edits, or your trust
+in search results, you are exactly who this project is for.
 
-1. Open an issue to discuss changes
-2. Fork and create a feature branch
-3. Run `bun run lint` and `bun run test`
-4. Submit a pull request
+**[⭐ Star the repo](https://github.com/SylphxAI/coderag)** — it is the fastest
+way to help more agent builders find chunk-level code search. Share it in your
+MCP client setup, team wiki, or agent stack README.
 
----
+### Discovery (in progress)
 
-## 📄 License
+| Channel | Status |
+| --- | --- |
+| [Official MCP Registry](https://registry.modelcontextprotocol.io/) | Not listed yet — no `server.json` publish workflow in this repo |
+| [Glama MCP directory](https://glama.ai/mcp/servers) | Not listed yet |
+| [mcpservers.org submit](https://mcpservers.org/submit) | Not listed yet — free web-form submission |
+| [mcp.so](https://mcp.so) | Not listed yet |
 
-MIT © [Sylphx](https://sylphx.com)
+Know another MCP directory? [Open an issue](https://github.com/SylphxAI/coderag/issues/new) with the link.
 
 ---
 
-<div align="center">
-
-**Powered by [Sylphx](https://github.com/SylphxAI)**
+## License
 
-Built with [@sylphx/synth](https://github.com/SylphxAI/synth) • [@sylphx/mcp-server-sdk](https://github.com/SylphxAI/mcp-server-sdk)
-
-</div>
+MIT © [SylphxAI](https://github.com/SylphxAI)
\ No newline at end of file
diff --git a/benchmark-artifacts/coderag_release_gate.json b/benchmark-artifacts/coderag_release_gate.json
new file mode 100644
index 0000000..7735158
--- /dev/null
+++ b/benchmark-artifacts/coderag_release_gate.json
@@ -0,0 +1,102 @@
+{
+	"profile": "coderag_release_gate",
+	"generated_at": "2026-07-09T15:37:32.042Z",
+	"artifact_dir": "/home/codex/src/github.com/SylphxAI/coderag/benchmark-artifacts",
+	"status": "passed",
+	"summary": {
+		"total": 12,
+		"passed": 12,
+		"failed": 0
+	},
+	"checks": [
+		{
+			"id": "rust:retrieval_core",
+			"status": "passed",
+			"message": "Rust coderag-core retrieval engine is present"
+		},
+		{
+			"id": "fixtures:benchmark_corpus",
+			"status": "passed",
+			"message": "Golden retrieval benchmark corpus is checked in"
+		},
+		{
+			"id": "tests:golden_retrieval",
+			"status": "passed",
+			"message": "Golden retrieval eval test harness is present"
+		},
+		{
+			"id": "doctor:golden_fixture",
+			"status": "passed",
+			"message": "doctor reports the golden retrieval corpus is available",
+			"evidence": {
+				"doctorStatus": "ready"
+			}
+		},
+		{
+			"id": "boundary:coderag_index",
+			"status": "passed",
+			"message": "coderag_index returns ok from the Rust CLI on the benchmark corpus"
+		},
+		{
+			"id": "boundary:incremental_cache_hit",
+			"status": "passed",
+			"message": "coderag_index mode=auto reuses the persisted index when file hashes are unchanged",
+			"evidence": {
+				"refreshMode": "cache_hit"
+			}
+		},
+		{
+			"id": "golden:src/auth/login.ts",
+			"status": "passed",
+			"message": "Rust retrieval returns src/auth/login.ts for \"user authentication login\"",
+			"evidence": {
+				"query": "user authentication login",
+				"expectedPath": "src/auth/login.ts",
+				"hit": true
+			}
+		},
+		{
+			"id": "golden:src/db/pool.ts",
+			"status": "passed",
+			"message": "Rust retrieval returns src/db/pool.ts for \"database connection pool\"",
+			"evidence": {
+				"query": "database connection pool",
+				"expectedPath": "src/db/pool.ts",
+				"hit": true
+			}
+		},
+		{
+			"id": "golden:src/api/rate-limit.ts",
+			"status": "passed",
+			"message": "Rust retrieval returns src/api/rate-limit.ts for \"checkRateLimit windowMs\"",
+			"evidence": {
+				"query": "checkRateLimit windowMs",
+				"expectedPath": "src/api/rate-limit.ts",
+				"hit": true
+			}
+		},
+		{
+			"id": "contract:retrieval_envelope",
+			"status": "passed",
+			"message": "Unified retrieval envelope documents versioned Rust index and hybrid semantic search routes",
+			"evidence": {
+				"contractVersion": "coderag-retrieval-v1",
+				"indexRoute": "rust-tfidf",
+				"searchRoute": "rust-semantic-hybrid"
+			}
+		},
+		{
+			"id": "mcp:rust_adapter_default",
+			"status": "passed",
+			"message": "Default npm bin launches the Rust rmcp MCP server; TypeScript adapter is opt-in only"
+		},
+		{
+			"id": "boundary:rust_cli_engine",
+			"status": "passed",
+			"message": "Shipped-path matrix test proves primary retrieval routes through Rust core without legacy runtime",
+			"evidence": {
+				"exitCode": 0
+			}
+		}
+	]
+}
diff --git a/bin/coderag-mcp b/bin/coderag-mcp
new file mode 100755
index 0000000..e2bfddc
--- /dev/null
+++ b/bin/coderag-mcp
@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+TS_ENTRY="$ROOT/packages/mcp-server/dist/index.js"
+
+resolve_rust_bin() {
+	if [[ -n "${CODERAG_MCP_RUST_BIN:-}" && -x "${CODERAG_MCP_RUST_BIN}" ]]; then
+		printf '%s\n' "${CODERAG_MCP_RUST_BIN}"
+		return 0
+	fi
+
+	for candidate in \
+		"$ROOT/bin/native/coderag-mcp-server" \
+		"$ROOT/target/release/coderag-mcp-server" \
+		"$ROOT/target/debug/coderag-mcp-server"; do
+		if [[ -x "$candidate" ]]; then
+			printf '%s\n' "$candidate"
+			return 0
+		fi
+	done
+
+	return 1
+}
+
+use_ts_transport() {
+	[[ "${CODERAG_MCP_TRANSPORT:-}" == "ts" ]] || [[ "${1:-}" == "ts" ]]
+}
+
+if use_ts_transport "$@"; then
+	if [[ "${1:-}" == "ts" ]]; then
+		shift
+	fi
+	exec node "$TS_ENTRY" "$@"
+fi
+
+if bin="$(resolve_rust_bin)"; then
+	exec "$bin" "$@"
+fi
+
+echo "[coderag-mcp] Rust MCP server (rmcp) is not built. Run: bun run build:rust" >&2
+exit 1
\ No newline at end of file
diff --git a/bin/native/coderag-mcp-server b/bin/native/coderag-mcp-server
new file mode 100755
index 0000000..5157461
Binary files /dev/null and b/bin/native/coderag-mcp-server differ
diff --git a/biome.json b/biome.json
index 36281ee..7dcc176 100644
--- a/biome.json
+++ b/biome.json
@@ -1,5 +1,5 @@
 {
-	"$schema": "https://biomejs.dev/schemas/2.3.8/schema.json",
+	"$schema": "https://biomejs.dev/schemas/2.5.3/schema.json",
 	"extends": ["@sylphx/biome-config"],
 	"vcs": {
 		"enabled": true,
@@ -42,6 +42,14 @@
 	},
 	"files": {
 		"ignoreUnknown": false,
-		"includes": ["**/*.js", "**/*.ts", "**/*.jsx", "**/*.tsx", "**/*.json"]
+		"includes": [
+			"**/*.js",
+			"**/*.ts",
+			"**/*.jsx",
+			"**/*.tsx",
+			"**/*.json",
+			"!benchmark-artifacts/**",
+			"!fixtures/**/.coderag/**"
+		]
 	}
 }
diff --git a/bun.lock b/bun.lock
index d2ed234..7e53ef6 100644
--- a/bun.lock
+++ b/bun.lock
@@ -9,7 +9,7 @@
         "@sylphx/biome-config": "^0.4.0",
         "lefthook": "^2.0.4",
         "turbo": "^2.6.1",
-        "typescript": "^5.9.3",
+        "typescript": "^7.0.2",
         "vitepress": "^1.6.4",
         "vue": "^3.5.25",
       },
@@ -28,9 +28,11 @@
         "ignore": "^7.0.5",
       },
       "devDependencies": {
+        "@biomejs/biome": "^2.3.12",
+        "@sylphx/biome-config": "^0.4.1",
         "@types/node": "^24.9.2",
         "drizzle-kit": "^0.28.1",
-        "typescript": "^5.9.3",
+        "typescript": "^7.0.2",
         "vitest": "^4.0.14",
       },
       "optionalDependencies": {
@@ -66,9 +68,11 @@
         "@sylphx/vex": "^0.1.11",
       },
       "devDependencies": {
+        "@biomejs/biome": "^2.3.12",
+        "@sylphx/biome-config": "^0.4.1",
         "@types/bun": "^1.3.3",
         "@types/node": "^24.9.2",
-        "typescript": "^5.9.3",
+        "typescript": "^7.0.2",
       },
     },
   },
@@ -521,6 +525,46 @@
 
     "@types/ws": ["@types/ws@8.18.1", "", { "dependencies": { "@types/node": "*" } }, "sha512-ThVF6DCVhA8kUGy+aazFQ4kXQ7E1Ty7A3ypFOe0IcJV8O/M511G99AW24irKrW56Wt44yG9+ij8FaqoBGkuBXg=="],
 
+    "@typescript/typescript-aix-ppc64": ["@typescript/typescript-aix-ppc64@7.0.2", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="],
+
+    "@typescript/typescript-darwin-arm64": ["@typescript/typescript-darwin-arm64@7.0.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="],
+
+    "@typescript/typescript-darwin-x64": ["@typescript/typescript-darwin-x64@7.0.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA=="],
+
+    "@typescript/typescript-freebsd-arm64": ["@typescript/typescript-freebsd-arm64@7.0.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ=="],
+
+    "@typescript/typescript-freebsd-x64": ["@typescript/typescript-freebsd-x64@7.0.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw=="],
+
+    "@typescript/typescript-linux-arm": ["@typescript/typescript-linux-arm@7.0.2", "", { "os": "linux", "cpu": "arm" }, "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ=="],
+
+    "@typescript/typescript-linux-arm64": ["@typescript/typescript-linux-arm64@7.0.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ=="],
+
+    "@typescript/typescript-linux-loong64": ["@typescript/typescript-linux-loong64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ=="],
+
+    "@typescript/typescript-linux-mips64el": ["@typescript/typescript-linux-mips64el@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA=="],
+
+    "@typescript/typescript-linux-ppc64": ["@typescript/typescript-linux-ppc64@7.0.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA=="],
+
+    "@typescript/typescript-linux-riscv64": ["@typescript/typescript-linux-riscv64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ=="],
+
+    "@typescript/typescript-linux-s390x": ["@typescript/typescript-linux-s390x@7.0.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw=="],
+
+    "@typescript/typescript-linux-x64": ["@typescript/typescript-linux-x64@7.0.2", "", { "os": "linux", "cpu": "x64" }, "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A=="],
+
+    "@typescript/typescript-netbsd-arm64": ["@typescript/typescript-netbsd-arm64@7.0.2", "", { "os": "none", "cpu": "arm64" }, "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA=="],
+
+    "@typescript/typescript-netbsd-x64": ["@typescript/typescript-netbsd-x64@7.0.2", "", { "os": "none", "cpu": "x64" }, "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA=="],
+
+    "@typescript/typescript-openbsd-arm64": ["@typescript/typescript-openbsd-arm64@7.0.2", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ=="],
+
+    "@typescript/typescript-openbsd-x64": ["@typescript/typescript-openbsd-x64@7.0.2", "", { "os": "openbsd", "cpu": "x64" }, "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg=="],
+
+    "@typescript/typescript-sunos-x64": ["@typescript/typescript-sunos-x64@7.0.2", "", { "os": "sunos", "cpu": "x64" }, "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g=="],
+
+    "@typescript/typescript-win32-arm64": ["@typescript/typescript-win32-arm64@7.0.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ=="],
+
+    "@typescript/typescript-win32-x64": ["@typescript/typescript-win32-x64@7.0.2", "", { "os": "win32", "cpu": "x64" }, "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g=="],
+
     "@ungap/structured-clone": ["@ungap/structured-clone@1.3.0", "", {}, "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g=="],
 
     "@vitejs/plugin-vue": ["@vitejs/plugin-vue@5.2.4", "", { "peerDependencies": { "vite": "^5.0.0 || ^6.0.0", "vue": "^3.2.25" } }, "sha512-7Yx/SXSOcQq5HiiV3orevHUFn+pmMB4cgbEkDYgnkUWb0WfeQ/wa2yFv6D5ICiCQOVpjA7vYDXrC7AGO8yjDHA=="],
@@ -995,7 +1039,7 @@
 
     "type-fest": ["type-fest@0.13.1", "", {}, "sha512-34R7HTnG0XIJcBSn5XhDd7nNFPRcXYRZrBB2O2jdKqYODldSzBAqzsWoZYYvduky73toYS/ESqxPvkDf/F0XMg=="],
 
-    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+    "typescript": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="],
 
     "typical": ["typical@4.0.0", "", {}, "sha512-VAH4IvQ7BDFYglMd7BPRDfLgxZZX4O4TFcRDA6EN5X7erNJJq+McIEp8np9aVtxrCJ6qx4GTYVfOWNjcqwZgRw=="],
 
@@ -1051,6 +1095,14 @@
 
     "@esbuild-kit/core-utils/esbuild": ["esbuild@0.18.20", "", { "optionalDependencies": { "@esbuild/android-arm": "0.18.20", "@esbuild/android-arm64": "0.18.20", "@esbuild/android-x64": "0.18.20", "@esbuild/darwin-arm64": "0.18.20", "@esbuild/darwin-x64": "0.18.20", "@esbuild/freebsd-arm64": "0.18.20", "@esbuild/freebsd-x64": "0.18.20", "@esbuild/linux-arm": "0.18.20", "@esbuild/linux-arm64": "0.18.20", "@esbuild/linux-ia32": "0.18.20", "@esbuild/linux-loong64": "0.18.20", "@esbuild/linux-mips64el": "0.18.20", "@esbuild/linux-ppc64": "0.18.20", "@esbuild/linux-riscv64": "0.18.20", "@esbuild/linux-s390x": "0.18.20", "@esbuild/linux-x64": "0.18.20", "@esbuild/netbsd-x64": "0.18.20", "@esbuild/openbsd-x64": "0.18.20", "@esbuild/sunos-x64": "0.18.20", "@esbuild/win32-arm64": "0.18.20", "@esbuild/win32-ia32": "0.18.20", "@esbuild/win32-x64": "0.18.20" }, "bin": { "esbuild": "bin/esbuild" } }, "sha512-ceqxoedUrcayh7Y7ZX6NdbbDzGROiyVBgC4PriJThBKSVPWnnFHZAkfI1lJT8QFkOwH4qOS2SJkS4wvpGl8BpA=="],
 
+    "@sylphx/coderag/@biomejs/biome": ["@biomejs/biome@2.5.3", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.3", "@biomejs/cli-darwin-x64": "2.5.3", "@biomejs/cli-linux-arm64": "2.5.3", "@biomejs/cli-linux-arm64-musl": "2.5.3", "@biomejs/cli-linux-x64": "2.5.3", "@biomejs/cli-linux-x64-musl": "2.5.3", "@biomejs/cli-win32-arm64": "2.5.3", "@biomejs/cli-win32-x64": "2.5.3" }, "bin": { "biome": "bin/biome" } }, "sha512-MrJswFdei9EfDwwUy2tQrPDpK0AO+RmMFvBoaaJ6ayBc3sUbHdCE+XG5N8vp+5So41ZupZJQm0roHFFhMGVD7A=="],
+
+    "@sylphx/coderag/@sylphx/biome-config": ["@sylphx/biome-config@0.4.1", "", { "peerDependencies": { "@biomejs/biome": "^2.0.0" } }, "sha512-yNdrXKcnhrXK+OB2WLEJix6cryj3PME5DbKpGFMJGA6/B1/+mpk2ChKiohifrf956FKQ3JTAqhLhZfY7lu18yA=="],
+
+    "@sylphx/coderag-mcp/@biomejs/biome": ["@biomejs/biome@2.5.3", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "2.5.3", "@biomejs/cli-darwin-x64": "2.5.3", "@biomejs/cli-linux-arm64": "2.5.3", "@biomejs/cli-linux-arm64-musl": "2.5.3", "@biomejs/cli-linux-x64": "2.5.3", "@biomejs/cli-linux-x64-musl": "2.5.3", "@biomejs/cli-win32-arm64": "2.5.3", "@biomejs/cli-win32-x64": "2.5.3" }, "bin": { "biome": "bin/biome" } }, "sha512-MrJswFdei9EfDwwUy2tQrPDpK0AO+RmMFvBoaaJ6ayBc3sUbHdCE+XG5N8vp+5So41ZupZJQm0roHFFhMGVD7A=="],
+
+    "@sylphx/coderag-mcp/@sylphx/biome-config": ["@sylphx/biome-config@0.4.1", "", { "peerDependencies": { "@biomejs/biome": "^2.0.0" } }, "sha512-yNdrXKcnhrXK+OB2WLEJix6cryj3PME5DbKpGFMJGA6/B1/+mpk2ChKiohifrf956FKQ3JTAqhLhZfY7lu18yA=="],
+
     "@sylphx/synth-c/@sylphx/synth": ["@sylphx/synth@0.3.2", "", {}, "sha512-g+8RFCzuxkU2OwC4T+Gn5BWjV93Ehhzatm7ccwM7yzhD22VBIe/wZ58WavoDzwOQg0uLbFRcURYDKEdXYevboA=="],
 
     "@sylphx/synth-go/@sylphx/synth": ["@sylphx/synth@0.3.2", "", {}, "sha512-g+8RFCzuxkU2OwC4T+Gn5BWjV93Ehhzatm7ccwM7yzhD22VBIe/wZ58WavoDzwOQg0uLbFRcURYDKEdXYevboA=="],
@@ -1183,6 +1235,38 @@
 
     "@esbuild-kit/core-utils/esbuild/@esbuild/win32-x64": ["@esbuild/win32-x64@0.18.20", "", { "os": "win32", "cpu": "x64" }, "sha512-kTdfRcSiDfQca/y9QIkng02avJ+NCaQvrMejlsB3RRv5sE9rRoeBPISaZpKxHELzRxZyLvNts1P27W3wV+8geQ=="],
 
+    "@sylphx/coderag-mcp/@biomejs/biome/@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-QhYP9muVQ0nUO5zztFuPbEwi4+94sJWVjaZds9aMi1l/KNZBiUjdiSUrGHsTaMGDXrYl+r4AS2sUKfgH3w+V3g=="],
+
+    "@sylphx/coderag-mcp/@biomejs/biome/@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-NC1Ss13UaW7QZX+y8j44bF7AP0jSJdBl6iRhe0MAkvaSqZy+mWg3GaXsrb+eSoHoGDBtaXWEbMVV0iVN2cZ7cQ=="],
+
+    "@sylphx/coderag-mcp/@biomejs/biome/@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-ksx1KWeyYW18ILL04msF/J4ZBtBDN33znYK8Z/aNv/vlBVxL9/g3mGP+omgHJKy4+KWbK87vcmmpmurfNjSgiA=="],
+
+    "@sylphx/coderag-mcp/@biomejs/biome/@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-fccix0w6xp6csCXgxeC0dU/3ecgRQal0y+cv2SP9ajNlhe7Yrk2Ug7UDe2j9AT9ZDYitkXpvUKgZjjuoYeP4Vg=="],
+
+    "@sylphx/coderag-mcp/@biomejs/biome/@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.3", "", { "os": "linux", "cpu": "x64" }, "sha512-yMkJtilsgvILDcVkh187aVLTb64xYsrxYajx5kym+r1ULkO5HUOfu9AYKLGQbOVLwJtT2utNw7hhFNg+17mUYA=="],
+
+    "@sylphx/coderag-mcp/@biomejs/biome/@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.3", "", { "os": "linux", "cpu": "x64" }, "sha512-O/yU9YKRUiHhmcjF2f38PSjseVk3G4VLWYc0G2HWpzdBVREV6G8IGWIVEFf7MFPfWIzNUIvPsEjeAZQIOgnLcQ=="],
+
+    "@sylphx/coderag-mcp/@biomejs/biome/@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-cX5z+GYwRcqEok0AH3KSfQGgqYd0Nomfp6Fbe1uiTtELE38hdH2k842wQ9wLNaF/JJ7r4rjJQ4VR+ce+fRmQbw=="],
+
+    "@sylphx/coderag-mcp/@biomejs/biome/@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.3", "", { "os": "win32", "cpu": "x64" }, "sha512-ExSaJWi4/u6+GXCszlSKpWSjKNbDseAYqqkCznsCsZ/4uidZ/BEqsCc5/3ctlq6dfIubdIIRSVLC/PG9xPl70Q=="],
+
+    "@sylphx/coderag/@biomejs/biome/@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@2.5.3", "", { "os": "darwin", "cpu": "arm64" }, "sha512-QhYP9muVQ0nUO5zztFuPbEwi4+94sJWVjaZds9aMi1l/KNZBiUjdiSUrGHsTaMGDXrYl+r4AS2sUKfgH3w+V3g=="],
+
+    "@sylphx/coderag/@biomejs/biome/@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@2.5.3", "", { "os": "darwin", "cpu": "x64" }, "sha512-NC1Ss13UaW7QZX+y8j44bF7AP0jSJdBl6iRhe0MAkvaSqZy+mWg3GaXsrb+eSoHoGDBtaXWEbMVV0iVN2cZ7cQ=="],
+
+    "@sylphx/coderag/@biomejs/biome/@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@2.5.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-ksx1KWeyYW18ILL04msF/J4ZBtBDN33znYK8Z/aNv/vlBVxL9/g3mGP+omgHJKy4+KWbK87vcmmpmurfNjSgiA=="],
+
+    "@sylphx/coderag/@biomejs/biome/@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@2.5.3", "", { "os": "linux", "cpu": "arm64" }, "sha512-fccix0w6xp6csCXgxeC0dU/3ecgRQal0y+cv2SP9ajNlhe7Yrk2Ug7UDe2j9AT9ZDYitkXpvUKgZjjuoYeP4Vg=="],
+
+    "@sylphx/coderag/@biomejs/biome/@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@2.5.3", "", { "os": "linux", "cpu": "x64" }, "sha512-yMkJtilsgvILDcVkh187aVLTb64xYsrxYajx5kym+r1ULkO5HUOfu9AYKLGQbOVLwJtT2utNw7hhFNg+17mUYA=="],
+
+    "@sylphx/coderag/@biomejs/biome/@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@2.5.3", "", { "os": "linux", "cpu": "x64" }, "sha512-O/yU9YKRUiHhmcjF2f38PSjseVk3G4VLWYc0G2HWpzdBVREV6G8IGWIVEFf7MFPfWIzNUIvPsEjeAZQIOgnLcQ=="],
+
+    "@sylphx/coderag/@biomejs/biome/@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@2.5.3", "", { "os": "win32", "cpu": "arm64" }, "sha512-cX5z+GYwRcqEok0AH3KSfQGgqYd0Nomfp6Fbe1uiTtELE38hdH2k842wQ9wLNaF/JJ7r4rjJQ4VR+ce+fRmQbw=="],
+
+    "@sylphx/coderag/@biomejs/biome/@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@2.5.3", "", { "os": "win32", "cpu": "x64" }, "sha512-ExSaJWi4/u6+GXCszlSKpWSjKNbDseAYqqkCznsCsZ/4uidZ/BEqsCc5/3ctlq6dfIubdIIRSVLC/PG9xPl70Q=="],
+
     "@vueuse/core/vue/@vue/compiler-dom": ["@vue/compiler-dom@3.5.24", "", { "dependencies": { "@vue/compiler-core": "3.5.24", "@vue/shared": "3.5.24" } }, "sha512-1QHGAvs53gXkWdd3ZMGYuvQFXHW4ksKWPG8HP8/2BscrbZ0brw183q2oNWjMrSWImYLHxHrx1ItBQr50I/q2zw=="],
 
     "@vueuse/core/vue/@vue/compiler-sfc": ["@vue/compiler-sfc@3.5.24", "", { "dependencies": { "@babel/parser": "^7.28.5", "@vue/compiler-core": "3.5.24", "@vue/compiler-dom": "3.5.24", "@vue/compiler-ssr": "3.5.24", "@vue/shared": "3.5.24", "estree-walker": "^2.0.2", "magic-string": "^0.30.21", "postcss": "^8.5.6", "source-map-js": "^1.2.1" } }, "sha512-8EG5YPRgmTB+YxYBM3VXy8zHD9SWHUJLIGPhDovo3Z8VOgvP+O7UP5vl0J4BBPWYD9vxtBabzW1EuEZ+Cqs14g=="],
diff --git a/crates/coderag-cli/Cargo.toml b/crates/coderag-cli/Cargo.toml
new file mode 100644
index 0000000..2b55c04
--- /dev/null
+++ b/crates/coderag-cli/Cargo.toml
@@ -0,0 +1,16 @@
+[package]
+name = "coderag-cli"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "JSON CLI bridge for the CodeRAG Rust retrieval engine."
+
+[[bin]]
+name = "coderag-cli"
+path = "src/main.rs"
+
+[dependencies]
+coderag-core = { path = "../coderag-core" }
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
\ No newline at end of file
diff --git a/crates/coderag-cli/src/main.rs b/crates/coderag-cli/src/main.rs
new file mode 100644
index 0000000..186d574
--- /dev/null
+++ b/crates/coderag-cli/src/main.rs
@@ -0,0 +1,29 @@
+use std::io::{self, Read};
+
+use coderag_core::handle_tool;
+use serde::Deserialize;
+
+#[derive(Debug, Deserialize)]
+struct CliRequest {
+    tool: String,
+    input: serde_json::Value,
+}
+
+fn main() {
+    let mut raw = String::new();
+    if io::stdin().read_to_string(&mut raw).is_err() || raw.trim().is_empty() {
+        eprintln!("coderag-cli expects JSON on stdin: {{\"tool\":\"...\",\"input\":{{...}}}}");
+        std::process::exit(2);
+    }
+
+    let request: CliRequest = match serde_json::from_str(&raw) {
+        Ok(value) => value,
+        Err(err) => {
+            eprintln!("Invalid JSON request: {err}");
+            std::process::exit(2);
+        }
+    };
+
+    let envelope = handle_tool(&request.tool, request.input);
+    println!("{}", serde_json::to_string(&envelope).expect("serialize envelope"));
+}
\ No newline at end of file
diff --git a/crates/coderag-core/Cargo.toml b/crates/coderag-core/Cargo.toml
new file mode 100644
index 0000000..7c9fe68
--- /dev/null
+++ b/crates/coderag-core/Cargo.toml
@@ -0,0 +1,17 @@
+[package]
+name = "coderag-core"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+description = "Rust TF-IDF retrieval core for CodeRAG."
+
+[lib]
+path = "src/lib.rs"
+
+[dependencies]
+regex = "1.11"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+sha2 = "0.10"
+walkdir = "2.5"
\ No newline at end of file
diff --git a/crates/coderag-core/src/engine.rs b/crates/coderag-core/src/engine.rs
new file mode 100644
index 0000000..7bfba1f
--- /dev/null
+++ b/crates/coderag-core/src/engine.rs
@@ -0,0 +1,107 @@
+use std::path::Path;
+use std::sync::{Mutex, OnceLock};
+use std::time::Instant;
+
+use crate::index::{refresh_index, search_index, IndexMode, SearchIndex};
+use crate::store::{load_index, save_index};
+use crate::types::ToolEnvelope;
+
+static INDEX: OnceLock<Mutex<Option<SearchIndex>>> = OnceLock::new();
+
+fn index_store() -> &'static Mutex<Option<SearchIndex>> {
+    INDEX.get_or_init(|| Mutex::new(None))
+}
+
+pub fn handle_tool(tool: &str, input: serde_json::Value) -> ToolEnvelope {
+    match tool {
+        "coderag_index" => coderag_index(input),
+        "coderag_search" => coderag_search(input),
+        _ => ToolEnvelope::error("UNSUPPORTED_TOOL", &format!("Unknown tool: {tool}")),
+    }
+}
+
+fn coderag_index(input: serde_json::Value) -> ToolEnvelope {
+    let root = match input.get("root").and_then(|v| v.as_str()) {
+        Some(value) => value,
+        None => return ToolEnvelope::error("INVALID_ROOT", "Missing required field: root"),
+    };
+    let max_file_bytes = input
+        .get("maxFileBytes")
+        .and_then(|v| v.as_u64())
+        .unwrap_or(1_048_576);
+    let mode = input
+        .get("mode")
+        .and_then(|v| v.as_str())
+        .map(IndexMode::parse)
+        .unwrap_or(IndexMode::Auto);
+
+    match refresh_index(Path::new(root), max_file_bytes, mode) {
+        Ok((index, stats)) => {
+            if let Err(message) = save_index(Path::new(root), &index) {
+                return ToolEnvelope::error("INDEX_PERSIST_FAILED", &message);
+            }
+            if let Ok(mut guard) = index_store().lock() {
+                *guard = Some(index);
+            }
+            ToolEnvelope::ok_index(stats)
+        }
+        Err(message) => ToolEnvelope::error("INDEX_FAILED", &message),
+    }
+}
+
+fn resolve_index(root: Option<&str>) -> Result<SearchIndex, ToolEnvelope> {
+    if let Ok(guard) = index_store().lock() {
+        if let Some(index) = guard.clone() {
+            if root.is_none() || root == Some(index.root.as_str()) {
+                return Ok(index);
+            }
+        }
+    }
+
+    let Some(root) = root else {
+        return Err(ToolEnvelope::error(
+            "INDEX_NOT_FOUND",
+            "No in-memory Rust index exists. Call coderag_index first or pass root to load a snapshot.",
+        ));
+    };
+
+    match load_index(Path::new(root)) {
+        Ok(index) => {
+            if let Ok(mut guard) = index_store().lock() {
+                *guard = Some(index.clone());
+            }
+            Ok(index)
+        }
+        Err(_) => match refresh_index(Path::new(root), 1_048_576, IndexMode::Auto) {
+            Ok((index, _)) => {
+                let _ = save_index(Path::new(root), &index);
+                if let Ok(mut guard) = index_store().lock() {
+                    *guard = Some(index.clone());
+                }
+                Ok(index)
+            }
+            Err(message) => Err(ToolEnvelope::error("INDEX_FAILED", &message)),
+        },
+    }
+}
+
+fn coderag_search(input: serde_json::Value) -> ToolEnvelope {
+    let started = Instant::now();
+    let query = match input.get("query").and_then(|v| v.as_str()) {
+        Some(value) => value,
+        None => return ToolEnvelope::error("INVALID_QUERY", "Missing required field: query"),
+    };
+    let limit = input
+        .get("limit")
+        .and_then(|v| v.as_u64())
+        .unwrap_or(10) as usize;
+
+    let root = input.get("root").and_then(|v| v.as_str());
+    let index = match resolve_index(root) {
+        Ok(index) => index,
+        Err(envelope) => return envelope,
+    };
+
+    let results = search_index(&index, query, limit);
+    ToolEnvelope::ok_search(query, results, started.elapsed().as_millis() as u64)
+}
\ No newline at end of file
diff --git a/crates/coderag-core/src/index.rs b/crates/coderag-core/src/index.rs
new file mode 100644
index 0000000..9c16c79
--- /dev/null
+++ b/crates/coderag-core/src/index.rs
@@ -0,0 +1,444 @@
+use std::collections::{HashMap, HashSet};
+use std::fs;
+use std::path::{Path, PathBuf};
+use std::time::Instant;
+
+use regex::Regex;
+use walkdir::WalkDir;
+
+use crate::store::{
+    hash_file_bytes, load_file_hashes, load_index, save_file_hashes, save_index, FileHashManifest,
+};
+use crate::tokenize::{tokenize, unique_terms};
+use crate::types::{IndexStats, ScoreComponent};
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
+pub struct Chunk {
+    pub path: String,
+    pub start_line: u32,
+    pub end_line: u32,
+    pub text: String,
+    pub tokens: Vec<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub symbol_name: Option<String>,
+    #[serde(default = "default_chunk_type")]
+    pub chunk_type: String,
+}
+
+fn default_chunk_type() -> String {
+    "file".into()
+}
+
+#[derive(Debug, Default, Clone, serde::Serialize, serde::Deserialize)]
+pub struct SearchIndex {
+    pub root: String,
+    pub chunks: Vec<Chunk>,
+    pub doc_freq: HashMap<String, usize>,
+    pub avg_doc_len: f64,
+}
+
+const DEFAULT_EXCLUDES: &[&str] = &["node_modules", "dist", "target", ".git"];
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum IndexMode {
+    Full,
+    Auto,
+}
+
+impl IndexMode {
+    pub fn parse(value: &str) -> Self {
+        match value {
+            "full" => Self::Full,
+            _ => Self::Auto,
+        }
+    }
+}
+
+pub fn refresh_index(
+    root: &Path,
+    max_file_bytes: u64,
+    mode: IndexMode,
+) -> Result<(SearchIndex, IndexStats), String> {
+    if mode == IndexMode::Full {
+        return build_index(root, max_file_bytes);
+    }
+
+    let started = Instant::now();
+    let canonical = root
+        .canonicalize()
+        .map_err(|e| format!("INVALID_ROOT: {e}"))?;
+    let inventory = inventory_files(&canonical, max_file_bytes)?;
+
+    if let (Ok(index), Ok(stored)) = (load_index(&canonical), load_file_hashes(&canonical)) {
+        if stored.file_hashes == inventory {
+            return Ok((
+                index.clone(),
+                IndexStats {
+                    files_scanned: inventory.len(),
+                    chunks_indexed: index.chunks.len(),
+                    elapsed_ms: started.elapsed().as_millis() as u64,
+                    refresh_mode: "cache_hit".into(),
+                    files_changed: 0,
+                    files_removed: 0,
+                },
+            ));
+        }
+
+        let mut changed = HashSet::new();
+        let mut removed = HashSet::new();
+
+        for (path, hash) in &inventory {
+            match stored.file_hashes.get(path) {
+                Some(previous) if previous == hash => {}
+                _ => {
+                    changed.insert(path.clone());
+                }
+            }
+        }
+
+        for path in stored.file_hashes.keys() {
+            if !inventory.contains_key(path) {
+                removed.insert(path.clone());
+            }
+        }
+
+        let files_changed = changed.len();
+        let files_removed = removed.len();
+        let affected: HashSet<String> = changed.union(&removed).cloned().collect();
+        let mut index = index;
+        index
+            .chunks
+            .retain(|chunk| !affected.contains(&chunk.path));
+
+        for path in &changed {
+            let file_path = canonical.join(path);
+            let content = fs::read_to_string(&file_path).unwrap_or_default();
+            index.chunks.extend(chunk_file(path, &content));
+        }
+
+        rebuild_doc_freq(&mut index);
+        let chunks_indexed = index.chunks.len();
+
+        let manifest = FileHashManifest {
+            schema_version: crate::store::FILE_HASH_SCHEMA_VERSION.into(),
+            root: canonical.to_string_lossy().to_string(),
+            file_hashes: inventory.clone(),
+        };
+        save_index(&canonical, &index)?;
+        save_file_hashes(&canonical, &manifest)?;
+
+        return Ok((
+            index,
+            IndexStats {
+                files_scanned: inventory.len(),
+                chunks_indexed,
+                elapsed_ms: started.elapsed().as_millis() as u64,
+                refresh_mode: "incremental".into(),
+                files_changed,
+                files_removed,
+            },
+        ));
+    }
+
+    build_index(root, max_file_bytes)
+}
+
+pub fn inventory_files(root: &Path, max_file_bytes: u64) -> Result<HashMap<String, String>, String> {
+    let mut inventory = HashMap::new();
+
+    for entry in WalkDir::new(root).into_iter().filter_map(Result::ok) {
+        let path = entry.path();
+        if path.is_dir() {
+            continue;
+        }
+        let rel = path.strip_prefix(root).unwrap_or(path);
+        let rel_str = rel.to_string_lossy().replace('\\', "/");
+        if should_skip(&rel_str) || !is_indexable_extension(&rel_str) {
+            continue;
+        }
+        if let Ok(meta) = fs::metadata(path) {
+            if meta.len() > max_file_bytes {
+                continue;
+            }
+        }
+        let hash = hash_file_bytes(path)?;
+        inventory.insert(rel_str, hash);
+    }
+
+    Ok(inventory)
+}
+
+fn is_indexable_extension(rel: &str) -> bool {
+    rel.ends_with(".ts")
+        || rel.ends_with(".tsx")
+        || rel.ends_with(".js")
+        || rel.ends_with(".rs")
+        || rel.ends_with(".md")
+}
+
+fn rebuild_doc_freq(index: &mut SearchIndex) {
+    index.doc_freq.clear();
+    let mut total_len = 0usize;
+    for chunk in &index.chunks {
+        total_len += chunk.tokens.len();
+        for term in unique_terms(&chunk.tokens) {
+            *index.doc_freq.entry(term).or_insert(0) += 1;
+        }
+    }
+    index.avg_doc_len = if index.chunks.is_empty() {
+        0.0
+    } else {
+        total_len as f64 / index.chunks.len() as f64
+    };
+}
+
+pub fn build_index(root: &Path, max_file_bytes: u64) -> Result<(SearchIndex, IndexStats), String> {
+    let started = Instant::now();
+    let root = root
+        .canonicalize()
+        .map_err(|e| format!("INVALID_ROOT: {e}"))?;
+    let mut index = SearchIndex {
+        root: root.to_string_lossy().to_string(),
+        ..Default::default()
+    };
+    let mut files_scanned = 0usize;
+
+    for entry in WalkDir::new(&root).into_iter().filter_map(Result::ok) {
+        let path = entry.path();
+        if path.is_dir() {
+            continue;
+        }
+        let rel = path.strip_prefix(&root).unwrap_or(path);
+        let rel_str = rel.to_string_lossy().replace('\\', "/");
+        if should_skip(&rel_str) {
+            continue;
+        }
+        if !is_indexable_extension(&rel_str) {
+            continue;
+        }
+        if let Ok(meta) = fs::metadata(path) {
+            if meta.len() > max_file_bytes {
+                continue;
+            }
+        }
+        files_scanned += 1;
+        let content = fs::read_to_string(path).unwrap_or_default();
+        index.chunks.extend(chunk_file(&rel_str, &content));
+    }
+
+    let mut total_len = 0usize;
+    for chunk in &index.chunks {
+        total_len += chunk.tokens.len();
+        for term in unique_terms(&chunk.tokens) {
+            *index.doc_freq.entry(term).or_insert(0) += 1;
+        }
+    }
+    index.avg_doc_len = if index.chunks.is_empty() {
+        0.0
+    } else {
+        total_len as f64 / index.chunks.len() as f64
+    };
+
+    let chunks_indexed = index.chunks.len();
+    let inventory = inventory_files(&root, max_file_bytes)?;
+    let manifest = FileHashManifest {
+        schema_version: crate::store::FILE_HASH_SCHEMA_VERSION.into(),
+        root: root.to_string_lossy().to_string(),
+        file_hashes: inventory,
+    };
+    save_index(&root, &index)?;
+    save_file_hashes(&root, &manifest)?;
+
+    Ok((
+        index,
+        IndexStats {
+            files_scanned,
+            chunks_indexed,
+            elapsed_ms: started.elapsed().as_millis() as u64,
+            refresh_mode: "full".into(),
+            files_changed: files_scanned,
+            files_removed: 0,
+        },
+    ))
+}
+
+fn should_skip(rel: &str) -> bool {
+    rel.split('/').any(|part| DEFAULT_EXCLUDES.contains(&part))
+}
+
+#[derive(Debug, Clone)]
+struct SymbolSpan {
+    name: String,
+    chunk_type: String,
+    start_line: u32,
+}
+
+fn chunk_file(path: &str, content: &str) -> Vec<Chunk> {
+    let lines: Vec<&str> = content.lines().collect();
+    let total_lines = lines.len().max(1) as u32;
+    let spans = extract_symbol_spans(content);
+
+    if spans.is_empty() {
+        let path_context = path.replace(['/', '.', '-'], " ");
+        return vec![Chunk {
+            path: path.into(),
+            start_line: 1,
+            end_line: total_lines,
+            text: content.to_string(),
+            tokens: tokenize(&format!("{path_context} {content}")),
+            symbol_name: None,
+            chunk_type: "file".into(),
+        }];
+    }
+
+    let preamble: String = lines
+        .iter()
+        .take(spans.first().map(|span| span.start_line as usize).unwrap_or(1).saturating_sub(1))
+        .copied()
+        .collect::<Vec<_>>()
+        .join("\n");
+    let path_context = path.replace(['/', '.', '-'], " ");
+
+    spans
+        .iter()
+        .enumerate()
+        .map(|(index, span)| {
+            let end_line = spans
+                .get(index + 1)
+                .map(|next| next.start_line.saturating_sub(1))
+                .unwrap_or(total_lines)
+                .max(span.start_line);
+            let snippet: String = lines
+                .get((span.start_line as usize).saturating_sub(1)..end_line as usize)
+                .unwrap_or(&[])
+                .join("\n");
+            let chunk_text = if preamble.is_empty() {
+                snippet.clone()
+            } else {
+                format!("{preamble}\n{snippet}")
+            };
+            Chunk {
+                path: path.into(),
+                start_line: span.start_line,
+                end_line,
+                text: chunk_text.clone(),
+                tokens: tokenize(&format!("{path_context} {} {chunk_text}", span.name)),
+                symbol_name: Some(span.name.clone()),
+                chunk_type: span.chunk_type.clone(),
+            }
+        })
+        .collect()
+}
+
+fn extract_symbol_spans(content: &str) -> Vec<SymbolSpan> {
+    let patterns = [
+        (
+            Regex::new(r"(?m)^export\s+(?:async\s+)?function\s+([A-Za-z_][A-Za-z0-9_]*)").unwrap(),
+            "function",
+        ),
+        (
+            Regex::new(r"(?m)^export\s+class\s+([A-Za-z_][A-Za-z0-9_]*)").unwrap(),
+            "class",
+        ),
+        (
+            Regex::new(r"(?m)^export\s+const\s+([A-Za-z_][A-Za-z0-9_]*)\s*=").unwrap(),
+            "const",
+        ),
+        (
+            Regex::new(r"(?m)^(?:async\s+)?function\s+([A-Za-z_][A-Za-z0-9_]*)").unwrap(),
+            "function",
+        ),
+        (
+            Regex::new(r"(?m)^def\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(").unwrap(),
+            "function",
+        ),
+        (
+            Regex::new(r"(?m)^class\s+([A-Za-z_][A-Za-z0-9_]*)").unwrap(),
+            "class",
+        ),
+    ];
+
+    let mut spans = Vec::new();
+    for (pattern, chunk_type) in patterns {
+        for cap in pattern.captures_iter(content) {
+            let name = cap[1].to_string();
+            let start_byte = cap.get(0).map(|m| m.start()).unwrap_or(0);
+            let start_line = content[..start_byte].matches('\n').count() as u32 + 1;
+            spans.push(SymbolSpan {
+                name,
+                chunk_type: chunk_type.into(),
+                start_line,
+            });
+        }
+    }
+
+    spans.sort_by_key(|span| span.start_line);
+    spans.dedup_by(|left, right| left.start_line == right.start_line && left.name == right.name);
+    spans
+}
+
+pub fn search_index(index: &SearchIndex, query: &str, limit: usize) -> Vec<crate::types::SearchHit> {
+    let query_terms = tokenize(query);
+    if query_terms.is_empty() || index.chunks.is_empty() {
+        return vec![];
+    }
+
+    let n_docs = index.chunks.len() as f64;
+    let k1 = 1.2;
+    let b = 0.75;
+
+    let mut scored = Vec::new();
+    for chunk in &index.chunks {
+        let mut score = 0.0;
+        let mut matched = Vec::new();
+        let doc_len = chunk.tokens.len() as f64;
+        let mut term_freq: HashMap<String, usize> = HashMap::new();
+        for token in &chunk.tokens {
+            *term_freq.entry(token.clone()).or_insert(0) += 1;
+        }
+
+        let mut score_components = Vec::new();
+        for term in &query_terms {
+            let tf = *term_freq.get(term).unwrap_or(&0) as f64;
+            if tf == 0.0 {
+                continue;
+            }
+            matched.push(term.clone());
+            let df = *index.doc_freq.get(term).unwrap_or(&1) as f64;
+            let idf = ((n_docs - df + 0.5) / (df + 0.5) + 1.0).ln();
+            let numerator = tf * (k1 + 1.0);
+            let denominator = tf + k1 * (1.0 - b + b * (doc_len / index.avg_doc_len.max(1.0)));
+            let bm25 = idf * (numerator / denominator);
+            score += bm25;
+            score_components.push(ScoreComponent {
+                term: term.clone(),
+                term_frequency: tf,
+                document_frequency: df,
+                idf,
+                bm25,
+            });
+        }
+
+        if score > 0.0 {
+            scored.push(crate::types::SearchHit {
+                path: chunk.path.clone(),
+                score,
+                matched_terms: matched,
+                score_components,
+                start_line: Some(chunk.start_line),
+                end_line: Some(chunk.end_line),
+                snippet: Some(chunk.text.clone()),
+                symbol_name: chunk.symbol_name.clone(),
+                chunk_type: Some(chunk.chunk_type.clone()),
+            });
+        }
+    }
+
+    scored.sort_by(|a, b| b.score.partial_cmp(&a.score).unwrap_or(std::cmp::Ordering::Equal));
+    scored.truncate(limit);
+    scored
+}
+
+pub fn index_path(root: &Path) -> PathBuf {
+    root.join(".coderag").join("rust-index.json")
+}
\ No newline at end of file
diff --git a/crates/coderag-core/src/lib.rs b/crates/coderag-core/src/lib.rs
new file mode 100644
index 0000000..9bd3126
--- /dev/null
+++ b/crates/coderag-core/src/lib.rs
@@ -0,0 +1,100 @@
+//! CodeRAG Rust retrieval core (TF-IDF).
+
+pub mod engine;
+pub mod index;
+pub mod store;
+pub mod tokenize;
+pub mod types;
+
+pub use engine::handle_tool;
+pub use types::{SearchHit, ENGINE_NAME, ENGINE_VERSION};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::path::PathBuf;
+    use std::sync::{Mutex, OnceLock};
+
+    fn fixture_index_lock() -> &'static Mutex<()> {
+        static LOCK: OnceLock<Mutex<()>> = OnceLock::new();
+        LOCK.get_or_init(|| Mutex::new(()))
+    }
+
+    fn fixture_root() -> PathBuf {
+        PathBuf::from(env!("CARGO_MANIFEST_DIR"))
+            .join("../../fixtures/benchmark-corpus")
+            .canonicalize()
+            .expect("fixture corpus")
+    }
+
+    #[test]
+    fn indexes_fixture_corpus() {
+        let (index, stats) = index::build_index(&fixture_root(), 1_048_576).expect("index");
+        assert!(stats.chunks_indexed > 0);
+        assert!(!index.chunks.is_empty());
+    }
+
+    #[test]
+    fn persists_and_reloads_index_snapshot() {
+        let _guard = fixture_index_lock()
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let root = fixture_root();
+        let (index, _) = index::build_index(&root, 1_048_576).expect("index");
+        store::save_index(&root, &index).expect("save");
+        let loaded = store::load_index(&root).expect("load");
+        assert_eq!(loaded.chunks.len(), index.chunks.len());
+        assert_eq!(loaded.root, index.root);
+    }
+
+    #[test]
+    fn finds_auth_login_for_authentication_query() {
+        let (index, _) = index::build_index(&fixture_root(), 1_048_576).expect("index");
+        let hits = index::search_index(&index, "user authentication login", 5);
+        assert!(!hits.is_empty());
+        assert!(hits.iter().any(|hit| hit.path.contains("auth/login")));
+    }
+
+    #[test]
+    fn auto_mode_returns_cache_hit_when_inventory_is_unchanged() {
+        let _guard = fixture_index_lock()
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let root = fixture_root();
+        let first = index::refresh_index(&root, 1_048_576, index::IndexMode::Full).expect("index");
+        let second = index::refresh_index(&root, 1_048_576, index::IndexMode::Auto).expect("refresh");
+        assert_eq!(first.1.refresh_mode, "full");
+        assert_eq!(second.1.refresh_mode, "cache_hit");
+        assert_eq!(first.0.chunks.len(), second.0.chunks.len());
+    }
+
+    #[test]
+    fn search_hits_include_score_components() {
+        let (index, _) = index::build_index(&fixture_root(), 1_048_576).expect("index");
+        let hits = index::search_index(&index, "user authentication login", 1);
+        assert!(!hits.is_empty());
+        assert!(!hits[0].score_components.is_empty());
+        assert!(hits[0].score_components.iter().any(|part| part.bm25 > 0.0));
+    }
+
+    #[test]
+    fn symbol_chunks_include_function_provenance() {
+        let (index, _) = index::build_index(&fixture_root(), 1_048_576).expect("index");
+        let symbol_chunks: Vec<_> = index
+            .chunks
+            .iter()
+            .filter(|chunk| chunk.symbol_name.is_some())
+            .collect();
+        assert!(
+            !symbol_chunks.is_empty(),
+            "expected symbol-aware chunks in benchmark corpus"
+        );
+        assert!(symbol_chunks.iter().any(|chunk| chunk.chunk_type == "function"));
+
+        let hits = index::search_index(&index, "authenticate", 5);
+        assert!(hits.iter().any(|hit| {
+            hit.chunk_type.as_deref() == Some("function")
+                && hit.symbol_name.as_deref() == Some("authenticate")
+        }));
+    }
+}
\ No newline at end of file
diff --git a/crates/coderag-core/src/store.rs b/crates/coderag-core/src/store.rs
new file mode 100644
index 0000000..4ac14ad
--- /dev/null
+++ b/crates/coderag-core/src/store.rs
@@ -0,0 +1,112 @@
+use std::collections::HashMap;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use sha2::{Digest, Sha256};
+
+use crate::index::{index_path, SearchIndex};
+
+pub const INDEX_SCHEMA_VERSION: &str = "0.1.0";
+pub const FILE_HASH_SCHEMA_VERSION: &str = "0.1.0";
+
+#[derive(Debug, serde::Serialize, serde::Deserialize)]
+struct PersistedIndex {
+    schema_version: String,
+    root: String,
+    index: SearchIndex,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct FileHashManifest {
+    pub schema_version: String,
+    pub root: String,
+    pub file_hashes: HashMap<String, String>,
+}
+
+pub fn file_hashes_path(root: &Path) -> PathBuf {
+    root.join(".coderag").join("file-hashes.json")
+}
+
+pub fn hash_file_bytes(path: &Path) -> Result<String, String> {
+    let bytes = fs::read(path).map_err(|err| format!("HASH_FAILED: {err}"))?;
+    Ok(format!("{:x}", Sha256::digest(bytes)))
+}
+
+pub fn save_file_hashes(root: &Path, manifest: &FileHashManifest) -> Result<(), String> {
+    let path = file_hashes_path(root);
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).map_err(|err| format!("HASH_PERSIST_FAILED: {err}"))?;
+    }
+    let bytes =
+        serde_json::to_vec_pretty(manifest).map_err(|err| format!("HASH_PERSIST_FAILED: {err}"))?;
+    fs::write(path, bytes).map_err(|err| format!("HASH_PERSIST_FAILED: {err}"))?;
+    Ok(())
+}
+
+pub fn load_file_hashes(root: &Path) -> Result<FileHashManifest, String> {
+    let path = file_hashes_path(root);
+    let bytes = fs::read(&path).map_err(|err| format!("HASH_NOT_FOUND: {err}"))?;
+    let manifest: FileHashManifest =
+        serde_json::from_slice(&bytes).map_err(|err| format!("HASH_LOAD_FAILED: {err}"))?;
+
+    if manifest.schema_version != FILE_HASH_SCHEMA_VERSION {
+        return Err(format!(
+            "HASH_VERSION_MISMATCH: expected {FILE_HASH_SCHEMA_VERSION}, got {}",
+            manifest.schema_version
+        ));
+    }
+
+    let canonical = root
+        .canonicalize()
+        .map_err(|err| format!("INVALID_ROOT: {err}"))?
+        .to_string_lossy()
+        .to_string();
+
+    if manifest.root != canonical {
+        return Err("HASH_ROOT_MISMATCH: persisted hash manifest belongs to a different repository root.".into());
+    }
+
+    Ok(manifest)
+}
+
+pub fn save_index(root: &Path, index: &SearchIndex) -> Result<(), String> {
+    let path = index_path(root);
+    if let Some(parent) = path.parent() {
+        fs::create_dir_all(parent).map_err(|err| format!("INDEX_PERSIST_FAILED: {err}"))?;
+    }
+
+    let snapshot = PersistedIndex {
+        schema_version: INDEX_SCHEMA_VERSION.into(),
+        root: index.root.clone(),
+        index: index.clone(),
+    };
+    let bytes = serde_json::to_vec(&snapshot).map_err(|err| format!("INDEX_PERSIST_FAILED: {err}"))?;
+    fs::write(&path, bytes).map_err(|err| format!("INDEX_PERSIST_FAILED: {err}"))?;
+    Ok(())
+}
+
+pub fn load_index(root: &Path) -> Result<SearchIndex, String> {
+    let path = index_path(root);
+    let bytes = fs::read(&path).map_err(|err| format!("INDEX_NOT_FOUND: {err}"))?;
+    let snapshot: PersistedIndex =
+        serde_json::from_slice(&bytes).map_err(|err| format!("INDEX_LOAD_FAILED: {err}"))?;
+
+    if snapshot.schema_version != INDEX_SCHEMA_VERSION {
+        return Err(format!(
+            "INDEX_VERSION_MISMATCH: expected {INDEX_SCHEMA_VERSION}, got {}",
+            snapshot.schema_version
+        ));
+    }
+
+    let canonical = root
+        .canonicalize()
+        .map_err(|err| format!("INVALID_ROOT: {err}"))?
+        .to_string_lossy()
+        .to_string();
+
+    if snapshot.root != canonical {
+        return Err("INDEX_ROOT_MISMATCH: persisted snapshot belongs to a different repository root.".into());
+    }
+
+    Ok(snapshot.index)
+}
\ No newline at end of file
diff --git a/crates/coderag-core/src/tokenize.rs b/crates/coderag-core/src/tokenize.rs
new file mode 100644
index 0000000..66ecb1d
--- /dev/null
+++ b/crates/coderag-core/src/tokenize.rs
@@ -0,0 +1,24 @@
+use std::collections::HashSet;
+
+pub fn tokenize(text: &str) -> Vec<String> {
+    let mut tokens = Vec::new();
+    let mut current = String::new();
+    for ch in text.chars() {
+        if ch.is_ascii_alphanumeric() || ch == '_' {
+            current.push(ch.to_ascii_lowercase());
+        } else if !current.is_empty() {
+            if current.len() > 1 {
+                tokens.push(current.clone());
+            }
+            current.clear();
+        }
+    }
+    if !current.is_empty() && current.len() > 1 {
+        tokens.push(current);
+    }
+    tokens
+}
+
+pub fn unique_terms(tokens: &[String]) -> HashSet<String> {
+    tokens.iter().cloned().collect()
+}
\ No newline at end of file
diff --git a/crates/coderag-core/src/types.rs b/crates/coderag-core/src/types.rs
new file mode 100644
index 0000000..03faac9
--- /dev/null
+++ b/crates/coderag-core/src/types.rs
@@ -0,0 +1,108 @@
+use serde::{Deserialize, Serialize};
+
+pub const ENGINE_NAME: &str = "coderag-core";
+pub const ENGINE_VERSION: &str = "0.1.0";
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ScoreComponent {
+    pub term: String,
+    pub term_frequency: f64,
+    pub document_frequency: f64,
+    pub idf: f64,
+    pub bm25: f64,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SearchHit {
+    pub path: String,
+    pub score: f64,
+    pub matched_terms: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub score_components: Vec<ScoreComponent>,
+    pub start_line: Option<u32>,
+    pub end_line: Option<u32>,
+    pub snippet: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub symbol_name: Option<String>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub chunk_type: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct IndexStats {
+    pub files_scanned: usize,
+    pub chunks_indexed: usize,
+    pub elapsed_ms: u64,
+    pub refresh_mode: String,
+    pub files_changed: usize,
+    pub files_removed: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct SearchStats {
+    pub elapsed_ms: u64,
+    pub route: String,
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct ToolEnvelope {
+    pub status: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub query: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub results: Option<Vec<SearchHit>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub index: Option<IndexStats>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub search: Option<SearchStats>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub code: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub message: Option<String>,
+}
+
+impl ToolEnvelope {
+    pub fn ok_search(query: &str, results: Vec<SearchHit>, elapsed_ms: u64) -> Self {
+        Self {
+            status: "ok".into(),
+            query: Some(query.into()),
+            results: Some(results),
+            index: None,
+            search: Some(SearchStats {
+                elapsed_ms,
+                route: "rust-tfidf".into(),
+            }),
+            code: None,
+            message: None,
+        }
+    }
+
+    pub fn ok_index(stats: IndexStats) -> Self {
+        Self {
+            status: "ok".into(),
+            query: None,
+            results: None,
+            index: Some(stats),
+            search: None,
+            code: None,
+            message: None,
+        }
+    }
+
+    pub fn error(code: &str, message: &str) -> Self {
+        Self {
+            status: "error".into(),
+            query: None,
+            results: None,
+            index: None,
+            search: None,
+            code: Some(code.into()),
+            message: Some(message.into()),
+        }
+    }
+}
\ No newline at end of file
diff --git a/crates/coderag-mcp-server/Cargo.toml b/crates/coderag-mcp-server/Cargo.toml
new file mode 100644
index 0000000..63b2158
--- /dev/null
+++ b/crates/coderag-mcp-server/Cargo.toml
@@ -0,0 +1,21 @@
+[package]
+name = "coderag-mcp-server"
+version = "0.1.0"
+edition = "2021"
+license = "MIT"
+description = "Rust-native MCP server for coderag (rmcp)"
+
+[lib]
+path = "src/lib.rs"
+
+[[bin]]
+name = "coderag-mcp-server"
+path = "src/main.rs"
+
+[dependencies]
+anyhow = "1"
+coderag-core = { path = "../coderag-core" }
+rmcp = { version = "0.16.0", features = ["server", "transport-io"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["full"] }
\ No newline at end of file
diff --git a/crates/coderag-mcp-server/src/cli_bridge.rs b/crates/coderag-mcp-server/src/cli_bridge.rs
new file mode 100644
index 0000000..8cf9de7
--- /dev/null
+++ b/crates/coderag-mcp-server/src/cli_bridge.rs
@@ -0,0 +1,122 @@
+use std::io::Write;
+use std::path::PathBuf;
+use std::process::{Command, Stdio};
+
+use rmcp::model::CallToolResult;
+use serde_json::Value;
+
+#[derive(Debug, serde::Deserialize)]
+struct CliSuccess {
+    status: String,
+    #[serde(flatten)]
+    payload: Value,
+}
+
+#[derive(Debug, serde::Deserialize)]
+struct CliError {
+    status: String,
+    message: Option<String>,
+    code: Option<String>,
+}
+
+pub fn resolve_cli_binary() -> Option<PathBuf> {
+    if let Ok(path) = std::env::var("CODERAG_RUST_CLI") {
+        let candidate = PathBuf::from(path);
+        if candidate.is_file() {
+            return Some(candidate);
+        }
+    }
+
+    if let Ok(exe) = std::env::current_exe() {
+        if let Some(parent) = exe.parent() {
+            if let Some(package_root) = parent.parent() {
+                for candidate in [
+                    package_root.join("target/release/coderag-cli"),
+                    package_root.join("target/debug/coderag-cli"),
+                    package_root.join("bin/native/coderag-cli"),
+                ] {
+                    if candidate.is_file() {
+                        return Some(candidate);
+                    }
+                }
+            }
+        }
+    }
+
+    for candidate in [
+        PathBuf::from("target/release/coderag-cli"),
+        PathBuf::from("target/debug/coderag-cli"),
+    ] {
+        if candidate.is_file() {
+            return Some(candidate);
+        }
+    }
+
+    None
+}
+
+pub fn invoke_cli_tool(tool: &str, arguments: Value) -> Result<CallToolResult, rmcp::ErrorData> {
+    let cli = resolve_cli_binary().ok_or_else(|| {
+        rmcp::ErrorData::invalid_request(
+            "coderag-cli is unavailable. Run `bun run build:rust`.",
+            None,
+        )
+    })?;
+
+    let request = serde_json::json!({ "tool": tool, "input": arguments });
+    let payload = serde_json::to_string(&request).map_err(|error| {
+        rmcp::ErrorData::internal_error(format!("Failed to serialize CLI request: {error}"), None)
+    })?;
+
+    let mut child = Command::new(cli)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .map_err(|error| {
+            rmcp::ErrorData::internal_error(format!("Failed to spawn coderag-cli: {error}"), None)
+        })?;
+
+    if let Some(mut stdin) = child.stdin.take() {
+        stdin.write_all(payload.as_bytes()).map_err(|error| {
+            rmcp::ErrorData::internal_error(format!("Failed to write CLI request: {error}"), None)
+        })?;
+    }
+
+    let output = child.wait_with_output().map_err(|error| {
+        rmcp::ErrorData::internal_error(format!("coderag-cli failed: {error}"), None)
+    })?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        return Err(rmcp::ErrorData::internal_error(
+            format!(
+                "coderag-cli exited with status {:?}: {stderr}",
+                output.status.code()
+            ),
+            None,
+        ));
+    }
+
+    let stdout = String::from_utf8(output.stdout).map_err(|error| {
+        rmcp::ErrorData::internal_error(
+            format!("coderag-cli returned non-UTF8 output: {error}"),
+            None,
+        )
+    })?;
+
+    let envelope: Value = serde_json::from_str(&stdout).map_err(|error| {
+        rmcp::ErrorData::internal_error(format!("coderag-cli returned invalid JSON: {error}"), None)
+    })?;
+
+    if envelope.get("status").and_then(Value::as_str) != Some("ok") {
+        let message = envelope
+            .get("message")
+            .and_then(Value::as_str)
+            .or_else(|| envelope.get("code").and_then(Value::as_str))
+            .unwrap_or("coderag-cli returned an error envelope");
+        return Err(rmcp::ErrorData::internal_error(message.to_string(), None));
+    }
+
+    Ok(CallToolResult::structured(envelope))
+}
\ No newline at end of file
diff --git a/crates/coderag-mcp-server/src/codebase_search.rs b/crates/coderag-mcp-server/src/codebase_search.rs
new file mode 100644
index 0000000..4c23746
--- /dev/null
+++ b/crates/coderag-mcp-server/src/codebase_search.rs
@@ -0,0 +1,45 @@
+use rmcp::model::CallToolResult;
+use serde_json::{json, Value};
+
+use crate::cli_bridge;
+
+pub const CODEBASE_SEARCH_ROUTE: &str = "rust-tfidf";
+
+pub fn codebase_search(args: Value) -> Result<CallToolResult, rmcp::ErrorData> {
+    let root = args
+        .get("root")
+        .and_then(Value::as_str)
+        .map(str::to_string)
+        .or_else(|| std::env::var("CODERAG_ROOT").ok())
+        .ok_or_else(|| {
+            rmcp::ErrorData::invalid_params(
+                "root is required (pass in tool args or set CODERAG_ROOT)",
+                None,
+            )
+        })?;
+
+    let query = args
+        .get("query")
+        .and_then(Value::as_str)
+        .ok_or_else(|| rmcp::ErrorData::invalid_params("query is required", None))?;
+
+    let limit = args.get("limit").and_then(Value::as_u64).unwrap_or(10);
+
+    let _ = cli_bridge::invoke_cli_tool(
+        "coderag_index",
+        json!({ "root": root, "mode": "auto" }),
+    )?;
+
+    let mut search = cli_bridge::invoke_cli_tool(
+        "coderag_search",
+        json!({ "root": root, "query": query, "limit": limit }),
+    )?;
+
+    if let Some(structured) = search.structured_content.as_mut() {
+        structured["tool"] = json!("codebase_search");
+        structured["route"] = json!(CODEBASE_SEARCH_ROUTE);
+        structured["engine"] = json!(coderag_core::ENGINE_NAME);
+    }
+
+    Ok(search)
+}
\ No newline at end of file
diff --git a/crates/coderag-mcp-server/src/lib.rs b/crates/coderag-mcp-server/src/lib.rs
new file mode 100644
index 0000000..967bc8a
--- /dev/null
+++ b/crates/coderag-mcp-server/src/lib.rs
@@ -0,0 +1,89 @@
+pub mod cli_bridge;
+pub mod codebase_search;
+pub mod tool_routes;
+
+use rmcp::{
+    handler::server::router::tool::ToolRouter,
+    handler::server::wrapper::Parameters,
+    model::{Implementation, ServerCapabilities, ServerInfo},
+    tool, tool_handler, tool_router, ErrorData, ServerHandler,
+};
+use serde_json::Value;
+
+pub const SERVER_NAME: &str = "coderag-mcp";
+pub const SERVER_VERSION: &str = "0.3.33";
+pub const SERVER_INSTRUCTIONS: &str =
+    "CodeRAG MCP server (Rust rmcp transport). Use codebase_search for deterministic Rust TF-IDF retrieval with score explainability.";
+
+#[derive(Clone)]
+pub struct CoderagMcp {
+    pub tool_router: ToolRouter<Self>,
+}
+
+impl CoderagMcp {
+    pub fn new() -> Self {
+        Self {
+            tool_router: Self::tool_router(),
+        }
+    }
+}
+
+#[tool_router]
+impl CoderagMcp {
+    #[tool(
+        description = "Search the codebase with Rust TF-IDF retrieval. Returns ranked hits with path, score, matched terms, and score components."
+    )]
+    pub fn codebase_search(
+        &self,
+        Parameters(args): Parameters<Value>,
+    ) -> Result<rmcp::model::CallToolResult, ErrorData> {
+        codebase_search::codebase_search(args)
+    }
+}
+
+#[tool_handler]
+impl ServerHandler for CoderagMcp {
+    fn get_info(&self) -> ServerInfo {
+        ServerInfo {
+            protocol_version: rmcp::model::ProtocolVersion::default(),
+            capabilities: ServerCapabilities::builder().enable_tools().build(),
+            server_info: Implementation {
+                name: SERVER_NAME.into(),
+                title: None,
+                version: SERVER_VERSION.into(),
+                description: Some(
+                    "Rust-native MCP server for coderag (modelcontextprotocol/rust-sdk rmcp)".into(),
+                ),
+                icons: None,
+                website_url: Some("https://github.com/SylphxAI/coderag".into()),
+            },
+            instructions: Some(SERVER_INSTRUCTIONS.into()),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::CoderagMcp;
+    use std::fs;
+    use std::path::PathBuf;
+
+    #[test]
+    fn rmcp_server_sources_route_codebase_search_through_rust_core() {
+        let src_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("src");
+        let lib_rs = fs::read_to_string(src_dir.join("lib.rs")).expect("read lib.rs");
+        let production_lib = lib_rs.split("#[cfg(test)]").next().unwrap_or(&lib_rs);
+        assert!(production_lib.contains("codebase_search::codebase_search"));
+
+        let routes = fs::read_to_string(src_dir.join("tool_routes.rs")).expect("read tool_routes");
+        assert!(routes.contains("codebase_search"));
+        assert!(routes.contains("RustCore"));
+    }
+
+    #[test]
+    fn exposes_codebase_search_tool_surface() {
+        let tools = CoderagMcp::new().tool_router.list_all();
+        let names: Vec<_> = tools.iter().map(|tool| tool.name.to_string()).collect();
+        assert!(names.contains(&"codebase_search".to_string()));
+    }
+}
\ No newline at end of file
diff --git a/crates/coderag-mcp-server/src/main.rs b/crates/coderag-mcp-server/src/main.rs
new file mode 100644
index 0000000..2c62657
--- /dev/null
+++ b/crates/coderag-mcp-server/src/main.rs
@@ -0,0 +1,22 @@
+use coderag_mcp_server::{cli_bridge, CoderagMcp, SERVER_VERSION};
+use rmcp::ServiceExt;
+
+#[tokio::main]
+async fn main() -> anyhow::Result<()> {
+    if std::env::args().nth(1).as_deref() == Some("doctor") {
+        eprintln!(
+            "coderag-mcp Rust MCP server {SERVER_VERSION} ({})",
+            coderag_core::ENGINE_NAME
+        );
+        if let Some(cli) = cli_bridge::resolve_cli_binary() {
+            eprintln!("engine cli: {}", cli.display());
+        } else {
+            eprintln!("engine cli: unavailable (run `bun run build:rust`)");
+        }
+        return Ok(());
+    }
+
+    let service = CoderagMcp::new().serve(rmcp::transport::stdio()).await?;
+    service.waiting().await?;
+    Ok(())
+}
\ No newline at end of file
diff --git a/crates/coderag-mcp-server/src/tool_routes.rs b/crates/coderag-mcp-server/src/tool_routes.rs
new file mode 100644
index 0000000..b8a5de1
--- /dev/null
+++ b/crates/coderag-mcp-server/src/tool_routes.rs
@@ -0,0 +1,30 @@
+//! Explicit shipped routing table for coderag primary tools.
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToolRoute {
+    RustCore,
+    LegacyOptIn,
+}
+
+pub fn route_for_tool(tool: &str) -> Option<ToolRoute> {
+    match tool {
+        "codebase_search" | "coderag_index" | "coderag_search" => Some(ToolRoute::RustCore),
+        _ => None,
+    }
+}
+
+pub fn is_rust_core_tool(tool: &str) -> bool {
+    matches!(route_for_tool(tool), Some(ToolRoute::RustCore))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn maps_primary_tools_to_explicit_routes() {
+        assert_eq!(route_for_tool("codebase_search"), Some(ToolRoute::RustCore));
+        assert_eq!(route_for_tool("coderag_search"), Some(ToolRoute::RustCore));
+        assert_eq!(route_for_tool("coderag_index"), Some(ToolRoute::RustCore));
+    }
+}
\ No newline at end of file
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 354b84a..030744b 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'vitepress'
 
 const title = 'CodeRAG'
 const description =
-	'Lightning-fast semantic code search with AST chunking - RAG-ready for AI assistants'
+	'Local-first hybrid code search with AST chunking — did your agent find the right code?'
 const url = 'https://coderag.sylphx.com'
 const ogImage = `${url}/og-image.png`
 
@@ -68,6 +68,11 @@ export default defineConfig({
 			{
 				text: 'Resources',
 				items: [
+					{ text: 'Benchmark proof', link: '/benchmark' },
+					{
+						text: 'Stop code-search guessing',
+						link: '/articles/stop-code-search-guessing',
+					},
 					{ text: 'GitHub', link: 'https://github.com/SylphxAI/coderag' },
 					{ text: 'npm', link: 'https://www.npmjs.com/package/@sylphx/coderag' },
 					{ text: 'Changelog', link: 'https://github.com/SylphxAI/coderag/releases' },
diff --git a/docs/articles/stop-code-search-guessing.md b/docs/articles/stop-code-search-guessing.md
new file mode 100644
index 0000000..42b32e8
--- /dev/null
+++ b/docs/articles/stop-code-search-guessing.md
@@ -0,0 +1,71 @@
+# Stop Your Agent From Guessing Which Code Snippet Matters
+
+You asked Claude to fix the login bug. It edited `src/utils/helpers.ts` — a file
+that has nothing to do with authentication.
+
+That is not a model failure. It is a **code search workflow failure**.
+
+## What actually went wrong
+
+Most agent stacks search code one of two ways:
+
+1. **grep/ripgrep** — literal match. Fast, but blind to synonyms and intent.
+2. **Cloud RAG** — semantic, but heavy setup, cold starts, and whole-file chunks.
+
+Both often return **too much text in the wrong shape**. The model picks a
+plausible-looking snippet and runs with it.
+
+## Three failures you cannot fix with a better prompt
+
+| Failure | What the agent sees | What actually happened |
+| --- | --- | --- |
+| Literal-only match | "No results" or random hits | Query said "login flow", code says `authenticateUser` |
+| Whole-file dump | 400 lines of context | Only 12 lines in one function matter |
+| Stale index | Old snippet | File changed since last scan; agent patches dead code |
+
+No system prompt fixes the wrong chunk.
+
+## What chunk-level hybrid search changes
+
+CodeRAG indexes at **AST boundaries** — functions, classes, methods — and ranks
+with hybrid TF-IDF (plus optional vectors when you want them):
+
+- **Semantic chunks** the agent can read without burning context.
+- **Scored results** so the best match surfaces first.
+- **Local index** with SQLite persistence and incremental updates.
+- **MCP-first** setup — no Docker, ChromaDB, or cloud pipeline required.
+
+The agent still uses a language model. The difference is it works from **the
+right code block**, not a directory of keyword accidents.
+
+## Try the fix in 30 seconds
+
+```bash
+claude mcp add coderag -- npx @sylphx/coderag-mcp --root=/absolute/path/to/project
+```
+
+```json
+{
+  "query": "user authentication login",
+  "limit": 5,
+  "exclude_paths": ["node_modules", "dist"]
+}
+```
+
+Point at your repo. Search returns ranked function-level chunks — not whole
+files, not cloud latency.
+
+## Verify the claims
+
+```bash
+bun run benchmark:public-proof
+```
+
+Reproducible indexing throughput and search latency on a fixed in-repo corpus.
+See [benchmark proof](/benchmark) for methodology.
+
+## Share this
+
+- [CodeRAG on GitHub](https://github.com/SylphxAI/coderag)
+- [MCP server docs](/mcp/overview)
+- [⭐ Star the repo](https://github.com/SylphxAI/coderag) — help other builders stop guessing
\ No newline at end of file
diff --git a/docs/benchmark.md b/docs/benchmark.md
new file mode 100644
index 0000000..de15cc2
--- /dev/null
+++ b/docs/benchmark.md
@@ -0,0 +1,85 @@
+---
+layout: doc
+
+title: Benchmark Proof
+description: Reproducible public benchmark for CodeRAG — indexing throughput and search latency on a fixed in-repo corpus.
+---
+
+# Benchmark Proof
+
+CodeRAG public performance claims are backed by a single checked-in script and a
+fixed fixture corpus — not hand-tuned marketing numbers.
+
+## What Gets Measured
+
+| Phase | What it proves |
+| --- | --- |
+| **Indexing** | Files/sec on `fixtures/benchmark-corpus/` (30 TypeScript files, AST chunking) |
+| **Search** | TF-IDF search p50 / min / max latency over 20 iterations (3 warmup) |
+
+The benchmark uses in-memory storage (`MemoryStorage`) and `lowMemoryMode: false`
+to measure best-case local search latency on the fixture corpus. Results are
+machine- and fixture-specific.
+
+## Reproduce
+
+```bash
+bun install
+bun run build
+bun run benchmark:public-proof
+```
+
+The script prints JSON to stdout and a human-readable summary to stderr.
+
+Example output shape:
+
+```json
+{
+  "profile": "coderag-public-proof",
+  "corpus": {
+    "fixtureTypeScriptFiles": 30,
+    "indexedFiles": "<from script>",
+    "indexedChunks": "<from script>"
+  },
+  "indexing": {
+    "durationMs": "<from script>",
+    "filesPerSecond": "<from script>"
+  },
+  "search": {
+    "iterations": 20,
+    "warmupIterations": 3,
+    "p50Ms": "<from script>",
+    "minMs": "<from script>",
+    "maxMs": "<from script>",
+    "avgMs": "<from script>"
+  }
+}
+```
+
+> **Note:** Run the script on your machine and paste the output here when
+> updating release notes. Do not edit the numbers in README or this page without
+> running `bun run benchmark:public-proof`.
+
+## Latest Run
+
+Run `bun run benchmark:public-proof` locally to populate this table for your
+environment. Commit updated numbers only from actual script output.
+
+| Metric | Result |
+| --- | --- |
+| Fixture corpus | 30 TypeScript files → 31 indexed files, 71 chunks |
+| Indexing throughput | **186.1 files/sec** (166.6 ms total; run 2 of 2) |
+| Search p50 (TF-IDF) | **0.0 ms** (20 iterations, 3 warmup) |
+| Search min / max | **0.0 ms / 0.5 ms** (avg 0.0 ms) |
+
+## What This Proves
+
+- **Indexing is bounded** on a fixed corpus — throughput is measurable and reproducible.
+- **Search latency is bounded** on a warm index — p50/min/max come from 20 timed runs.
+- **Claims stay honest** — README performance section links here; no invented MacBook tables.
+
+## Fixture Corpus
+
+The corpus lives at `fixtures/benchmark-corpus/src/` and covers auth, database,
+API, middleware, utilities, and services modules. Do not edit fixtures without
+re-running the benchmark.
\ No newline at end of file
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index 928c4b8..5f06394 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -105,3 +105,5 @@ const results = await indexer.search('database connection pool', {
 - [Installation](/guide/installation) - Install CodeRAG in your project
 - [Quick Start](/guide/quick-start) - Build your first search index
 - [MCP Server](/mcp/overview) - Use with AI assistants
+- [Stop code-search guessing](/articles/stop-code-search-guessing) - Why chunk-level search beats grep dumps
+- [Benchmark proof](/benchmark) - Reproducible indexing and search latency
diff --git a/docs/index.md b/docs/index.md
index aa10240..0c9581d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -3,8 +3,8 @@ layout: home
 
 hero:
   name: CodeRAG
-  text: Semantic Code Search
-  tagline: Lightning-fast hybrid search with AST chunking - RAG-ready for AI assistants
+  text: Did it find the right code?
+  tagline: Local-first hybrid search with AST chunking — MCP-ready for AI assistants
   image:
     src: /logo.svg
     alt: CodeRAG
@@ -23,8 +23,8 @@ features:
   - icon:
       svg: '<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="currentColor" d="M13 2.03v2.02c4.39.54 7.5 4.53 6.96 8.92c-.46 3.64-3.32 6.53-6.96 6.96v2c5.5-.55 9.5-5.43 8.95-10.93c-.45-4.75-4.22-8.5-8.95-8.97m-2 .03c-1.95.19-3.81.94-5.33 2.2L7.1 5.74c1.12-.9 2.47-1.48 3.9-1.68zM4.26 5.67A9.9 9.9 0 0 0 2.05 11h2c.19-1.42.75-2.77 1.64-3.9zM2.06 13c.2 1.96.97 3.81 2.21 5.33l1.42-1.43A8 8 0 0 1 4.06 13zm5.04 5.37l-1.43 1.37A10 10 0 0 0 11 21.95v-2c-1.42-.2-2.77-.76-3.9-1.58M12 8l-4 4h3v4h2v-4h3z"/></svg>'
     title: Blazing Fast
-    details: Index 1000-2000 files/sec with instant startup (<100ms). Incremental updates only reindex changed files.
-    link: /guide/performance
+    details: Fast indexing with SQLite persistence and incremental updates. Reproduce throughput with the public benchmark script.
+    link: /benchmark
     linkText: Learn more
 
   - icon:
@@ -102,8 +102,8 @@ console.log(results)
 
 Built with performance in mind from day one:
 
-- **Fast Indexing**: 1000-2000 files/second
-- **Instant Startup**: <100ms with cached index
+- **Fast Indexing**: Reproducible throughput — see [benchmark proof](/benchmark)
+- **Instant Startup**: SQLite-backed cache for warm restarts
 - **Low Memory**: SQL-based search mode available
 - **Incremental Updates**: Only reindex changed files
 
diff --git a/examples/codebase-search-request.json b/examples/codebase-search-request.json
new file mode 100644
index 0000000..7044707
--- /dev/null
+++ b/examples/codebase-search-request.json
@@ -0,0 +1,6 @@
+{
+	"query": "user authentication login",
+	"limit": 5,
+	"file_extensions": [".ts", ".tsx"],
+	"exclude_paths": ["node_modules", "dist", ".git"]
+}
diff --git a/fixtures/benchmark-corpus/.coderag/file-hashes.json b/fixtures/benchmark-corpus/.coderag/file-hashes.json
new file mode 100644
index 0000000..18f005b
--- /dev/null
+++ b/fixtures/benchmark-corpus/.coderag/file-hashes.json
@@ -0,0 +1,37 @@
+{
+	"schema_version": "0.1.0",
+	"root": "/home/codex/src/github.com/SylphxAI/coderag/fixtures/benchmark-corpus",
+	"file_hashes": {
+		"src/auth/token.ts": "29d3020699648b57355b2fac8b8e4cac74ce4aca0660c528635313271bd49aaf",
+		"src/auth/session.ts": "3642bb9dd52c2ead0bb1a1348d4cb8dda47c8f5363179a84ddd24c787eae64d1",
+		"src/utils/cache.ts": "75ecf5370dc9a6238af210b0ac84780ac7fdcb965ce084a7e63f0f60528df763",
+		"src/middleware/compression.ts": "634754a0e6f408b97addfa7b57e527df678ea9c4d81056563ef7fe7fc44dc83a",
+		"src/utils/hash.ts": "634c6608d0e799cf45e80b66850e586212f040d03b6b0cfa0c2d4adf2e75d840",
+		"src/index.ts": "996da7626e314dd2601b20e2be0fd35a6c4d82c97e2305f946ec0626b2959f80",
+		"src/middleware/cors.ts": "842d0b357e768431f59037d5aab1fec0f20075513e6c130ee19a278f2e6fe806",
+		"src/utils/retry.ts": "71129d55e5f103a6aa9118d85b9d6c9c325e5d5fc35e418cc125e18a086aa7c7",
+		"src/db/migrations.ts": "a13f4985b9ee4f12393d7a7017ef5eaf1f18c451b392e0b6319ee5f233a40587",
+		"src/services/search-service.ts": "c81d284b74b7f6a0bb10549cd6699ef3d77571c337aabed8dbaf34ec6310c491",
+		"src/services/billing-service.ts": "f0a26a473ccd879446f9da79210c128fcfc4ff866cf50cc9c15c52e3a34e473a",
+		"src/api/rate-limit.ts": "52d203f6eace62610ff1e08231dead70cd8d7d6575c07a49689e90d37f8fd584",
+		"README.md": "e58c907e2d476414c42257f11669790e31aef2599347fe64e5f7d0db73db68a7",
+		"src/auth/login.ts": "0151fbac31146e2f194e36fa61c3a595dcc6f0907d138450cf84f3b17e1a83d9",
+		"src/db/pool.ts": "e7133e9cc6635d186846abfe5361257da123f8383985c3986f5487a7dbcb721f",
+		"src/middleware/auth.ts": "8bd60dde8f14efadc28287d5061bb4630e376e7d1bb72ad592bc03a7d9f8bfcf",
+		"src/auth/permissions.ts": "7b4dc3c00898710058d0226d2ba6d6e6df0e147b6ac2803df3557cabdb753620",
+		"src/utils/array.ts": "0f7f06ebde5f32b642196fe0d2e2ba443912ddcb1983be03fe45584beb12bfad",
+		"src/db/connection.ts": "f7be81695dd3152f66e646da13faffcbe3d319b6d4ff4f107a96e976c305e37e",
+		"src/db/transaction.ts": "37f5d9070bccd0de4cf38730d71628b9c20a54eece6633a2ad807065b8bb63fe",
+		"src/middleware/logging.ts": "4f1000ebef31e0e21e31d2a030a03e966d3eac33a764c69061c93f59cca004db",
+		"src/auth/oauth.ts": "0f975030ee72588755419a884825df4da2744041f3523e2afc9295593f2f2947",
+		"src/api/handlers.ts": "f16b5318f17f83bfc2444196ea149d9cd5cd6c8e01c022c7beecec7d866d94cc",
+		"src/api/validation.ts": "824b394ffef9f638628be7bc35f7545ef0aa6003555acfca49972e00781bea5a",
+		"src/api/router.ts": "0bc465361d7edd2b736e5d83211c7dbbb1da792a339dfcdea6df7b83867dc766",
+		"src/services/notification-service.ts": "6bb5ea945ddc5583e4af4fe4a6dbe1af7ebe2d24e81e5b11a67b8c25c1e07cb7",
+		"src/utils/string.ts": "52df5082de27b13edc85175d907729910eaa9e5819640a02b21434f5bac73f93",
+		"src/services/user-service.ts": "5aa1fbb73d6d173682653ffac5eb5cf5b6853c611aca78f93e111ac072858667",
+		"src/db/repository.ts": "65d183d926cacb9b6a12aba12b9babf9b70f516b74a8a13ca8584999f4d30193",
+		"src/api/errors.ts": "c7a2dba7d293b3e79c7b0d4a8941d566e784f45b430655d8740cb0ad56b6e175",
+		"src/middleware/error-handler.ts": "5718a1c592b22f89d5135ae6b6ee651ae625da7d5973c1c4459446173bcbe3a7"
+	}
+}
diff --git a/fixtures/benchmark-corpus/.coderag/rust-index.json b/fixtures/benchmark-corpus/.coderag/rust-index.json
new file mode 100644
index 0000000..4bb3524
--- /dev/null
+++ b/fixtures/benchmark-corpus/.coderag/rust-index.json
@@ -0,0 +1,2754 @@
+{
+	"schema_version": "0.1.0",
+	"root": "/home/codex/src/github.com/SylphxAI/coderag/fixtures/benchmark-corpus",
+	"index": {
+		"root": "/home/codex/src/github.com/SylphxAI/coderag/fixtures/benchmark-corpus",
+		"chunks": [
+			{
+				"path": "README.md",
+				"start_line": 1,
+				"end_line": 5,
+				"text": "# Benchmark Corpus\n\nFixed in-repo TypeScript fixture corpus for `bun run benchmark:public-proof`.\n\nDo not edit files here without re-running the benchmark and updating `docs/benchmark.md`.",
+				"tokens": [
+					"readme",
+					"md",
+					"benchmark",
+					"corpus",
+					"fixed",
+					"in",
+					"repo",
+					"typescript",
+					"fixture",
+					"corpus",
+					"for",
+					"bun",
+					"run",
+					"benchmark",
+					"public",
+					"proof",
+					"do",
+					"not",
+					"edit",
+					"files",
+					"here",
+					"without",
+					"re",
+					"running",
+					"the",
+					"benchmark",
+					"and",
+					"updating",
+					"docs",
+					"benchmark",
+					"md"
+				],
+				"chunk_type": "file"
+			},
+			{
+				"path": "src/api/router.ts",
+				"start_line": 3,
+				"end_line": 20,
+				"text": "export type Handler = (req: Request) => Promise<Response>\n\nexport class Router {\n\tprivate routes = new Map<string, Handler>()\n\n\tget(path: string, handler: Handler): void {\n\t\tthis.routes.set(`GET:${path}`, handler)\n\t}\n\n\tpost(path: string, handler: Handler): void {\n\t\tthis.routes.set(`POST:${path}`, handler)\n\t}\n\n\tasync handle(req: Request): Promise<Response> {\n\t\tconst key = `${req.method}:${new URL(req.url).pathname}`\n\t\tconst handler = this.routes.get(key)\n\t\tif (!handler) return new Response('not found', { status: 404 })\n\t\treturn handler(req)\n\t}\n}",
+				"tokens": [
+					"src",
+					"api",
+					"router",
+					"ts",
+					"router",
+					"export",
+					"type",
+					"handler",
+					"req",
+					"request",
+					"promise",
+					"response",
+					"export",
+					"class",
+					"router",
+					"private",
+					"routes",
+					"new",
+					"map",
+					"string",
+					"handler",
+					"get",
+					"path",
+					"string",
+					"handler",
+					"handler",
+					"void",
+					"this",
+					"routes",
+					"set",
+					"get",
+					"path",
+					"handler",
+					"post",
+					"path",
+					"string",
+					"handler",
+					"handler",
+					"void",
+					"this",
+					"routes",
+					"set",
+					"post",
+					"path",
+					"handler",
+					"async",
+					"handle",
+					"req",
+					"request",
+					"promise",
+					"response",
+					"const",
+					"key",
+					"req",
+					"method",
+					"new",
+					"url",
+					"req",
+					"url",
+					"pathname",
+					"const",
+					"handler",
+					"this",
+					"routes",
+					"get",
+					"key",
+					"if",
+					"handler",
+					"return",
+					"new",
+					"response",
+					"not",
+					"found",
+					"status",
+					"404",
+					"return",
+					"handler",
+					"req"
+				],
+				"symbol_name": "Router",
+				"chunk_type": "class"
+			},
+			{
+				"path": "src/api/rate-limit.ts",
+				"start_line": 3,
+				"end_line": 13,
+				"text": "const buckets = new Map<string, { count: number; resetAt: number }>()\n\nexport function checkRateLimit(key: string, limit = 100, windowMs = 60_000): boolean {\n\tconst now = Date.now()\n\tconst bucket = buckets.get(key)\n\tif (!bucket || bucket.resetAt < now) {\n\t\tbuckets.set(key, { count: 1, resetAt: now + windowMs })\n\t\treturn true\n\t}\n\tif (bucket.count >= limit) return false\n\tbucket.count += 1\n\treturn true\n}",
+				"tokens": [
+					"src",
+					"api",
+					"rate",
+					"limit",
+					"ts",
+					"checkratelimit",
+					"const",
+					"buckets",
+					"new",
+					"map",
+					"string",
+					"count",
+					"number",
+					"resetat",
+					"number",
+					"export",
+					"function",
+					"checkratelimit",
+					"key",
+					"string",
+					"limit",
+					"100",
+					"windowms",
+					"60_000",
+					"boolean",
+					"const",
+					"now",
+					"date",
+					"now",
+					"const",
+					"bucket",
+					"buckets",
+					"get",
+					"key",
+					"if",
+					"bucket",
+					"bucket",
+					"resetat",
+					"now",
+					"buckets",
+					"set",
+					"key",
+					"count",
+					"resetat",
+					"now",
+					"windowms",
+					"return",
+					"true",
+					"if",
+					"bucket",
+					"count",
+					"limit",
+					"return",
+					"false",
+					"bucket",
+					"count",
+					"return",
+					"true"
+				],
+				"symbol_name": "checkRateLimit",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/api/validation.ts",
+				"start_line": 1,
+				"end_line": 4,
+				"text": "export function validateEmail(email: string): boolean {\n\treturn /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(email)\n}\n",
+				"tokens": [
+					"src",
+					"api",
+					"validation",
+					"ts",
+					"validateemail",
+					"export",
+					"function",
+					"validateemail",
+					"email",
+					"string",
+					"boolean",
+					"return",
+					"test",
+					"email"
+				],
+				"symbol_name": "validateEmail",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/api/validation.ts",
+				"start_line": 5,
+				"end_line": 8,
+				"text": "export function validatePasswordStrength(password: string): boolean {\n\treturn password.length >= 8 && /[A-Z]/.test(password) && /[0-9]/.test(password)\n}\n",
+				"tokens": [
+					"src",
+					"api",
+					"validation",
+					"ts",
+					"validatepasswordstrength",
+					"export",
+					"function",
+					"validatepasswordstrength",
+					"password",
+					"string",
+					"boolean",
+					"return",
+					"password",
+					"length",
+					"test",
+					"password",
+					"test",
+					"password"
+				],
+				"symbol_name": "validatePasswordStrength",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/api/validation.ts",
+				"start_line": 9,
+				"end_line": 14,
+				"text": "export function parsePagination(searchParams: URLSearchParams) {\n\treturn {\n\t\tlimit: Math.min(Number(searchParams.get('limit') ?? 20), 100),\n\t\toffset: Number(searchParams.get('offset') ?? 0),\n\t}\n}",
+				"tokens": [
+					"src",
+					"api",
+					"validation",
+					"ts",
+					"parsepagination",
+					"export",
+					"function",
+					"parsepagination",
+					"searchparams",
+					"urlsearchparams",
+					"return",
+					"limit",
+					"math",
+					"min",
+					"number",
+					"searchparams",
+					"get",
+					"limit",
+					"20",
+					"100",
+					"offset",
+					"number",
+					"searchparams",
+					"get",
+					"offset"
+				],
+				"symbol_name": "parsePagination",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/api/errors.ts",
+				"start_line": 1,
+				"end_line": 11,
+				"text": "export class ApiError extends Error {\n\tconstructor(\n\t\tmessage: string,\n\t\treadonly status: number,\n\t\treadonly code: string\n\t) {\n\t\tsuper(message)\n\t\tthis.name = 'ApiError'\n\t}\n}\n",
+				"tokens": [
+					"src",
+					"api",
+					"errors",
+					"ts",
+					"apierror",
+					"export",
+					"class",
+					"apierror",
+					"extends",
+					"error",
+					"constructor",
+					"message",
+					"string",
+					"readonly",
+					"status",
+					"number",
+					"readonly",
+					"code",
+					"string",
+					"super",
+					"message",
+					"this",
+					"name",
+					"apierror"
+				],
+				"symbol_name": "ApiError",
+				"chunk_type": "class"
+			},
+			{
+				"path": "src/api/errors.ts",
+				"start_line": 12,
+				"end_line": 17,
+				"text": "export function toErrorResponse(error: unknown): Response {\n\tif (error instanceof ApiError) {\n\t\treturn Response.json({ error: error.code, message: error.message }, { status: error.status })\n\t}\n\treturn Response.json({ error: 'internal_error' }, { status: 500 })\n}",
+				"tokens": [
+					"src",
+					"api",
+					"errors",
+					"ts",
+					"toerrorresponse",
+					"export",
+					"function",
+					"toerrorresponse",
+					"error",
+					"unknown",
+					"response",
+					"if",
+					"error",
+					"instanceof",
+					"apierror",
+					"return",
+					"response",
+					"json",
+					"error",
+					"error",
+					"code",
+					"message",
+					"error",
+					"message",
+					"status",
+					"error",
+					"status",
+					"return",
+					"response",
+					"json",
+					"error",
+					"internal_error",
+					"status",
+					"500"
+				],
+				"symbol_name": "toErrorResponse",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/api/handlers.ts",
+				"start_line": 1,
+				"end_line": 4,
+				"text": "export async function handleHealthCheck(): Promise<Response> {\n\treturn Response.json({ status: 'ok' })\n}\n",
+				"tokens": [
+					"src",
+					"api",
+					"handlers",
+					"ts",
+					"handlehealthcheck",
+					"export",
+					"async",
+					"function",
+					"handlehealthcheck",
+					"promise",
+					"response",
+					"return",
+					"response",
+					"json",
+					"status",
+					"ok"
+				],
+				"symbol_name": "handleHealthCheck",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/api/handlers.ts",
+				"start_line": 5,
+				"end_line": 10,
+				"text": "export async function handleUserList(req: Request): Promise<Response> {\n\tconst url = new URL(req.url)\n\tconst limit = Number(url.searchParams.get('limit') ?? 10)\n\treturn Response.json({ users: [], limit })\n}\n",
+				"tokens": [
+					"src",
+					"api",
+					"handlers",
+					"ts",
+					"handleuserlist",
+					"export",
+					"async",
+					"function",
+					"handleuserlist",
+					"req",
+					"request",
+					"promise",
+					"response",
+					"const",
+					"url",
+					"new",
+					"url",
+					"req",
+					"url",
+					"const",
+					"limit",
+					"number",
+					"url",
+					"searchparams",
+					"get",
+					"limit",
+					"10",
+					"return",
+					"response",
+					"json",
+					"users",
+					"limit"
+				],
+				"symbol_name": "handleUserList",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/api/handlers.ts",
+				"start_line": 11,
+				"end_line": 14,
+				"text": "export async function handleCreateUser(req: Request): Promise<Response> {\n\tconst body = await req.json()\n\treturn Response.json({ created: true, user: body }, { status: 201 })\n}",
+				"tokens": [
+					"src",
+					"api",
+					"handlers",
+					"ts",
+					"handlecreateuser",
+					"export",
+					"async",
+					"function",
+					"handlecreateuser",
+					"req",
+					"request",
+					"promise",
+					"response",
+					"const",
+					"body",
+					"await",
+					"req",
+					"json",
+					"return",
+					"response",
+					"json",
+					"created",
+					"true",
+					"user",
+					"body",
+					"status",
+					"201"
+				],
+				"symbol_name": "handleCreateUser",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/db/transaction.ts",
+				"start_line": 1,
+				"end_line": 12,
+				"text": "export async function withTransaction<T>(fn: () => Promise<T>): Promise<T> {\n\tawait beginTransaction()\n\ttry {\n\t\tconst result = await fn()\n\t\tawait commitTransaction()\n\t\treturn result\n\t} catch (error) {\n\t\tawait rollbackTransaction()\n\t\tthrow error\n\t}\n}\n",
+				"tokens": [
+					"src",
+					"db",
+					"transaction",
+					"ts",
+					"withtransaction",
+					"export",
+					"async",
+					"function",
+					"withtransaction",
+					"fn",
+					"promise",
+					"promise",
+					"await",
+					"begintransaction",
+					"try",
+					"const",
+					"result",
+					"await",
+					"fn",
+					"await",
+					"committransaction",
+					"return",
+					"result",
+					"catch",
+					"error",
+					"await",
+					"rollbacktransaction",
+					"throw",
+					"error"
+				],
+				"symbol_name": "withTransaction",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/db/transaction.ts",
+				"start_line": 13,
+				"end_line": 13,
+				"text": "async function beginTransaction(): Promise<void> {}",
+				"tokens": [
+					"src",
+					"db",
+					"transaction",
+					"ts",
+					"begintransaction",
+					"async",
+					"function",
+					"begintransaction",
+					"promise",
+					"void"
+				],
+				"symbol_name": "beginTransaction",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/db/transaction.ts",
+				"start_line": 14,
+				"end_line": 14,
+				"text": "async function commitTransaction(): Promise<void> {}",
+				"tokens": [
+					"src",
+					"db",
+					"transaction",
+					"ts",
+					"committransaction",
+					"async",
+					"function",
+					"committransaction",
+					"promise",
+					"void"
+				],
+				"symbol_name": "commitTransaction",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/db/transaction.ts",
+				"start_line": 15,
+				"end_line": 15,
+				"text": "async function rollbackTransaction(): Promise<void> {}",
+				"tokens": [
+					"src",
+					"db",
+					"transaction",
+					"ts",
+					"rollbacktransaction",
+					"async",
+					"function",
+					"rollbacktransaction",
+					"promise",
+					"void"
+				],
+				"symbol_name": "rollbackTransaction",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/db/connection.ts",
+				"start_line": 1,
+				"end_line": 17,
+				"text": "export class DatabaseConnection {\n\tprivate connected = false\n\n\tasync connect(connectionString: string): Promise<void> {\n\t\tif (!connectionString) throw new Error('connection string required')\n\t\tthis.connected = true\n\t}\n\n\tasync query<T>(sql: string, params: unknown[] = []): Promise<T[]> {\n\t\tif (!this.connected) throw new Error('not connected')\n\t\treturn [] as T[]\n\t}\n\n\tasync disconnect(): Promise<void> {\n\t\tthis.connected = false\n\t}\n}",
+				"tokens": [
+					"src",
+					"db",
+					"connection",
+					"ts",
+					"databaseconnection",
+					"export",
+					"class",
+					"databaseconnection",
+					"private",
+					"connected",
+					"false",
+					"async",
+					"connect",
+					"connectionstring",
+					"string",
+					"promise",
+					"void",
+					"if",
+					"connectionstring",
+					"throw",
+					"new",
+					"error",
+					"connection",
+					"string",
+					"required",
+					"this",
+					"connected",
+					"true",
+					"async",
+					"query",
+					"sql",
+					"string",
+					"params",
+					"unknown",
+					"promise",
+					"if",
+					"this",
+					"connected",
+					"throw",
+					"new",
+					"error",
+					"not",
+					"connected",
+					"return",
+					"as",
+					"async",
+					"disconnect",
+					"promise",
+					"void",
+					"this",
+					"connected",
+					"false"
+				],
+				"symbol_name": "DatabaseConnection",
+				"chunk_type": "class"
+			},
+			{
+				"path": "src/db/repository.ts",
+				"start_line": 7,
+				"end_line": 19,
+				"text": "export interface Repository<T> {\n\tfindById(id: string): Promise<T | null>\n\tsave(entity: T): Promise<void>\n\tdelete(id: string): Promise<void>\n}\n\nexport class UserRepository implements Repository<{ id: string; email: string }> {\n\tasync findById(id: string) {\n\t\treturn { id, email: `${id}@example.com` }\n\t}\n\n\tasync save(entity: { id: string; email: string }): Promise<void> {\n\t\tvoid entity\n\t}\n\n\tasync delete(id: string): Promise<void> {\n\t\tvoid id\n\t}\n}",
+				"tokens": [
+					"src",
+					"db",
+					"repository",
+					"ts",
+					"userrepository",
+					"export",
+					"interface",
+					"repository",
+					"findbyid",
+					"id",
+					"string",
+					"promise",
+					"null",
+					"save",
+					"entity",
+					"promise",
+					"void",
+					"delete",
+					"id",
+					"string",
+					"promise",
+					"void",
+					"export",
+					"class",
+					"userrepository",
+					"implements",
+					"repository",
+					"id",
+					"string",
+					"email",
+					"string",
+					"async",
+					"findbyid",
+					"id",
+					"string",
+					"return",
+					"id",
+					"email",
+					"id",
+					"example",
+					"com",
+					"async",
+					"save",
+					"entity",
+					"id",
+					"string",
+					"email",
+					"string",
+					"promise",
+					"void",
+					"void",
+					"entity",
+					"async",
+					"delete",
+					"id",
+					"string",
+					"promise",
+					"void",
+					"void",
+					"id"
+				],
+				"symbol_name": "UserRepository",
+				"chunk_type": "class"
+			},
+			{
+				"path": "src/db/pool.ts",
+				"start_line": 3,
+				"end_line": 22,
+				"text": "import { DatabaseConnection } from './connection.js'\n\nexport class ConnectionPool {\n\tprivate readonly connections: DatabaseConnection[] = []\n\n\tconstructor(private readonly size: number) {}\n\n\tasync acquire(): Promise<DatabaseConnection> {\n\t\tconst conn = new DatabaseConnection()\n\t\tawait conn.connect('postgres://localhost/app')\n\t\tthis.connections.push(conn)\n\t\treturn conn\n\t}\n\n\tasync release(conn: DatabaseConnection): Promise<void> {\n\t\tawait conn.disconnect()\n\t}\n\n\tget activeCount(): number {\n\t\treturn this.connections.length\n\t}\n}",
+				"tokens": [
+					"src",
+					"db",
+					"pool",
+					"ts",
+					"connectionpool",
+					"import",
+					"databaseconnection",
+					"from",
+					"connection",
+					"js",
+					"export",
+					"class",
+					"connectionpool",
+					"private",
+					"readonly",
+					"connections",
+					"databaseconnection",
+					"constructor",
+					"private",
+					"readonly",
+					"size",
+					"number",
+					"async",
+					"acquire",
+					"promise",
+					"databaseconnection",
+					"const",
+					"conn",
+					"new",
+					"databaseconnection",
+					"await",
+					"conn",
+					"connect",
+					"postgres",
+					"localhost",
+					"app",
+					"this",
+					"connections",
+					"push",
+					"conn",
+					"return",
+					"conn",
+					"async",
+					"release",
+					"conn",
+					"databaseconnection",
+					"promise",
+					"void",
+					"await",
+					"conn",
+					"disconnect",
+					"get",
+					"activecount",
+					"number",
+					"return",
+					"this",
+					"connections",
+					"length"
+				],
+				"symbol_name": "ConnectionPool",
+				"chunk_type": "class"
+			},
+			{
+				"path": "src/db/migrations.ts",
+				"start_line": 16,
+				"end_line": 24,
+				"text": "export interface Migration {\n\tid: string\n\tup: string\n\tdown: string\n}\n\nexport const migrations: Migration[] = [\n\t{ id: '001_users', up: 'CREATE TABLE users (id TEXT PRIMARY KEY)', down: 'DROP TABLE users' },\n\t{\n\t\tid: '002_sessions',\n\t\tup: 'CREATE TABLE sessions (id TEXT PRIMARY KEY)',\n\t\tdown: 'DROP TABLE sessions',\n\t},\n]\n\nexport async function runMigrations(applied: Set<string>): Promise<string[]> {\n\tconst ran: string[] = []\n\tfor (const migration of migrations) {\n\t\tif (!applied.has(migration.id)) {\n\t\t\tran.push(migration.id)\n\t\t}\n\t}\n\treturn ran\n}",
+				"tokens": [
+					"src",
+					"db",
+					"migrations",
+					"ts",
+					"runmigrations",
+					"export",
+					"interface",
+					"migration",
+					"id",
+					"string",
+					"up",
+					"string",
+					"down",
+					"string",
+					"export",
+					"const",
+					"migrations",
+					"migration",
+					"id",
+					"001_users",
+					"up",
+					"create",
+					"table",
+					"users",
+					"id",
+					"text",
+					"primary",
+					"key",
+					"down",
+					"drop",
+					"table",
+					"users",
+					"id",
+					"002_sessions",
+					"up",
+					"create",
+					"table",
+					"sessions",
+					"id",
+					"text",
+					"primary",
+					"key",
+					"down",
+					"drop",
+					"table",
+					"sessions",
+					"export",
+					"async",
+					"function",
+					"runmigrations",
+					"applied",
+					"set",
+					"string",
+					"promise",
+					"string",
+					"const",
+					"ran",
+					"string",
+					"for",
+					"const",
+					"migration",
+					"of",
+					"migrations",
+					"if",
+					"applied",
+					"has",
+					"migration",
+					"id",
+					"ran",
+					"push",
+					"migration",
+					"id",
+					"return",
+					"ran"
+				],
+				"symbol_name": "runMigrations",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/session.ts",
+				"start_line": 7,
+				"end_line": 14,
+				"text": "export interface Session {\n\tid: string\n\tuserId: string\n\texpiresAt: Date\n}\n\nexport function createSession(userId: string, ttlMs = 86_400_000): Session {\n\treturn {\n\t\tid: crypto.randomUUID(),\n\t\tuserId,\n\t\texpiresAt: new Date(Date.now() + ttlMs),\n\t}\n}\n",
+				"tokens": [
+					"src",
+					"auth",
+					"session",
+					"ts",
+					"createsession",
+					"export",
+					"interface",
+					"session",
+					"id",
+					"string",
+					"userid",
+					"string",
+					"expiresat",
+					"date",
+					"export",
+					"function",
+					"createsession",
+					"userid",
+					"string",
+					"ttlms",
+					"86_400_000",
+					"session",
+					"return",
+					"id",
+					"crypto",
+					"randomuuid",
+					"userid",
+					"expiresat",
+					"new",
+					"date",
+					"date",
+					"now",
+					"ttlms"
+				],
+				"symbol_name": "createSession",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/session.ts",
+				"start_line": 15,
+				"end_line": 17,
+				"text": "export interface Session {\n\tid: string\n\tuserId: string\n\texpiresAt: Date\n}\n\nexport function isSessionValid(session: Session): boolean {\n\treturn session.expiresAt.getTime() > Date.now()\n}",
+				"tokens": [
+					"src",
+					"auth",
+					"session",
+					"ts",
+					"issessionvalid",
+					"export",
+					"interface",
+					"session",
+					"id",
+					"string",
+					"userid",
+					"string",
+					"expiresat",
+					"date",
+					"export",
+					"function",
+					"issessionvalid",
+					"session",
+					"session",
+					"boolean",
+					"return",
+					"session",
+					"expiresat",
+					"gettime",
+					"date",
+					"now"
+				],
+				"symbol_name": "isSessionValid",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/permissions.ts",
+				"start_line": 9,
+				"end_line": 12,
+				"text": "export type Role = 'admin' | 'editor' | 'viewer'\n\nconst ROLE_PERMISSIONS: Record<Role, string[]> = {\n\tadmin: ['read', 'write', 'delete', 'manage_users'],\n\teditor: ['read', 'write'],\n\tviewer: ['read'],\n}\n\nexport function hasPermission(role: Role, permission: string): boolean {\n\treturn ROLE_PERMISSIONS[role].includes(permission)\n}\n",
+				"tokens": [
+					"src",
+					"auth",
+					"permissions",
+					"ts",
+					"haspermission",
+					"export",
+					"type",
+					"role",
+					"admin",
+					"editor",
+					"viewer",
+					"const",
+					"role_permissions",
+					"record",
+					"role",
+					"string",
+					"admin",
+					"read",
+					"write",
+					"delete",
+					"manage_users",
+					"editor",
+					"read",
+					"write",
+					"viewer",
+					"read",
+					"export",
+					"function",
+					"haspermission",
+					"role",
+					"role",
+					"permission",
+					"string",
+					"boolean",
+					"return",
+					"role_permissions",
+					"role",
+					"includes",
+					"permission"
+				],
+				"symbol_name": "hasPermission",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/permissions.ts",
+				"start_line": 13,
+				"end_line": 15,
+				"text": "export type Role = 'admin' | 'editor' | 'viewer'\n\nconst ROLE_PERMISSIONS: Record<Role, string[]> = {\n\tadmin: ['read', 'write', 'delete', 'manage_users'],\n\teditor: ['read', 'write'],\n\tviewer: ['read'],\n}\n\nexport function canManageUsers(role: Role): boolean {\n\treturn hasPermission(role, 'manage_users')\n}",
+				"tokens": [
+					"src",
+					"auth",
+					"permissions",
+					"ts",
+					"canmanageusers",
+					"export",
+					"type",
+					"role",
+					"admin",
+					"editor",
+					"viewer",
+					"const",
+					"role_permissions",
+					"record",
+					"role",
+					"string",
+					"admin",
+					"read",
+					"write",
+					"delete",
+					"manage_users",
+					"editor",
+					"read",
+					"write",
+					"viewer",
+					"read",
+					"export",
+					"function",
+					"canmanageusers",
+					"role",
+					"role",
+					"boolean",
+					"return",
+					"haspermission",
+					"role",
+					"manage_users"
+				],
+				"symbol_name": "canManageUsers",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/token.ts",
+				"start_line": 1,
+				"end_line": 5,
+				"text": "export function signAccessToken(userId: string, secret: string): string {\n\tconst payload = JSON.stringify({ sub: userId, iat: Date.now() })\n\treturn Buffer.from(`${payload}.${secret}`).toString('base64url')\n}\n",
+				"tokens": [
+					"src",
+					"auth",
+					"token",
+					"ts",
+					"signaccesstoken",
+					"export",
+					"function",
+					"signaccesstoken",
+					"userid",
+					"string",
+					"secret",
+					"string",
+					"string",
+					"const",
+					"payload",
+					"json",
+					"stringify",
+					"sub",
+					"userid",
+					"iat",
+					"date",
+					"now",
+					"return",
+					"buffer",
+					"from",
+					"payload",
+					"secret",
+					"tostring",
+					"base64url"
+				],
+				"symbol_name": "signAccessToken",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/token.ts",
+				"start_line": 6,
+				"end_line": 11,
+				"text": "export function verifyAccessToken(token: string, secret: string): string | null {\n\tconst decoded = Buffer.from(token, 'base64url').toString('utf8')\n\tconst [payload, sig] = decoded.split('.')\n\tif (sig !== secret) return null\n\treturn JSON.parse(payload).sub as string\n}",
+				"tokens": [
+					"src",
+					"auth",
+					"token",
+					"ts",
+					"verifyaccesstoken",
+					"export",
+					"function",
+					"verifyaccesstoken",
+					"token",
+					"string",
+					"secret",
+					"string",
+					"string",
+					"null",
+					"const",
+					"decoded",
+					"buffer",
+					"from",
+					"token",
+					"base64url",
+					"tostring",
+					"utf8",
+					"const",
+					"payload",
+					"sig",
+					"decoded",
+					"split",
+					"if",
+					"sig",
+					"secret",
+					"return",
+					"null",
+					"return",
+					"json",
+					"parse",
+					"payload",
+					"sub",
+					"as",
+					"string"
+				],
+				"symbol_name": "verifyAccessToken",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/oauth.ts",
+				"start_line": 1,
+				"end_line": 8,
+				"text": "export async function exchangeOAuthCode(code: string, redirectUri: string) {\n\tconst response = await fetch('https://oauth.example/token', {\n\t\tmethod: 'POST',\n\t\tbody: JSON.stringify({ code, redirectUri }),\n\t})\n\treturn response.json()\n}\n",
+				"tokens": [
+					"src",
+					"auth",
+					"oauth",
+					"ts",
+					"exchangeoauthcode",
+					"export",
+					"async",
+					"function",
+					"exchangeoauthcode",
+					"code",
+					"string",
+					"redirecturi",
+					"string",
+					"const",
+					"response",
+					"await",
+					"fetch",
+					"https",
+					"oauth",
+					"example",
+					"token",
+					"method",
+					"post",
+					"body",
+					"json",
+					"stringify",
+					"code",
+					"redirecturi",
+					"return",
+					"response",
+					"json"
+				],
+				"symbol_name": "exchangeOAuthCode",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/oauth.ts",
+				"start_line": 9,
+				"end_line": 12,
+				"text": "export function buildAuthorizationUrl(clientId: string, scope: string[]): string {\n\tconst params = new URLSearchParams({ client_id: clientId, scope: scope.join(' ') })\n\treturn `https://oauth.example/authorize?${params}`\n}",
+				"tokens": [
+					"src",
+					"auth",
+					"oauth",
+					"ts",
+					"buildauthorizationurl",
+					"export",
+					"function",
+					"buildauthorizationurl",
+					"clientid",
+					"string",
+					"scope",
+					"string",
+					"string",
+					"const",
+					"params",
+					"new",
+					"urlsearchparams",
+					"client_id",
+					"clientid",
+					"scope",
+					"scope",
+					"join",
+					"return",
+					"https",
+					"oauth",
+					"example",
+					"authorize",
+					"params"
+				],
+				"symbol_name": "buildAuthorizationUrl",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/login.ts",
+				"start_line": 1,
+				"end_line": 5,
+				"text": "export async function authenticate(username: string, password: string): Promise<boolean> {\n\tconst user = await findUserByEmail(username)\n\treturn validatePassword(user, password)\n}\n",
+				"tokens": [
+					"src",
+					"auth",
+					"login",
+					"ts",
+					"authenticate",
+					"export",
+					"async",
+					"function",
+					"authenticate",
+					"username",
+					"string",
+					"password",
+					"string",
+					"promise",
+					"boolean",
+					"const",
+					"user",
+					"await",
+					"finduserbyemail",
+					"username",
+					"return",
+					"validatepassword",
+					"user",
+					"password"
+				],
+				"symbol_name": "authenticate",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/login.ts",
+				"start_line": 6,
+				"end_line": 9,
+				"text": "export async function findUserByEmail(email: string) {\n\treturn { id: '1', email, passwordHash: 'hash' }\n}\n",
+				"tokens": [
+					"src",
+					"auth",
+					"login",
+					"ts",
+					"finduserbyemail",
+					"export",
+					"async",
+					"function",
+					"finduserbyemail",
+					"email",
+					"string",
+					"return",
+					"id",
+					"email",
+					"passwordhash",
+					"hash"
+				],
+				"symbol_name": "findUserByEmail",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/login.ts",
+				"start_line": 10,
+				"end_line": 13,
+				"text": "export function validatePassword(user: { passwordHash: string }, password: string): boolean {\n\treturn user.passwordHash === hashPassword(password)\n}\n",
+				"tokens": [
+					"src",
+					"auth",
+					"login",
+					"ts",
+					"validatepassword",
+					"export",
+					"function",
+					"validatepassword",
+					"user",
+					"passwordhash",
+					"string",
+					"password",
+					"string",
+					"boolean",
+					"return",
+					"user",
+					"passwordhash",
+					"hashpassword",
+					"password"
+				],
+				"symbol_name": "validatePassword",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/auth/login.ts",
+				"start_line": 14,
+				"end_line": 16,
+				"text": "function hashPassword(password: string): string {\n\treturn `hashed:${password}`\n}",
+				"tokens": [
+					"src",
+					"auth",
+					"login",
+					"ts",
+					"hashpassword",
+					"function",
+					"hashpassword",
+					"password",
+					"string",
+					"string",
+					"return",
+					"hashed",
+					"password"
+				],
+				"symbol_name": "hashPassword",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/logging.ts",
+				"start_line": 1,
+				"end_line": 5,
+				"text": "export function logRequest(req: Request): void {\n\tconst url = new URL(req.url)\n\tconsole.error(`[req] ${req.method} ${url.pathname}`)\n}\n",
+				"tokens": [
+					"src",
+					"middleware",
+					"logging",
+					"ts",
+					"logrequest",
+					"export",
+					"function",
+					"logrequest",
+					"req",
+					"request",
+					"void",
+					"const",
+					"url",
+					"new",
+					"url",
+					"req",
+					"url",
+					"console",
+					"error",
+					"req",
+					"req",
+					"method",
+					"url",
+					"pathname"
+				],
+				"symbol_name": "logRequest",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/logging.ts",
+				"start_line": 6,
+				"end_line": 9,
+				"text": "export function logResponse(status: number, durationMs: number): void {\n\tconsole.error(`[res] ${status} ${durationMs}ms`)\n}\n",
+				"tokens": [
+					"src",
+					"middleware",
+					"logging",
+					"ts",
+					"logresponse",
+					"export",
+					"function",
+					"logresponse",
+					"status",
+					"number",
+					"durationms",
+					"number",
+					"void",
+					"console",
+					"error",
+					"res",
+					"status",
+					"durationms",
+					"ms"
+				],
+				"symbol_name": "logResponse",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/logging.ts",
+				"start_line": 10,
+				"end_line": 13,
+				"text": "export function withTiming<T>(fn: () => Promise<T>): Promise<{ result: T; durationMs: number }> {\n\tconst start = performance.now()\n\treturn fn().then((result) => ({ result, durationMs: performance.now() - start }))\n}",
+				"tokens": [
+					"src",
+					"middleware",
+					"logging",
+					"ts",
+					"withtiming",
+					"export",
+					"function",
+					"withtiming",
+					"fn",
+					"promise",
+					"promise",
+					"result",
+					"durationms",
+					"number",
+					"const",
+					"start",
+					"performance",
+					"now",
+					"return",
+					"fn",
+					"then",
+					"result",
+					"result",
+					"durationms",
+					"performance",
+					"now",
+					"start"
+				],
+				"symbol_name": "withTiming",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/auth.ts",
+				"start_line": 3,
+				"end_line": 11,
+				"text": "import { verifyAccessToken } from '../auth/token.js'\n\nexport async function authMiddleware(req: Request, secret: string): Promise<Request | Response> {\n\tconst header = req.headers.get('authorization')\n\tif (!header?.startsWith('Bearer ')) {\n\t\treturn new Response('unauthorized', { status: 401 })\n\t}\n\tconst userId = verifyAccessToken(header.slice(7), secret)\n\tif (!userId) return new Response('invalid token', { status: 401 })\n\treturn req\n}",
+				"tokens": [
+					"src",
+					"middleware",
+					"auth",
+					"ts",
+					"authmiddleware",
+					"import",
+					"verifyaccesstoken",
+					"from",
+					"auth",
+					"token",
+					"js",
+					"export",
+					"async",
+					"function",
+					"authmiddleware",
+					"req",
+					"request",
+					"secret",
+					"string",
+					"promise",
+					"request",
+					"response",
+					"const",
+					"header",
+					"req",
+					"headers",
+					"get",
+					"authorization",
+					"if",
+					"header",
+					"startswith",
+					"bearer",
+					"return",
+					"new",
+					"response",
+					"unauthorized",
+					"status",
+					"401",
+					"const",
+					"userid",
+					"verifyaccesstoken",
+					"header",
+					"slice",
+					"secret",
+					"if",
+					"userid",
+					"return",
+					"new",
+					"response",
+					"invalid",
+					"token",
+					"status",
+					"401",
+					"return",
+					"req"
+				],
+				"symbol_name": "authMiddleware",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/compression.ts",
+				"start_line": 1,
+				"end_line": 5,
+				"text": "export function shouldCompress(req: Request): boolean {\n\tconst accept = req.headers.get('accept-encoding') ?? ''\n\treturn accept.includes('gzip') || accept.includes('br')\n}\n",
+				"tokens": [
+					"src",
+					"middleware",
+					"compression",
+					"ts",
+					"shouldcompress",
+					"export",
+					"function",
+					"shouldcompress",
+					"req",
+					"request",
+					"boolean",
+					"const",
+					"accept",
+					"req",
+					"headers",
+					"get",
+					"accept",
+					"encoding",
+					"return",
+					"accept",
+					"includes",
+					"gzip",
+					"accept",
+					"includes",
+					"br"
+				],
+				"symbol_name": "shouldCompress",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/compression.ts",
+				"start_line": 6,
+				"end_line": 8,
+				"text": "export function compressBody(body: string): Uint8Array {\n\treturn new TextEncoder().encode(body)\n}",
+				"tokens": [
+					"src",
+					"middleware",
+					"compression",
+					"ts",
+					"compressbody",
+					"export",
+					"function",
+					"compressbody",
+					"body",
+					"string",
+					"uint8array",
+					"return",
+					"new",
+					"textencoder",
+					"encode",
+					"body"
+				],
+				"symbol_name": "compressBody",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/cors.ts",
+				"start_line": 1,
+				"end_line": 8,
+				"text": "export function corsHeaders(origin = '*'): HeadersInit {\n\treturn {\n\t\t'Access-Control-Allow-Origin': origin,\n\t\t'Access-Control-Allow-Methods': 'GET,POST,PUT,DELETE,OPTIONS',\n\t\t'Access-Control-Allow-Headers': 'Content-Type, Authorization',\n\t}\n}\n",
+				"tokens": [
+					"src",
+					"middleware",
+					"cors",
+					"ts",
+					"corsheaders",
+					"export",
+					"function",
+					"corsheaders",
+					"origin",
+					"headersinit",
+					"return",
+					"access",
+					"control",
+					"allow",
+					"origin",
+					"origin",
+					"access",
+					"control",
+					"allow",
+					"methods",
+					"get",
+					"post",
+					"put",
+					"delete",
+					"options",
+					"access",
+					"control",
+					"allow",
+					"headers",
+					"content",
+					"type",
+					"authorization"
+				],
+				"symbol_name": "corsHeaders",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/cors.ts",
+				"start_line": 9,
+				"end_line": 12,
+				"text": "export function handlePreflight(req: Request): Response | null {\n\tif (req.method !== 'OPTIONS') return null\n\treturn new Response(null, { status: 204, headers: corsHeaders() })\n}",
+				"tokens": [
+					"src",
+					"middleware",
+					"cors",
+					"ts",
+					"handlepreflight",
+					"export",
+					"function",
+					"handlepreflight",
+					"req",
+					"request",
+					"response",
+					"null",
+					"if",
+					"req",
+					"method",
+					"options",
+					"return",
+					"null",
+					"return",
+					"new",
+					"response",
+					"null",
+					"status",
+					"204",
+					"headers",
+					"corsheaders"
+				],
+				"symbol_name": "handlePreflight",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/middleware/error-handler.ts",
+				"start_line": 3,
+				"end_line": 9,
+				"text": "import { toErrorResponse } from '../api/errors.js'\n\nexport async function errorHandler(fn: () => Promise<Response>): Promise<Response> {\n\ttry {\n\t\treturn await fn()\n\t} catch (error) {\n\t\treturn toErrorResponse(error)\n\t}\n}",
+				"tokens": [
+					"src",
+					"middleware",
+					"error",
+					"handler",
+					"ts",
+					"errorhandler",
+					"import",
+					"toerrorresponse",
+					"from",
+					"api",
+					"errors",
+					"js",
+					"export",
+					"async",
+					"function",
+					"errorhandler",
+					"fn",
+					"promise",
+					"response",
+					"promise",
+					"response",
+					"try",
+					"return",
+					"await",
+					"fn",
+					"catch",
+					"error",
+					"return",
+					"toerrorresponse",
+					"error"
+				],
+				"symbol_name": "errorHandler",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/services/notification-service.ts",
+				"start_line": 7,
+				"end_line": 10,
+				"text": "export interface Notification {\n\tuserId: string\n\tchannel: 'email' | 'sms' | 'push'\n\tmessage: string\n}\n\nexport async function sendNotification(notification: Notification): Promise<void> {\n\tconsole.error(`notify:${notification.channel} -> ${notification.userId}`)\n}\n",
+				"tokens": [
+					"src",
+					"services",
+					"notification",
+					"service",
+					"ts",
+					"sendnotification",
+					"export",
+					"interface",
+					"notification",
+					"userid",
+					"string",
+					"channel",
+					"email",
+					"sms",
+					"push",
+					"message",
+					"string",
+					"export",
+					"async",
+					"function",
+					"sendnotification",
+					"notification",
+					"notification",
+					"promise",
+					"void",
+					"console",
+					"error",
+					"notify",
+					"notification",
+					"channel",
+					"notification",
+					"userid"
+				],
+				"symbol_name": "sendNotification",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/services/notification-service.ts",
+				"start_line": 11,
+				"end_line": 13,
+				"text": "export interface Notification {\n\tuserId: string\n\tchannel: 'email' | 'sms' | 'push'\n\tmessage: string\n}\n\nexport async function sendWelcomeEmail(userId: string, email: string): Promise<void> {\n\tawait sendNotification({ userId, channel: 'email', message: `Welcome ${email}` })\n}",
+				"tokens": [
+					"src",
+					"services",
+					"notification",
+					"service",
+					"ts",
+					"sendwelcomeemail",
+					"export",
+					"interface",
+					"notification",
+					"userid",
+					"string",
+					"channel",
+					"email",
+					"sms",
+					"push",
+					"message",
+					"string",
+					"export",
+					"async",
+					"function",
+					"sendwelcomeemail",
+					"userid",
+					"string",
+					"email",
+					"string",
+					"promise",
+					"void",
+					"await",
+					"sendnotification",
+					"userid",
+					"channel",
+					"email",
+					"message",
+					"welcome",
+					"email"
+				],
+				"symbol_name": "sendWelcomeEmail",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/services/search-service.ts",
+				"start_line": 7,
+				"end_line": 18,
+				"text": "export interface SearchHit {\n\tpath: string\n\tscore: number\n\tsnippet: string\n}\n\nexport function rankResults(query: string, hits: SearchHit[]): SearchHit[] {\n\tconst terms = query.toLowerCase().split(/\\s+/)\n\treturn hits\n\t\t.map((hit) => ({\n\t\t\t...hit,\n\t\t\tscore: terms.reduce(\n\t\t\t\t(score, term) => (hit.snippet.toLowerCase().includes(term) ? score + 1 : score),\n\t\t\t\thit.score\n\t\t\t),\n\t\t}))\n\t\t.sort((a, b) => b.score - a.score)\n}",
+				"tokens": [
+					"src",
+					"services",
+					"search",
+					"service",
+					"ts",
+					"rankresults",
+					"export",
+					"interface",
+					"searchhit",
+					"path",
+					"string",
+					"score",
+					"number",
+					"snippet",
+					"string",
+					"export",
+					"function",
+					"rankresults",
+					"query",
+					"string",
+					"hits",
+					"searchhit",
+					"searchhit",
+					"const",
+					"terms",
+					"query",
+					"tolowercase",
+					"split",
+					"return",
+					"hits",
+					"map",
+					"hit",
+					"hit",
+					"score",
+					"terms",
+					"reduce",
+					"score",
+					"term",
+					"hit",
+					"snippet",
+					"tolowercase",
+					"includes",
+					"term",
+					"score",
+					"score",
+					"hit",
+					"score",
+					"sort",
+					"score",
+					"score"
+				],
+				"symbol_name": "rankResults",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/services/user-service.ts",
+				"start_line": 4,
+				"end_line": 17,
+				"text": "import { validateEmail } from '../api/validation.js'\nimport { UserRepository } from '../db/repository.js'\n\nexport class UserService {\n\tconstructor(private readonly repo = new UserRepository()) {}\n\n\tasync getUser(id: string) {\n\t\treturn this.repo.findById(id)\n\t}\n\n\tasync register(email: string) {\n\t\tif (!validateEmail(email)) throw new Error('invalid email')\n\t\tconst user = { id: crypto.randomUUID(), email }\n\t\tawait this.repo.save(user)\n\t\treturn user\n\t}\n}",
+				"tokens": [
+					"src",
+					"services",
+					"user",
+					"service",
+					"ts",
+					"userservice",
+					"import",
+					"validateemail",
+					"from",
+					"api",
+					"validation",
+					"js",
+					"import",
+					"userrepository",
+					"from",
+					"db",
+					"repository",
+					"js",
+					"export",
+					"class",
+					"userservice",
+					"constructor",
+					"private",
+					"readonly",
+					"repo",
+					"new",
+					"userrepository",
+					"async",
+					"getuser",
+					"id",
+					"string",
+					"return",
+					"this",
+					"repo",
+					"findbyid",
+					"id",
+					"async",
+					"register",
+					"email",
+					"string",
+					"if",
+					"validateemail",
+					"email",
+					"throw",
+					"new",
+					"error",
+					"invalid",
+					"email",
+					"const",
+					"user",
+					"id",
+					"crypto",
+					"randomuuid",
+					"email",
+					"await",
+					"this",
+					"repo",
+					"save",
+					"user",
+					"return",
+					"user"
+				],
+				"symbol_name": "UserService",
+				"chunk_type": "class"
+			},
+			{
+				"path": "src/services/billing-service.ts",
+				"start_line": 1,
+				"end_line": 5,
+				"text": "export function calculateSubscriptionPrice(seats: number, plan: 'starter' | 'pro'): number {\n\tconst base = plan === 'starter' ? 9 : 29\n\treturn base * Math.max(seats, 1)\n}\n",
+				"tokens": [
+					"src",
+					"services",
+					"billing",
+					"service",
+					"ts",
+					"calculatesubscriptionprice",
+					"export",
+					"function",
+					"calculatesubscriptionprice",
+					"seats",
+					"number",
+					"plan",
+					"starter",
+					"pro",
+					"number",
+					"const",
+					"base",
+					"plan",
+					"starter",
+					"29",
+					"return",
+					"base",
+					"math",
+					"max",
+					"seats"
+				],
+				"symbol_name": "calculateSubscriptionPrice",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/services/billing-service.ts",
+				"start_line": 6,
+				"end_line": 9,
+				"text": "export async function chargeCustomer(customerId: string, amountCents: number): Promise<string> {\n\tif (amountCents <= 0) throw new Error('invalid amount')\n\treturn `ch_${customerId}_${amountCents}`\n}",
+				"tokens": [
+					"src",
+					"services",
+					"billing",
+					"service",
+					"ts",
+					"chargecustomer",
+					"export",
+					"async",
+					"function",
+					"chargecustomer",
+					"customerid",
+					"string",
+					"amountcents",
+					"number",
+					"promise",
+					"string",
+					"if",
+					"amountcents",
+					"throw",
+					"new",
+					"error",
+					"invalid",
+					"amount",
+					"return",
+					"ch_",
+					"customerid",
+					"amountcents"
+				],
+				"symbol_name": "chargeCustomer",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/string.ts",
+				"start_line": 1,
+				"end_line": 7,
+				"text": "export function slugify(input: string): string {\n\treturn input\n\t\t.toLowerCase()\n\t\t.replace(/[^a-z0-9]+/g, '-')\n\t\t.replace(/^-|-$/g, '')\n}\n",
+				"tokens": [
+					"src",
+					"utils",
+					"string",
+					"ts",
+					"slugify",
+					"export",
+					"function",
+					"slugify",
+					"input",
+					"string",
+					"string",
+					"return",
+					"input",
+					"tolowercase",
+					"replace",
+					"z0",
+					"replace"
+				],
+				"symbol_name": "slugify",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/string.ts",
+				"start_line": 8,
+				"end_line": 11,
+				"text": "export function truncate(input: string, max: number): string {\n\treturn input.length <= max ? input : `${input.slice(0, max - 3)}...`\n}\n",
+				"tokens": [
+					"src",
+					"utils",
+					"string",
+					"ts",
+					"truncate",
+					"export",
+					"function",
+					"truncate",
+					"input",
+					"string",
+					"max",
+					"number",
+					"string",
+					"return",
+					"input",
+					"length",
+					"max",
+					"input",
+					"input",
+					"slice",
+					"max"
+				],
+				"symbol_name": "truncate",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/string.ts",
+				"start_line": 12,
+				"end_line": 14,
+				"text": "export function camelToSnake(input: string): string {\n\treturn input.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`)\n}",
+				"tokens": [
+					"src",
+					"utils",
+					"string",
+					"ts",
+					"cameltosnake",
+					"export",
+					"function",
+					"cameltosnake",
+					"input",
+					"string",
+					"string",
+					"return",
+					"input",
+					"replace",
+					"tolowercase"
+				],
+				"symbol_name": "camelToSnake",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/hash.ts",
+				"start_line": 1,
+				"end_line": 9,
+				"text": "export function simpleHash(input: string): string {\n\tlet hash = 0\n\tfor (let i = 0; i < input.length; i++) {\n\t\thash = (hash << 5) - hash + input.charCodeAt(i)\n\t\thash |= 0\n\t}\n\treturn Math.abs(hash).toString(16)\n}\n",
+				"tokens": [
+					"src",
+					"utils",
+					"hash",
+					"ts",
+					"simplehash",
+					"export",
+					"function",
+					"simplehash",
+					"input",
+					"string",
+					"string",
+					"let",
+					"hash",
+					"for",
+					"let",
+					"input",
+					"length",
+					"hash",
+					"hash",
+					"hash",
+					"input",
+					"charcodeat",
+					"hash",
+					"return",
+					"math",
+					"abs",
+					"hash",
+					"tostring",
+					"16"
+				],
+				"symbol_name": "simpleHash",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/hash.ts",
+				"start_line": 10,
+				"end_line": 12,
+				"text": "export function stableObjectHash(obj: Record<string, unknown>): string {\n\treturn simpleHash(JSON.stringify(obj, Object.keys(obj).sort()))\n}",
+				"tokens": [
+					"src",
+					"utils",
+					"hash",
+					"ts",
+					"stableobjecthash",
+					"export",
+					"function",
+					"stableobjecthash",
+					"obj",
+					"record",
+					"string",
+					"unknown",
+					"string",
+					"return",
+					"simplehash",
+					"json",
+					"stringify",
+					"obj",
+					"object",
+					"keys",
+					"obj",
+					"sort"
+				],
+				"symbol_name": "stableObjectHash",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/retry.ts",
+				"start_line": 1,
+				"end_line": 12,
+				"text": "export async function retry<T>(fn: () => Promise<T>, attempts = 3, delayMs = 100): Promise<T> {\n\tlet lastError: unknown\n\tfor (let i = 0; i < attempts; i++) {\n\t\ttry {\n\t\t\treturn await fn()\n\t\t} catch (error) {\n\t\t\tlastError = error\n\t\t\tawait new Promise((resolve) => setTimeout(resolve, delayMs * (i + 1)))\n\t\t}\n\t}\n\tthrow lastError\n}",
+				"tokens": [
+					"src",
+					"utils",
+					"retry",
+					"ts",
+					"retry",
+					"export",
+					"async",
+					"function",
+					"retry",
+					"fn",
+					"promise",
+					"attempts",
+					"delayms",
+					"100",
+					"promise",
+					"let",
+					"lasterror",
+					"unknown",
+					"for",
+					"let",
+					"attempts",
+					"try",
+					"return",
+					"await",
+					"fn",
+					"catch",
+					"error",
+					"lasterror",
+					"error",
+					"await",
+					"new",
+					"promise",
+					"resolve",
+					"settimeout",
+					"resolve",
+					"delayms",
+					"throw",
+					"lasterror"
+				],
+				"symbol_name": "retry",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/array.ts",
+				"start_line": 1,
+				"end_line": 4,
+				"text": "export function unique<T>(items: T[]): T[] {\n\treturn [...new Set(items)]\n}\n",
+				"tokens": [
+					"src",
+					"utils",
+					"array",
+					"ts",
+					"unique",
+					"export",
+					"function",
+					"unique",
+					"items",
+					"return",
+					"new",
+					"set",
+					"items"
+				],
+				"symbol_name": "unique",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/array.ts",
+				"start_line": 5,
+				"end_line": 12,
+				"text": "export function chunk<T>(items: T[], size: number): T[][] {\n\tconst chunks: T[][] = []\n\tfor (let i = 0; i < items.length; i += size) {\n\t\tchunks.push(items.slice(i, i + size))\n\t}\n\treturn chunks\n}\n",
+				"tokens": [
+					"src",
+					"utils",
+					"array",
+					"ts",
+					"chunk",
+					"export",
+					"function",
+					"chunk",
+					"items",
+					"size",
+					"number",
+					"const",
+					"chunks",
+					"for",
+					"let",
+					"items",
+					"length",
+					"size",
+					"chunks",
+					"push",
+					"items",
+					"slice",
+					"size",
+					"return",
+					"chunks"
+				],
+				"symbol_name": "chunk",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/array.ts",
+				"start_line": 13,
+				"end_line": 20,
+				"text": "export function groupBy<T>(items: T[], keyFn: (item: T) => string): Record<string, T[]> {\n\treturn items.reduce<Record<string, T[]>>((acc, item) => {\n\t\tconst key = keyFn(item)\n\t\tacc[key] ??= []\n\t\tacc[key].push(item)\n\t\treturn acc\n\t}, {})\n}",
+				"tokens": [
+					"src",
+					"utils",
+					"array",
+					"ts",
+					"groupby",
+					"export",
+					"function",
+					"groupby",
+					"items",
+					"keyfn",
+					"item",
+					"string",
+					"record",
+					"string",
+					"return",
+					"items",
+					"reduce",
+					"record",
+					"string",
+					"acc",
+					"item",
+					"const",
+					"key",
+					"keyfn",
+					"item",
+					"acc",
+					"key",
+					"acc",
+					"key",
+					"push",
+					"item",
+					"return",
+					"acc"
+				],
+				"symbol_name": "groupBy",
+				"chunk_type": "function"
+			},
+			{
+				"path": "src/utils/cache.ts",
+				"start_line": 1,
+				"end_line": 22,
+				"text": "export class LRUCache<K, V> {\n\tprivate map = new Map<K, V>()\n\n\tconstructor(private readonly maxSize: number) {}\n\n\tget(key: K): V | undefined {\n\t\tconst value = this.map.get(key)\n\t\tif (value === undefined) return undefined\n\t\tthis.map.delete(key)\n\t\tthis.map.set(key, value)\n\t\treturn value\n\t}\n\n\tset(key: K, value: V): void {\n\t\tif (this.map.has(key)) this.map.delete(key)\n\t\tthis.map.set(key, value)\n\t\tif (this.map.size > this.maxSize) {\n\t\t\tconst oldest = this.map.keys().next().value\n\t\t\tif (oldest !== undefined) this.map.delete(oldest)\n\t\t}\n\t}\n}",
+				"tokens": [
+					"src",
+					"utils",
+					"cache",
+					"ts",
+					"lrucache",
+					"export",
+					"class",
+					"lrucache",
+					"private",
+					"map",
+					"new",
+					"map",
+					"constructor",
+					"private",
+					"readonly",
+					"maxsize",
+					"number",
+					"get",
+					"key",
+					"undefined",
+					"const",
+					"value",
+					"this",
+					"map",
+					"get",
+					"key",
+					"if",
+					"value",
+					"undefined",
+					"return",
+					"undefined",
+					"this",
+					"map",
+					"delete",
+					"key",
+					"this",
+					"map",
+					"set",
+					"key",
+					"value",
+					"return",
+					"value",
+					"set",
+					"key",
+					"value",
+					"void",
+					"if",
+					"this",
+					"map",
+					"has",
+					"key",
+					"this",
+					"map",
+					"delete",
+					"key",
+					"this",
+					"map",
+					"set",
+					"key",
+					"value",
+					"if",
+					"this",
+					"map",
+					"size",
+					"this",
+					"maxsize",
+					"const",
+					"oldest",
+					"this",
+					"map",
+					"keys",
+					"next",
+					"value",
+					"if",
+					"oldest",
+					"undefined",
+					"this",
+					"map",
+					"delete",
+					"oldest"
+				],
+				"symbol_name": "LRUCache",
+				"chunk_type": "class"
+			},
+			{
+				"path": "src/index.ts",
+				"start_line": 1,
+				"end_line": 5,
+				"text": "export { Router } from './api/router.js'\nexport { authenticate } from './auth/login.js'\nexport { createSession } from './auth/session.js'\nexport { DatabaseConnection } from './db/connection.js'\nexport { UserService } from './services/user-service.js'\n",
+				"tokens": [
+					"src",
+					"index",
+					"ts",
+					"export",
+					"router",
+					"from",
+					"api",
+					"router",
+					"js",
+					"export",
+					"authenticate",
+					"from",
+					"auth",
+					"login",
+					"js",
+					"export",
+					"createsession",
+					"from",
+					"auth",
+					"session",
+					"js",
+					"export",
+					"databaseconnection",
+					"from",
+					"db",
+					"connection",
+					"js",
+					"export",
+					"userservice",
+					"from",
+					"services",
+					"user",
+					"service",
+					"js"
+				],
+				"chunk_type": "file"
+			}
+		],
+		"doc_freq": {
+			"repo": 2,
+			"post": 3,
+			"return": 47,
+			"ts": 56,
+			"connect": 2,
+			"replace": 2,
+			"checkratelimit": 1,
+			"retry": 1,
+			"drop": 1,
+			"sql": 1,
+			"unknown": 4,
+			"score": 1,
+			"res": 1,
+			"admin": 2,
+			"export": 52,
+			"chargecustomer": 1,
+			"startswith": 1,
+			"write": 2,
+			"haspermission": 2,
+			"60_000": 1,
+			"groupby": 1,
+			"function": 48,
+			"br": 1,
+			"204": 1,
+			"encoding": 1,
+			"rankresults": 1,
+			"10": 1,
+			"content": 1,
+			"client_id": 1,
+			"handlehealthcheck": 1,
+			"rate": 1,
+			"shouldcompress": 1,
+			"billing": 2,
+			"seats": 1,
+			"searchhit": 1,
+			"searchparams": 2,
+			"repository": 2,
+			"headersinit": 1,
+			"slugify": 1,
+			"docs": 1,
+			"term": 1,
+			"json": 8,
+			"origin": 1,
+			"index": 1,
+			"edit": 1,
+			"join": 1,
+			"charcodeat": 1,
+			"sub": 2,
+			"token": 4,
+			"true": 3,
+			"authmiddleware": 1,
+			"offset": 1,
+			"withtiming": 1,
+			"starter": 1,
+			"sig": 1,
+			"maxsize": 1,
+			"gzip": 1,
+			"methods": 1,
+			"math": 3,
+			"input": 4,
+			"corsheaders": 2,
+			"terms": 1,
+			"authenticate": 2,
+			"userrepository": 2,
+			"calculatesubscriptionprice": 1,
+			"running": 1,
+			"re": 1,
+			"false": 2,
+			"oldest": 1,
+			"iat": 1,
+			"record": 4,
+			"implements": 1,
+			"extends": 1,
+			"ttlms": 1,
+			"delete": 5,
+			"put": 1,
+			"sendwelcomeemail": 1,
+			"pathname": 2,
+			"role_permissions": 2,
+			"db": 10,
+			"handlers": 3,
+			"viewer": 2,
+			"fetch": 1,
+			"001_users": 1,
+			"payload": 2,
+			"attempts": 1,
+			"import": 4,
+			"response": 9,
+			"logging": 3,
+			"in": 1,
+			"interface": 7,
+			"201": 1,
+			"down": 1,
+			"resetat": 1,
+			"simplehash": 2,
+			"async": 22,
+			"instanceof": 1,
+			"result": 2,
+			"secret": 3,
+			"customerid": 1,
+			"now": 5,
+			"amountcents": 1,
+			"withtransaction": 1,
+			"exchangeoauthcode": 1,
+			"limit": 3,
+			"validateemail": 2,
+			"session": 3,
+			"private": 5,
+			"ran": 1,
+			"decoded": 1,
+			"com": 1,
+			"request": 7,
+			"durationms": 2,
+			"ms": 1,
+			"findbyid": 2,
+			"error": 11,
+			"split": 2,
+			"20": 1,
+			"await": 9,
+			"has": 2,
+			"userid": 6,
+			"search": 1,
+			"void": 12,
+			"the": 1,
+			"textencoder": 1,
+			"undefined": 1,
+			"up": 1,
+			"accept": 1,
+			"hit": 1,
+			"userservice": 2,
+			"tolowercase": 3,
+			"internal_error": 1,
+			"unique": 1,
+			"sendnotification": 2,
+			"date": 4,
+			"encode": 1,
+			"stringify": 3,
+			"array": 3,
+			"ok": 1,
+			"router": 2,
+			"set": 5,
+			"services": 7,
+			"max": 2,
+			"user": 5,
+			"users": 2,
+			"validatepasswordstrength": 1,
+			"release": 1,
+			"length": 5,
+			"unauthorized": 1,
+			"then": 1,
+			"postgres": 1,
+			"req": 7,
+			"size": 3,
+			"handler": 2,
+			"url": 3,
+			"from": 7,
+			"manage_users": 2,
+			"notification": 2,
+			"sms": 2,
+			"chunk": 1,
+			"tostring": 3,
+			"push": 6,
+			"params": 2,
+			"items": 3,
+			"email": 6,
+			"new": 16,
+			"transaction": 4,
+			"do": 1,
+			"body": 3,
+			"redirecturi": 1,
+			"authorization": 2,
+			"acc": 1,
+			"base": 1,
+			"buckets": 1,
+			"compression": 2,
+			"oauth": 2,
+			"role": 2,
+			"invalid": 3,
+			"crypto": 2,
+			"files": 1,
+			"base64url": 2,
+			"status": 8,
+			"item": 1,
+			"z0": 1,
+			"map": 4,
+			"key": 5,
+			"boolean": 9,
+			"validatepassword": 2,
+			"connectionstring": 1,
+			"includes": 3,
+			"snippet": 1,
+			"hits": 1,
+			"connections": 1,
+			"localhost": 1,
+			"parse": 1,
+			"readonly": 4,
+			"migrations": 1,
+			"without": 1,
+			"amount": 1,
+			"control": 1,
+			"console": 3,
+			"runmigrations": 1,
+			"stableobjecthash": 1,
+			"gettime": 1,
+			"obj": 1,
+			"cache": 1,
+			"sessions": 1,
+			"handleuserlist": 1,
+			"fixture": 1,
+			"src": 56,
+			"create": 1,
+			"handlecreateuser": 1,
+			"apierror": 2,
+			"proof": 1,
+			"bucket": 1,
+			"handle": 1,
+			"editor": 2,
+			"null": 3,
+			"constructor": 4,
+			"randomuuid": 2,
+			"example": 3,
+			"bun": 1,
+			"js": 5,
+			"buildauthorizationurl": 1,
+			"handlepreflight": 1,
+			"object": 1,
+			"created": 1,
+			"test": 2,
+			"passwordhash": 2,
+			"reduce": 2,
+			"86_400_000": 1,
+			"keys": 2,
+			"routes": 1,
+			"pool": 1,
+			"begintransaction": 2,
+			"resolve": 1,
+			"getuser": 1,
+			"service": 7,
+			"options": 2,
+			"parsepagination": 1,
+			"toerrorresponse": 2,
+			"path": 2,
+			"save": 2,
+			"002_sessions": 1,
+			"windowms": 1,
+			"logresponse": 1,
+			"uint8array": 1,
+			"name": 1,
+			"headers": 4,
+			"permission": 1,
+			"scope": 1,
+			"signaccesstoken": 1,
+			"min": 1,
+			"text": 1,
+			"urlsearchparams": 2,
+			"utils": 10,
+			"truncate": 1,
+			"29": 1,
+			"disconnect": 2,
+			"validation": 4,
+			"canmanageusers": 1,
+			"100": 3,
+			"benchmark": 1,
+			"bearer": 1,
+			"compressbody": 1,
+			"pro": 1,
+			"table": 1,
+			"query": 2,
+			"if": 11,
+			"code": 3,
+			"next": 1,
+			"class": 7,
+			"message": 4,
+			"welcome": 1,
+			"updating": 1,
+			"createsession": 2,
+			"of": 1,
+			"login": 5,
+			"permissions": 2,
+			"catch": 3,
+			"finduserbyemail": 2,
+			"lrucache": 1,
+			"type": 4,
+			"issessionvalid": 1,
+			"acquire": 1,
+			"databaseconnection": 3,
+			"logrequest": 1,
+			"sort": 2,
+			"start": 1,
+			"fixed": 1,
+			"header": 1,
+			"connectionpool": 1,
+			"as": 2,
+			"readme": 1,
+			"read": 2,
+			"here": 1,
+			"errorhandler": 1,
+			"activecount": 1,
+			"auth": 14,
+			"abs": 1,
+			"super": 1,
+			"16": 1,
+			"this": 6,
+			"rollbacktransaction": 2,
+			"verifyaccesstoken": 2,
+			"promise": 20,
+			"committransaction": 2,
+			"corpus": 1,
+			"let": 3,
+			"notify": 1,
+			"throw": 5,
+			"username": 1,
+			"and": 1,
+			"hashpassword": 2,
+			"register": 1,
+			"get": 9,
+			"value": 1,
+			"ch_": 1,
+			"password": 4,
+			"md": 1,
+			"expiresat": 2,
+			"cors": 2,
+			"buffer": 2,
+			"connection": 3,
+			"run": 1,
+			"id": 6,
+			"found": 1,
+			"401": 1,
+			"count": 1,
+			"authorize": 1,
+			"public": 1,
+			"string": 33,
+			"performance": 1,
+			"const": 24,
+			"chunks": 1,
+			"app": 1,
+			"channel": 2,
+			"hash": 3,
+			"required": 1,
+			"https": 2,
+			"keyfn": 1,
+			"primary": 1,
+			"allow": 1,
+			"not": 3,
+			"hashed": 1,
+			"slice": 3,
+			"utf8": 1,
+			"migration": 1,
+			"typescript": 1,
+			"for": 5,
+			"method": 4,
+			"500": 1,
+			"connected": 1,
+			"404": 1,
+			"middleware": 9,
+			"conn": 1,
+			"number": 13,
+			"access": 1,
+			"delayms": 1,
+			"fn": 4,
+			"applied": 1,
+			"plan": 1,
+			"lasterror": 1,
+			"errors": 3,
+			"clientid": 1,
+			"settimeout": 1,
+			"api": 13,
+			"try": 3,
+			"cameltosnake": 1,
+			"entity": 1
+		},
+		"avg_doc_len": 31.649122807017545
+	}
+}
diff --git a/fixtures/benchmark-corpus/README.md b/fixtures/benchmark-corpus/README.md
new file mode 100644
index 0000000..5d48252
--- /dev/null
+++ b/fixtures/benchmark-corpus/README.md
@@ -0,0 +1,5 @@
+# Benchmark Corpus
+
+Fixed in-repo TypeScript fixture corpus for `bun run benchmark:public-proof`.
+
+Do not edit files here without re-running the benchmark and updating `docs/benchmark.md`.
\ No newline at end of file
diff --git a/fixtures/benchmark-corpus/src/api/errors.ts b/fixtures/benchmark-corpus/src/api/errors.ts
new file mode 100644
index 0000000..5d272e9
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/api/errors.ts
@@ -0,0 +1,17 @@
+export class ApiError extends Error {
+	constructor(
+		message: string,
+		readonly status: number,
+		readonly code: string
+	) {
+		super(message)
+		this.name = 'ApiError'
+	}
+}
+
+export function toErrorResponse(error: unknown): Response {
+	if (error instanceof ApiError) {
+		return Response.json({ error: error.code, message: error.message }, { status: error.status })
+	}
+	return Response.json({ error: 'internal_error' }, { status: 500 })
+}
diff --git a/fixtures/benchmark-corpus/src/api/handlers.ts b/fixtures/benchmark-corpus/src/api/handlers.ts
new file mode 100644
index 0000000..46a4cdd
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/api/handlers.ts
@@ -0,0 +1,14 @@
+export async function handleHealthCheck(): Promise<Response> {
+	return Response.json({ status: 'ok' })
+}
+
+export async function handleUserList(req: Request): Promise<Response> {
+	const url = new URL(req.url)
+	const limit = Number(url.searchParams.get('limit') ?? 10)
+	return Response.json({ users: [], limit })
+}
+
+export async function handleCreateUser(req: Request): Promise<Response> {
+	const body = await req.json()
+	return Response.json({ created: true, user: body }, { status: 201 })
+}
diff --git a/fixtures/benchmark-corpus/src/api/rate-limit.ts b/fixtures/benchmark-corpus/src/api/rate-limit.ts
new file mode 100644
index 0000000..5b51e75
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/api/rate-limit.ts
@@ -0,0 +1,13 @@
+const buckets = new Map<string, { count: number; resetAt: number }>()
+
+export function checkRateLimit(key: string, limit = 100, windowMs = 60_000): boolean {
+	const now = Date.now()
+	const bucket = buckets.get(key)
+	if (!bucket || bucket.resetAt < now) {
+		buckets.set(key, { count: 1, resetAt: now + windowMs })
+		return true
+	}
+	if (bucket.count >= limit) return false
+	bucket.count += 1
+	return true
+}
diff --git a/fixtures/benchmark-corpus/src/api/router.ts b/fixtures/benchmark-corpus/src/api/router.ts
new file mode 100644
index 0000000..1edfb9a
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/api/router.ts
@@ -0,0 +1,20 @@
+export type Handler = (req: Request) => Promise<Response>
+
+export class Router {
+	private routes = new Map<string, Handler>()
+
+	get(path: string, handler: Handler): void {
+		this.routes.set(`GET:${path}`, handler)
+	}
+
+	post(path: string, handler: Handler): void {
+		this.routes.set(`POST:${path}`, handler)
+	}
+
+	async handle(req: Request): Promise<Response> {
+		const key = `${req.method}:${new URL(req.url).pathname}`
+		const handler = this.routes.get(key)
+		if (!handler) return new Response('not found', { status: 404 })
+		return handler(req)
+	}
+}
diff --git a/fixtures/benchmark-corpus/src/api/validation.ts b/fixtures/benchmark-corpus/src/api/validation.ts
new file mode 100644
index 0000000..b09bd95
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/api/validation.ts
@@ -0,0 +1,14 @@
+export function validateEmail(email: string): boolean {
+	return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)
+}
+
+export function validatePasswordStrength(password: string): boolean {
+	return password.length >= 8 && /[A-Z]/.test(password) && /[0-9]/.test(password)
+}
+
+export function parsePagination(searchParams: URLSearchParams) {
+	return {
+		limit: Math.min(Number(searchParams.get('limit') ?? 20), 100),
+		offset: Number(searchParams.get('offset') ?? 0),
+	}
+}
diff --git a/fixtures/benchmark-corpus/src/auth/login.ts b/fixtures/benchmark-corpus/src/auth/login.ts
new file mode 100644
index 0000000..66126eb
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/auth/login.ts
@@ -0,0 +1,16 @@
+export async function authenticate(username: string, password: string): Promise<boolean> {
+	const user = await findUserByEmail(username)
+	return validatePassword(user, password)
+}
+
+export async function findUserByEmail(email: string) {
+	return { id: '1', email, passwordHash: 'hash' }
+}
+
+export function validatePassword(user: { passwordHash: string }, password: string): boolean {
+	return user.passwordHash === hashPassword(password)
+}
+
+function hashPassword(password: string): string {
+	return `hashed:${password}`
+}
diff --git a/fixtures/benchmark-corpus/src/auth/oauth.ts b/fixtures/benchmark-corpus/src/auth/oauth.ts
new file mode 100644
index 0000000..8e23fb0
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/auth/oauth.ts
@@ -0,0 +1,12 @@
+export async function exchangeOAuthCode(code: string, redirectUri: string) {
+	const response = await fetch('https://oauth.example/token', {
+		method: 'POST',
+		body: JSON.stringify({ code, redirectUri }),
+	})
+	return response.json()
+}
+
+export function buildAuthorizationUrl(clientId: string, scope: string[]): string {
+	const params = new URLSearchParams({ client_id: clientId, scope: scope.join(' ') })
+	return `https://oauth.example/authorize?${params}`
+}
diff --git a/fixtures/benchmark-corpus/src/auth/permissions.ts b/fixtures/benchmark-corpus/src/auth/permissions.ts
new file mode 100644
index 0000000..b7152e7
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/auth/permissions.ts
@@ -0,0 +1,15 @@
+export type Role = 'admin' | 'editor' | 'viewer'
+
+const ROLE_PERMISSIONS: Record<Role, string[]> = {
+	admin: ['read', 'write', 'delete', 'manage_users'],
+	editor: ['read', 'write'],
+	viewer: ['read'],
+}
+
+export function hasPermission(role: Role, permission: string): boolean {
+	return ROLE_PERMISSIONS[role].includes(permission)
+}
+
+export function canManageUsers(role: Role): boolean {
+	return hasPermission(role, 'manage_users')
+}
diff --git a/fixtures/benchmark-corpus/src/auth/session.ts b/fixtures/benchmark-corpus/src/auth/session.ts
new file mode 100644
index 0000000..471745d
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/auth/session.ts
@@ -0,0 +1,17 @@
+export interface Session {
+	id: string
+	userId: string
+	expiresAt: Date
+}
+
+export function createSession(userId: string, ttlMs = 86_400_000): Session {
+	return {
+		id: crypto.randomUUID(),
+		userId,
+		expiresAt: new Date(Date.now() + ttlMs),
+	}
+}
+
+export function isSessionValid(session: Session): boolean {
+	return session.expiresAt.getTime() > Date.now()
+}
diff --git a/fixtures/benchmark-corpus/src/auth/token.ts b/fixtures/benchmark-corpus/src/auth/token.ts
new file mode 100644
index 0000000..f46b007
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/auth/token.ts
@@ -0,0 +1,11 @@
+export function signAccessToken(userId: string, secret: string): string {
+	const payload = JSON.stringify({ sub: userId, iat: Date.now() })
+	return Buffer.from(`${payload}.${secret}`).toString('base64url')
+}
+
+export function verifyAccessToken(token: string, secret: string): string | null {
+	const decoded = Buffer.from(token, 'base64url').toString('utf8')
+	const [payload, sig] = decoded.split('.')
+	if (sig !== secret) return null
+	return JSON.parse(payload).sub as string
+}
diff --git a/fixtures/benchmark-corpus/src/db/connection.ts b/fixtures/benchmark-corpus/src/db/connection.ts
new file mode 100644
index 0000000..67477a1
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/db/connection.ts
@@ -0,0 +1,17 @@
+export class DatabaseConnection {
+	private connected = false
+
+	async connect(connectionString: string): Promise<void> {
+		if (!connectionString) throw new Error('connection string required')
+		this.connected = true
+	}
+
+	async query<T>(sql: string, params: unknown[] = []): Promise<T[]> {
+		if (!this.connected) throw new Error('not connected')
+		return [] as T[]
+	}
+
+	async disconnect(): Promise<void> {
+		this.connected = false
+	}
+}
diff --git a/fixtures/benchmark-corpus/src/db/migrations.ts b/fixtures/benchmark-corpus/src/db/migrations.ts
new file mode 100644
index 0000000..6f5c5f0
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/db/migrations.ts
@@ -0,0 +1,24 @@
+export interface Migration {
+	id: string
+	up: string
+	down: string
+}
+
+export const migrations: Migration[] = [
+	{ id: '001_users', up: 'CREATE TABLE users (id TEXT PRIMARY KEY)', down: 'DROP TABLE users' },
+	{
+		id: '002_sessions',
+		up: 'CREATE TABLE sessions (id TEXT PRIMARY KEY)',
+		down: 'DROP TABLE sessions',
+	},
+]
+
+export async function runMigrations(applied: Set<string>): Promise<string[]> {
+	const ran: string[] = []
+	for (const migration of migrations) {
+		if (!applied.has(migration.id)) {
+			ran.push(migration.id)
+		}
+	}
+	return ran
+}
diff --git a/fixtures/benchmark-corpus/src/db/pool.ts b/fixtures/benchmark-corpus/src/db/pool.ts
new file mode 100644
index 0000000..aff449e
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/db/pool.ts
@@ -0,0 +1,22 @@
+import { DatabaseConnection } from './connection.js'
+
+export class ConnectionPool {
+	private readonly connections: DatabaseConnection[] = []
+
+	constructor(private readonly size: number) {}
+
+	async acquire(): Promise<DatabaseConnection> {
+		const conn = new DatabaseConnection()
+		await conn.connect('postgres://localhost/app')
+		this.connections.push(conn)
+		return conn
+	}
+
+	async release(conn: DatabaseConnection): Promise<void> {
+		await conn.disconnect()
+	}
+
+	get activeCount(): number {
+		return this.connections.length
+	}
+}
diff --git a/fixtures/benchmark-corpus/src/db/repository.ts b/fixtures/benchmark-corpus/src/db/repository.ts
new file mode 100644
index 0000000..9a60e82
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/db/repository.ts
@@ -0,0 +1,19 @@
+export interface Repository<T> {
+	findById(id: string): Promise<T | null>
+	save(entity: T): Promise<void>
+	delete(id: string): Promise<void>
+}
+
+export class UserRepository implements Repository<{ id: string; email: string }> {
+	async findById(id: string) {
+		return { id, email: `${id}@example.com` }
+	}
+
+	async save(entity: { id: string; email: string }): Promise<void> {
+		void entity
+	}
+
+	async delete(id: string): Promise<void> {
+		void id
+	}
+}
diff --git a/fixtures/benchmark-corpus/src/db/transaction.ts b/fixtures/benchmark-corpus/src/db/transaction.ts
new file mode 100644
index 0000000..9ded333
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/db/transaction.ts
@@ -0,0 +1,15 @@
+export async function withTransaction<T>(fn: () => Promise<T>): Promise<T> {
+	await beginTransaction()
+	try {
+		const result = await fn()
+		await commitTransaction()
+		return result
+	} catch (error) {
+		await rollbackTransaction()
+		throw error
+	}
+}
+
+async function beginTransaction(): Promise<void> {}
+async function commitTransaction(): Promise<void> {}
+async function rollbackTransaction(): Promise<void> {}
diff --git a/fixtures/benchmark-corpus/src/index.ts b/fixtures/benchmark-corpus/src/index.ts
new file mode 100644
index 0000000..353cfa5
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/index.ts
@@ -0,0 +1,5 @@
+export { Router } from './api/router.js'
+export { authenticate } from './auth/login.js'
+export { createSession } from './auth/session.js'
+export { DatabaseConnection } from './db/connection.js'
+export { UserService } from './services/user-service.js'
diff --git a/fixtures/benchmark-corpus/src/middleware/auth.ts b/fixtures/benchmark-corpus/src/middleware/auth.ts
new file mode 100644
index 0000000..2dec72d
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/middleware/auth.ts
@@ -0,0 +1,11 @@
+import { verifyAccessToken } from '../auth/token.js'
+
+export async function authMiddleware(req: Request, secret: string): Promise<Request | Response> {
+	const header = req.headers.get('authorization')
+	if (!header?.startsWith('Bearer ')) {
+		return new Response('unauthorized', { status: 401 })
+	}
+	const userId = verifyAccessToken(header.slice(7), secret)
+	if (!userId) return new Response('invalid token', { status: 401 })
+	return req
+}
diff --git a/fixtures/benchmark-corpus/src/middleware/compression.ts b/fixtures/benchmark-corpus/src/middleware/compression.ts
new file mode 100644
index 0000000..894eda5
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/middleware/compression.ts
@@ -0,0 +1,8 @@
+export function shouldCompress(req: Request): boolean {
+	const accept = req.headers.get('accept-encoding') ?? ''
+	return accept.includes('gzip') || accept.includes('br')
+}
+
+export function compressBody(body: string): Uint8Array {
+	return new TextEncoder().encode(body)
+}
diff --git a/fixtures/benchmark-corpus/src/middleware/cors.ts b/fixtures/benchmark-corpus/src/middleware/cors.ts
new file mode 100644
index 0000000..4b1d77b
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/middleware/cors.ts
@@ -0,0 +1,12 @@
+export function corsHeaders(origin = '*'): HeadersInit {
+	return {
+		'Access-Control-Allow-Origin': origin,
+		'Access-Control-Allow-Methods': 'GET,POST,PUT,DELETE,OPTIONS',
+		'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+	}
+}
+
+export function handlePreflight(req: Request): Response | null {
+	if (req.method !== 'OPTIONS') return null
+	return new Response(null, { status: 204, headers: corsHeaders() })
+}
diff --git a/fixtures/benchmark-corpus/src/middleware/error-handler.ts b/fixtures/benchmark-corpus/src/middleware/error-handler.ts
new file mode 100644
index 0000000..a431e1c
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/middleware/error-handler.ts
@@ -0,0 +1,9 @@
+import { toErrorResponse } from '../api/errors.js'
+
+export async function errorHandler(fn: () => Promise<Response>): Promise<Response> {
+	try {
+		return await fn()
+	} catch (error) {
+		return toErrorResponse(error)
+	}
+}
diff --git a/fixtures/benchmark-corpus/src/middleware/logging.ts b/fixtures/benchmark-corpus/src/middleware/logging.ts
new file mode 100644
index 0000000..e3c9044
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/middleware/logging.ts
@@ -0,0 +1,13 @@
+export function logRequest(req: Request): void {
+	const url = new URL(req.url)
+	console.error(`[req] ${req.method} ${url.pathname}`)
+}
+
+export function logResponse(status: number, durationMs: number): void {
+	console.error(`[res] ${status} ${durationMs}ms`)
+}
+
+export function withTiming<T>(fn: () => Promise<T>): Promise<{ result: T; durationMs: number }> {
+	const start = performance.now()
+	return fn().then((result) => ({ result, durationMs: performance.now() - start }))
+}
diff --git a/fixtures/benchmark-corpus/src/services/billing-service.ts b/fixtures/benchmark-corpus/src/services/billing-service.ts
new file mode 100644
index 0000000..a662ef4
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/services/billing-service.ts
@@ -0,0 +1,9 @@
+export function calculateSubscriptionPrice(seats: number, plan: 'starter' | 'pro'): number {
+	const base = plan === 'starter' ? 9 : 29
+	return base * Math.max(seats, 1)
+}
+
+export async function chargeCustomer(customerId: string, amountCents: number): Promise<string> {
+	if (amountCents <= 0) throw new Error('invalid amount')
+	return `ch_${customerId}_${amountCents}`
+}
diff --git a/fixtures/benchmark-corpus/src/services/notification-service.ts b/fixtures/benchmark-corpus/src/services/notification-service.ts
new file mode 100644
index 0000000..d10bc99
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/services/notification-service.ts
@@ -0,0 +1,13 @@
+export interface Notification {
+	userId: string
+	channel: 'email' | 'sms' | 'push'
+	message: string
+}
+
+export async function sendNotification(notification: Notification): Promise<void> {
+	console.error(`notify:${notification.channel} -> ${notification.userId}`)
+}
+
+export async function sendWelcomeEmail(userId: string, email: string): Promise<void> {
+	await sendNotification({ userId, channel: 'email', message: `Welcome ${email}` })
+}
diff --git a/fixtures/benchmark-corpus/src/services/search-service.ts b/fixtures/benchmark-corpus/src/services/search-service.ts
new file mode 100644
index 0000000..40aa632
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/services/search-service.ts
@@ -0,0 +1,18 @@
+export interface SearchHit {
+	path: string
+	score: number
+	snippet: string
+}
+
+export function rankResults(query: string, hits: SearchHit[]): SearchHit[] {
+	const terms = query.toLowerCase().split(/\s+/)
+	return hits
+		.map((hit) => ({
+			...hit,
+			score: terms.reduce(
+				(score, term) => (hit.snippet.toLowerCase().includes(term) ? score + 1 : score),
+				hit.score
+			),
+		}))
+		.sort((a, b) => b.score - a.score)
+}
diff --git a/fixtures/benchmark-corpus/src/services/user-service.ts b/fixtures/benchmark-corpus/src/services/user-service.ts
new file mode 100644
index 0000000..ead9d2f
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/services/user-service.ts
@@ -0,0 +1,17 @@
+import { validateEmail } from '../api/validation.js'
+import { UserRepository } from '../db/repository.js'
+
+export class UserService {
+	constructor(private readonly repo = new UserRepository()) {}
+
+	async getUser(id: string) {
+		return this.repo.findById(id)
+	}
+
+	async register(email: string) {
+		if (!validateEmail(email)) throw new Error('invalid email')
+		const user = { id: crypto.randomUUID(), email }
+		await this.repo.save(user)
+		return user
+	}
+}
diff --git a/fixtures/benchmark-corpus/src/utils/array.ts b/fixtures/benchmark-corpus/src/utils/array.ts
new file mode 100644
index 0000000..79fab11
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/utils/array.ts
@@ -0,0 +1,20 @@
+export function unique<T>(items: T[]): T[] {
+	return [...new Set(items)]
+}
+
+export function chunk<T>(items: T[], size: number): T[][] {
+	const chunks: T[][] = []
+	for (let i = 0; i < items.length; i += size) {
+		chunks.push(items.slice(i, i + size))
+	}
+	return chunks
+}
+
+export function groupBy<T>(items: T[], keyFn: (item: T) => string): Record<string, T[]> {
+	return items.reduce<Record<string, T[]>>((acc, item) => {
+		const key = keyFn(item)
+		acc[key] ??= []
+		acc[key].push(item)
+		return acc
+	}, {})
+}
diff --git a/fixtures/benchmark-corpus/src/utils/cache.ts b/fixtures/benchmark-corpus/src/utils/cache.ts
new file mode 100644
index 0000000..eb9d441
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/utils/cache.ts
@@ -0,0 +1,22 @@
+export class LRUCache<K, V> {
+	private map = new Map<K, V>()
+
+	constructor(private readonly maxSize: number) {}
+
+	get(key: K): V | undefined {
+		const value = this.map.get(key)
+		if (value === undefined) return undefined
+		this.map.delete(key)
+		this.map.set(key, value)
+		return value
+	}
+
+	set(key: K, value: V): void {
+		if (this.map.has(key)) this.map.delete(key)
+		this.map.set(key, value)
+		if (this.map.size > this.maxSize) {
+			const oldest = this.map.keys().next().value
+			if (oldest !== undefined) this.map.delete(oldest)
+		}
+	}
+}
diff --git a/fixtures/benchmark-corpus/src/utils/hash.ts b/fixtures/benchmark-corpus/src/utils/hash.ts
new file mode 100644
index 0000000..17861a8
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/utils/hash.ts
@@ -0,0 +1,12 @@
+export function simpleHash(input: string): string {
+	let hash = 0
+	for (let i = 0; i < input.length; i++) {
+		hash = (hash << 5) - hash + input.charCodeAt(i)
+		hash |= 0
+	}
+	return Math.abs(hash).toString(16)
+}
+
+export function stableObjectHash(obj: Record<string, unknown>): string {
+	return simpleHash(JSON.stringify(obj, Object.keys(obj).sort()))
+}
diff --git a/fixtures/benchmark-corpus/src/utils/retry.ts b/fixtures/benchmark-corpus/src/utils/retry.ts
new file mode 100644
index 0000000..0f984a4
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/utils/retry.ts
@@ -0,0 +1,12 @@
+export async function retry<T>(fn: () => Promise<T>, attempts = 3, delayMs = 100): Promise<T> {
+	let lastError: unknown
+	for (let i = 0; i < attempts; i++) {
+		try {
+			return await fn()
+		} catch (error) {
+			lastError = error
+			await new Promise((resolve) => setTimeout(resolve, delayMs * (i + 1)))
+		}
+	}
+	throw lastError
+}
diff --git a/fixtures/benchmark-corpus/src/utils/string.ts b/fixtures/benchmark-corpus/src/utils/string.ts
new file mode 100644
index 0000000..cb4ed56
--- /dev/null
+++ b/fixtures/benchmark-corpus/src/utils/string.ts
@@ -0,0 +1,14 @@
+export function slugify(input: string): string {
+	return input
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-|-$/g, '')
+}
+
+export function truncate(input: string, max: number): string {
+	return input.length <= max ? input : `${input.slice(0, max - 3)}...`
+}
+
+export function camelToSnake(input: string): string {
+	return input.replace(/[A-Z]/g, (m) => `_${m.toLowerCase()}`)
+}
diff --git a/package.json b/package.json
index 63bef7e..6f52d22 100644
--- a/package.json
+++ b/package.json
@@ -6,6 +6,9 @@
 	"workspaces": [
 		"packages/*"
 	],
+	"bin": {
+		"coderag-mcp": "./bin/coderag-mcp"
+	},
 	"scripts": {
 		"build": "turbo run build",
 		"dev": "turbo run dev",
@@ -17,8 +20,15 @@
 		"format": "biome format --write .",
 		"format:check": "biome format .",
 		"docs:dev": "cd docs && bun run docs:dev",
+		"build:rust": "cargo build --release -p coderag-core -p coderag-cli -p coderag-mcp-server && bun scripts/stage-rust-mcp.ts",
+		"test:rust": "cargo test",
+		"test:golden-retrieval": "bun run build:rust && bun test test/golden-retrieval.test.ts",
+		"test:public-surface": "bun test test/readmeDiscovery.test.ts",
 		"docs:build": "cd docs && bun run docs:build",
 		"docs:preview": "cd docs && bun run docs:preview",
+		"benchmark:public-proof": "bun run scripts/benchmark-public-proof.ts",
+		"doctor": "bun run packages/mcp-server/src/doctor.ts",
+		"benchmark:release-gate": "bun run build:rust && bun run scripts/release-gate.ts",
 		"changeset": "changeset",
 		"version": "changeset version",
 		"release": "echo \"Direct changeset publish is unsafe for workspace packages; use the Sylphx release workflow.\" && exit 1",
@@ -29,7 +39,7 @@
 		"@sylphx/biome-config": "^0.4.0",
 		"lefthook": "^2.0.4",
 		"turbo": "^2.6.1",
-		"typescript": "^5.9.3",
+		"typescript": "^7.0.2",
 		"vitepress": "^1.6.4",
 		"vue": "^3.5.25"
 	},
diff --git a/packages/core/README.md b/packages/core/README.md
index f83da53..31bb44a 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -136,12 +136,15 @@ interface SearchOptions {
 
 ## Performance
 
-| Metric | Value |
-|--------|-------|
-| Indexing speed | ~1000-2000 files/sec |
-| Startup with cache | <100ms |
-| Search latency | <50ms |
-| Memory per 1000 files | ~1-2 MB |
+Reproducible numbers live in the monorepo root — do not trust hand-waved latency claims.
+
+```bash
+# From github.com/SylphxAI/coderag
+bun run build
+bun run benchmark:public-proof
+```
+
+See [docs/benchmark.md](https://github.com/SylphxAI/coderag/blob/main/docs/benchmark.md) for methodology and Latest Run results.
 
 ## License
 
diff --git a/packages/core/package.json b/packages/core/package.json
index 136b843..fc372ca 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -41,7 +41,8 @@
 		"clean": "rm -rf dist",
 		"db:generate": "drizzle-kit generate",
 		"db:migrate": "drizzle-kit migrate",
-		"db:studio": "drizzle-kit studio"
+		"db:studio": "drizzle-kit studio",
+		"lint:fix": "biome check --write ."
 	},
 	"dependencies": {
 		"@ai-sdk/openai": "^1.0.11",
@@ -76,8 +77,10 @@
 	"devDependencies": {
 		"@types/node": "^24.9.2",
 		"drizzle-kit": "^0.28.1",
-		"typescript": "^5.9.3",
-		"vitest": "^4.0.14"
+		"typescript": "^7.0.2",
+		"vitest": "^4.0.14",
+		"@biomejs/biome": "^2.3.12",
+		"@sylphx/biome-config": "^0.4.1"
 	},
 	"keywords": [
 		"rag",
diff --git a/packages/core/src/indexer.ts b/packages/core/src/indexer.ts
index 109ad3a..b9c6ec6 100644
--- a/packages/core/src/indexer.ts
+++ b/packages/core/src/indexer.ts
@@ -1554,10 +1554,19 @@ export class CodebaseIndexer {
 	}
 }
 
+export interface ScoreComponent {
+	term: string
+	termFrequency: number
+	documentFrequency: number
+	idf: number
+	bm25: number
+}
+
 export interface SearchResult {
 	path: string
 	score: number
 	matchedTerms: string[]
+	scoreComponents?: ScoreComponent[]
 	language?: string
 	size: number
 	snippet?: string
diff --git a/packages/mcp-server/README.md b/packages/mcp-server/README.md
index 6ca3cb0..f6b37cc 100644
--- a/packages/mcp-server/README.md
+++ b/packages/mcp-server/README.md
@@ -1,6 +1,9 @@
 # @sylphx/coderag-mcp
 
-MCP server for intelligent codebase search - RAG-ready for AI assistants.
+MCP server for hybrid codebase search — **Did it find the right code?**
+
+Monorepo README, benchmark proof, and Discovery status:
+[github.com/SylphxAI/coderag](https://github.com/SylphxAI/coderag).
 
 ## Quick Start
 
@@ -263,11 +266,13 @@ LLM-optimized output (minimal tokens, maximum content):
 
 ## Performance
 
-| Metric | Value |
-|--------|-------|
-| Startup | 1-5 seconds |
-| Search | <50ms |
-| Memory | ~1-2 MB per 1000 files |
+Run the reproducible public benchmark from the monorepo root (after `bun run build`):
+
+```bash
+bun run benchmark:public-proof
+```
+
+Details: [docs/benchmark.md](https://github.com/SylphxAI/coderag/blob/main/docs/benchmark.md).
 
 ## Development
 
diff --git a/packages/mcp-server/package.json b/packages/mcp-server/package.json
index c27d8af..50fd436 100644
--- a/packages/mcp-server/package.json
+++ b/packages/mcp-server/package.json
@@ -23,7 +23,8 @@
 		"start": "node dist/index.js",
 		"test": "bun test",
 		"type-check": "tsc --noEmit",
-		"clean": "rm -rf dist"
+		"clean": "rm -rf dist",
+		"lint:fix": "biome check --write ."
 	},
 	"dependencies": {
 		"@sylphx/coderag": "workspace:*",
@@ -33,7 +34,9 @@
 	"devDependencies": {
 		"@types/bun": "^1.3.3",
 		"@types/node": "^24.9.2",
-		"typescript": "^5.9.3"
+		"typescript": "^7.0.2",
+		"@biomejs/biome": "^2.3.12",
+		"@sylphx/biome-config": "^0.4.1"
 	},
 	"keywords": [
 		"mcp",
diff --git a/packages/mcp-server/src/doctor.ts b/packages/mcp-server/src/doctor.ts
new file mode 100644
index 0000000..2fea29d
--- /dev/null
+++ b/packages/mcp-server/src/doctor.ts
@@ -0,0 +1,132 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { resolveRustCliBinary } from './rust-engine.js'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+export type DoctorStatus = 'ok' | 'warn' | 'fail'
+
+export interface DoctorCheck {
+	id: string
+	status: DoctorStatus
+	message: string
+}
+
+export interface DoctorReport {
+	profile: 'coderag_doctor'
+	version: string
+	status: 'ready' | 'degraded' | 'unavailable'
+	checks: DoctorCheck[]
+}
+
+const probeRustCore = (): DoctorCheck => {
+	const corePath = join(here, '../../../crates/coderag-core/src/lib.rs')
+	if (existsSync(corePath)) {
+		return {
+			id: 'rust_core',
+			status: 'ok',
+			message: 'coderag-core Rust retrieval engine sources are present.',
+		}
+	}
+
+	return {
+		id: 'rust_core',
+		status: 'fail',
+		message: 'Missing crates/coderag-core/src/lib.rs.',
+	}
+}
+
+const probeCliBinary = (): DoctorCheck => {
+	const binary = resolveRustCliBinary()
+	if (binary !== 'coderag-cli' && existsSync(binary)) {
+		return {
+			id: 'cli_binary',
+			status: 'ok',
+			message: `Rust CLI is available at ${binary}.`,
+		}
+	}
+
+	return {
+		id: 'cli_binary',
+		status: 'warn',
+		message:
+			'Rust CLI binary is not built. Run `cargo build --release` to enable the default native retrieval path.',
+	}
+}
+
+const probeGoldenEvalFixture = (): DoctorCheck => {
+	const fixture = join(here, '../../../fixtures/benchmark-corpus/src/auth/login.ts')
+	if (existsSync(fixture)) {
+		return {
+			id: 'golden_fixture',
+			status: 'ok',
+			message: 'Golden retrieval benchmark corpus is available.',
+		}
+	}
+
+	return {
+		id: 'golden_fixture',
+		status: 'fail',
+		message: 'Missing fixtures/benchmark-corpus for retrieval eval gates.',
+	}
+}
+
+const probeRustEngineFlag = (): DoctorCheck => {
+	if (process.env.CODERAG_USE_RUST_ENGINE === '0') {
+		return {
+			id: 'rust_engine_flag',
+			status: 'warn',
+			message: 'CODERAG_USE_RUST_ENGINE=0 forces the TypeScript indexer adapter path.',
+		}
+	}
+
+	if (process.env.CODERAG_USE_RUST_ENGINE === '1') {
+		return {
+			id: 'rust_engine_flag',
+			status: 'ok',
+			message: 'CODERAG_USE_RUST_ENGINE=1 routes retrieval through the Rust core.',
+		}
+	}
+
+	const binary = resolveRustCliBinary()
+	if (binary !== 'coderag-cli' && existsSync(binary)) {
+		return {
+			id: 'rust_engine_flag',
+			status: 'ok',
+			message: 'Rust CLI is built; keyword retrieval defaults to the Rust core.',
+		}
+	}
+
+	return {
+		id: 'rust_engine_flag',
+		status: 'warn',
+		message:
+			'Rust CLI is not built. The TypeScript indexer remains the default adapter path until `cargo build --release`.',
+	}
+}
+
+export async function runDoctor(version: string): Promise<DoctorReport> {
+	const checks = [
+		probeRustCore(),
+		probeCliBinary(),
+		probeGoldenEvalFixture(),
+		probeRustEngineFlag(),
+	]
+	const hasFail = checks.some((check) => check.status === 'fail')
+	const hasWarn = checks.some((check) => check.status === 'warn')
+
+	return {
+		profile: 'coderag_doctor',
+		version,
+		status: hasFail ? 'unavailable' : hasWarn ? 'degraded' : 'ready',
+		checks,
+	}
+}
+
+if (import.meta.main) {
+	const pkg = JSON.parse(readFileSync(join(here, '../package.json'), 'utf8')) as { version: string }
+	const report = await runDoctor(pkg.version)
+	console.log(JSON.stringify(report, null, 2))
+	process.exit(report.status === 'unavailable' ? 1 : 0)
+}
diff --git a/packages/mcp-server/src/evidence.ts b/packages/mcp-server/src/evidence.ts
new file mode 100644
index 0000000..e08dd0f
--- /dev/null
+++ b/packages/mcp-server/src/evidence.ts
@@ -0,0 +1,132 @@
+import type { SearchResult } from '@sylphx/coderag'
+
+export type RetrievalRoute = 'tfidf' | 'semantic' | 'rust-tfidf' | 'rust-semantic-hybrid'
+
+export interface RetrievalEngineEvidence {
+	contract_version: string
+	index: 'rust-tfidf' | 'typescript'
+	search: RetrievalRoute
+}
+
+export interface RetrievalLocator {
+	path: string
+	startLine?: number
+	endLine?: number
+}
+
+export interface ScoreComponentEvidence {
+	term: string
+	termFrequency: number
+	documentFrequency: number
+	idf: number
+	bm25: number
+}
+
+export interface RetrievalResultEvidence {
+	path: string
+	locator: RetrievalLocator
+	score: number
+	matchedTerms: string[]
+	scoreComponents?: ScoreComponentEvidence[]
+	route: RetrievalRoute
+	confidence: 'deterministic' | 'derived' | 'inferred' | 'unknown'
+	snippet?: string
+	chunkType?: string
+	language?: string
+}
+
+export interface CodebaseSearchEnvelope {
+	status: 'ok' | 'error'
+	subject: 'codebase_search'
+	query: string
+	route: RetrievalRoute
+	engine: RetrievalEngineEvidence
+	freshness: {
+		indexedFiles: number
+		indexing: boolean
+		stale: boolean
+	}
+	results: RetrievalResultEvidence[]
+	warnings: string[]
+	nextActions: string[]
+}
+
+export function buildCodebaseSearchEnvelope(input: {
+	query: string
+	route: RetrievalRoute
+	engine: RetrievalEngineEvidence
+	indexedFiles: number
+	indexing: boolean
+	results: SearchResult[]
+	warnings?: string[]
+}): CodebaseSearchEnvelope {
+	return {
+		status: 'ok',
+		subject: 'codebase_search',
+		query: input.query,
+		route: input.route,
+		engine: input.engine,
+		freshness: {
+			indexedFiles: input.indexedFiles,
+			indexing: input.indexing,
+			stale: false,
+		},
+		results: input.results.map((result) => ({
+			path: result.path,
+			locator: {
+				path: result.path,
+				startLine: result.startLine,
+				endLine: result.endLine,
+			},
+			score: result.score,
+			matchedTerms: result.matchedTerms ?? [],
+			...(result.scoreComponents && result.scoreComponents.length > 0
+				? { scoreComponents: result.scoreComponents }
+				: {}),
+			route: input.route,
+			confidence: 'deterministic',
+			snippet: result.snippet,
+			chunkType: result.chunkType,
+			language: result.language,
+		})),
+		warnings: input.warnings ?? [],
+		nextActions: [
+			'Open the top result path and verify the cited line range before editing.',
+			'Re-run codebase_search after index refresh if files changed.',
+		],
+	}
+}
+
+export function mapRustHitsToSearchResults(
+	hits: Array<{
+		path: string
+		score: number
+		matchedTerms: string[]
+		scoreComponents?: Array<{
+			term: string
+			termFrequency: number
+			documentFrequency: number
+			idf: number
+			bm25: number
+		}>
+		startLine?: number
+		endLine?: number
+		snippet?: string
+		symbolName?: string
+		chunkType?: string
+	}>
+): SearchResult[] {
+	return hits.map((hit) => ({
+		path: hit.path,
+		score: hit.score,
+		matchedTerms: hit.matchedTerms,
+		...(hit.scoreComponents && hit.scoreComponents.length > 0
+			? { scoreComponents: hit.scoreComponents }
+			: {}),
+		size: hit.snippet?.length ?? 0,
+		startLine: hit.startLine,
+		endLine: hit.endLine,
+		snippet: hit.snippet,
+		...(hit.chunkType || hit.symbolName ? { chunkType: hit.chunkType ?? 'function' } : {}),
+	}))
+}
diff --git a/packages/mcp-server/src/index.ts b/packages/mcp-server/src/index.ts
index 5b43d8a..dfab342 100644
--- a/packages/mcp-server/src/index.ts
+++ b/packages/mcp-server/src/index.ts
@@ -14,6 +14,14 @@ import {
 } from '@sylphx/coderag'
 import { createServer, stdio, text, tool } from '@sylphx/mcp-server-sdk'
 import { array, bool, description, num, object, optional, str } from '@sylphx/vex'
+import { buildCodebaseSearchEnvelope, type RetrievalRoute } from './evidence.js'
+import { invokeRustEngine, shouldUseRustEngine } from './rust-engine.js'
+import {
+	buildRetrievalEngineEvidence,
+	mapHybridResultsToSearchResults,
+	mapRustSearchEnvelope,
+	mergeRustLexicalWithSemantic,
+} from './search-coordinator.js'
 
 // Logger utility (stderr for MCP)
 const Logger = {
@@ -72,6 +80,8 @@ async function main() {
 	}
 
 	const isSemanticSearch = !!embeddingProvider
+	const useRustIndexing = shouldUseRustEngine()
+	const useRustSearch = shouldUseRustEngine() && !isSemanticSearch
 
 	// Create persistent storage
 	const storage = new PersistentStorage({ codebaseRoot })
@@ -93,6 +103,7 @@ async function main() {
 
 	// Track indexing state for search handler
 	let indexingPending = autoIndex // Will be set to false once indexing completes or fails
+	let rustIndexedChunks = 0
 
 	// Tool descriptions based on search mode
 	const toolDescription = isSemanticSearch
@@ -196,24 +207,63 @@ When to use:
 					snippet?: string
 					content?: string
 				}>
+				let route: RetrievalRoute = useRustSearch
+					? 'rust-tfidf'
+					: isSemanticSearch
+						? 'semantic'
+						: 'tfidf'
+
 				try {
-					results = isSemanticSearch
-						? await semanticSearch(query, indexer, {
-								limit,
-								fileExtensions: file_extensions,
-								pathFilter: path_filter,
-								excludePaths: exclude_paths,
-							})
-						: await indexer.search(query, {
-								limit,
-								includeContent: include_content,
+					if (useRustSearch) {
+						const rust = invokeRustEngine('coderag_search', {
+							root: codebaseRoot,
+							query,
+							limit,
+						})
+						if (rust.status === 'ok' && rust.results) {
+							results = mapRustSearchEnvelope(rust, limit)
+						} else {
+							throw new Error(rust.message ?? 'Rust retrieval engine failed')
+						}
+					} else if (isSemanticSearch && useRustIndexing) {
+						const candidateLimit = Math.max(limit * 4, 20)
+						const rust = invokeRustEngine('coderag_search', {
+							root: codebaseRoot,
+							query,
+							limit: candidateLimit,
+						})
+						const rustHits = mapRustSearchEnvelope(rust, candidateLimit)
+						const semanticHits = mapHybridResultsToSearchResults(
+							await semanticSearch(query, indexer, {
+								limit: candidateLimit,
 								fileExtensions: file_extensions,
 								pathFilter: path_filter,
 								excludePaths: exclude_paths,
-								contextLines: context_lines,
-								maxSnippetChars: max_snippet_chars,
-								maxSnippetBlocks: max_snippet_blocks,
 							})
+						)
+						results = mergeRustLexicalWithSemantic(rustHits, semanticHits, limit)
+						route = 'rust-semantic-hybrid'
+					} else {
+						results = isSemanticSearch
+							? mapHybridResultsToSearchResults(
+									await semanticSearch(query, indexer, {
+										limit,
+										fileExtensions: file_extensions,
+										pathFilter: path_filter,
+										excludePaths: exclude_paths,
+									})
+								)
+							: await indexer.search(query, {
+									limit,
+									includeContent: include_content,
+									fileExtensions: file_extensions,
+									pathFilter: path_filter,
+									excludePaths: exclude_paths,
+									contextLines: context_lines,
+									maxSnippetChars: max_snippet_chars,
+									maxSnippetBlocks: max_snippet_blocks,
+								})
+					}
 				} catch (searchError) {
 					// Index not ready yet (background indexing hasn't completed)
 					const errorMsg = (searchError as Error).message
@@ -240,101 +290,23 @@ When to use:
 					throw searchError
 				}
 
-				// Get indexed count for display
-				const indexedCount = await indexer.getIndexedCount()
-
-				if (results.length === 0) {
-					return text(
-						`# Search: "${query}" (0 results)\n\nNo matches found. Try different terms or check filters.\nIndexed files: ${indexedCount}`
-					)
-				}
-
-				// Format results - optimized for LLM consumption (minimal tokens, maximum content)
-				let formattedResults = `# Search: "${query}" (${results.length} results)\n\n`
-
-				for (const result of results as Array<{
-					path: string
-					score: number
-					language?: string
-					size?: number
-					matchedTerms?: string[]
-					snippet?: string
-					content?: string
-					chunkType?: string
-					startLine?: number
-					endLine?: number
-				}>) {
-					// Build file path with line range (check !== undefined since 0 is valid)
-					let header = result.path
-					if (result.startLine !== undefined && result.endLine !== undefined) {
-						header += `:${result.startLine}-${result.endLine}`
-					}
-
-					// Add embedded indicator for code blocks in markdown/html
-					const isEmbedded =
-						result.chunkType?.startsWith('code') &&
-						(result.language === 'Markdown' || result.language === 'HTML')
-					if (isEmbedded) {
-						// Extract embedded language from snippet if available (e.g., "66: ```typescript")
-						const langMatch = result.snippet?.match(/```(\w+)/)
-						const embeddedLang = langMatch?.[1] || 'code'
-						header += ` [${result.language?.toLowerCase()}→${embeddedLang}]`
-					}
-
-					formattedResults += `## ${header}\n`
-
-					// Show content snippet
-					const maxSnippetLen = 2000 // Max chars for snippet display
-
-					if (result.snippet) {
-						// Determine language for syntax highlighting
-						let lang = ''
-						if (isEmbedded) {
-							// For embedded code, extract the actual language
-							const langMatch = result.snippet.match(/```(\w+)/)
-							lang = langMatch?.[1] || ''
-						} else {
-							lang = result.language?.toLowerCase() || ''
-						}
-
-						// Truncate long snippets with head+tail format
-						let snippetContent = result.snippet
-						if (snippetContent.length > maxSnippetLen) {
-							const headLen = Math.floor(maxSnippetLen * 0.7) // 70% head
-							const tailLen = Math.floor(maxSnippetLen * 0.2) // 20% tail
-							const head = snippetContent.substring(0, headLen)
-							const tail = snippetContent.substring(snippetContent.length - tailLen)
-							const truncatedChars = snippetContent.length - headLen - tailLen
-							snippetContent = `${head}\n\n... [${truncatedChars} chars truncated] ...\n\n${tail}`
-							// Add truncation indicator to header
-							formattedResults = `${formattedResults.trimEnd()} [truncated]\n`
-						}
-						formattedResults += `\`\`\`${lang}\n${snippetContent}\n\`\`\`\n\n`
-					} else if (result.content) {
-						// Truncate long content with head+tail format
-						const maxLen = 500
-						let preview: string
-						let isTruncated = false
-						if (result.content.length > maxLen) {
-							isTruncated = true
-							// Show first 350 chars + ... + last 100 chars
-							const headLen = 350
-							const tailLen = 100
-							const head = result.content.substring(0, headLen)
-							const tail = result.content.substring(result.content.length - tailLen)
-							preview = `${head}\n\n... [${result.content.length - headLen - tailLen} chars truncated] ...\n\n${tail}`
-						} else {
-							preview = result.content
-						}
-						// Add truncation indicator to header if needed
-						if (isTruncated) {
-							formattedResults = `${formattedResults.trimEnd()} [truncated]\n`
-						}
-						formattedResults += `\`\`\`\n${preview}\n\`\`\`\n\n`
-					}
-				}
+				const indexedCount = useRustIndexing ? rustIndexedChunks : await indexer.getIndexedCount()
 
-				return text(formattedResults)
+				const envelope = buildCodebaseSearchEnvelope({
+					query,
+					route,
+					engine: buildRetrievalEngineEvidence({
+						useRustIndexing,
+						route,
+					}),
+					indexedFiles: indexedCount,
+					indexing: status.isIndexing,
+					results: results as import('@sylphx/coderag').SearchResult[],
+					warnings:
+						results.length === 0 ? ['No matches found for the query and active filters.'] : [],
+				})
+
+				return text(JSON.stringify(envelope, null, 2))
 			} catch (error) {
 				return text(`✗ Codebase search error: ${(error as Error).message}`)
 			}
@@ -361,7 +333,24 @@ When to use:
 
 	// Start indexing BEFORE server.start() since server.start() blocks waiting for client
 	// This way indexing runs concurrently while waiting for MCP client to connect
-	if (autoIndex) {
+	if (useRustIndexing) {
+		Logger.info(
+			isSemanticSearch
+				? '🦀 Rust TF-IDF index enabled for semantic hybrid retrieval'
+				: '🦀 Rust TF-IDF engine enabled (default when coderag-cli is built)'
+		)
+		const rustIndex = invokeRustEngine('coderag_index', {
+			root: codebaseRoot,
+			maxFileBytes: maxFileSize,
+			mode: 'auto',
+		})
+		rustIndexedChunks = rustIndex.index?.chunksIndexed ?? 0
+		if (!isSemanticSearch) {
+			indexingPending = false
+		}
+	}
+
+	if ((!useRustIndexing || isSemanticSearch) && autoIndex) {
 		Logger.info('📚 Starting automatic indexing...')
 		// Don't await - let it run in background
 		indexer
diff --git a/packages/mcp-server/src/rust-engine.ts b/packages/mcp-server/src/rust-engine.ts
new file mode 100644
index 0000000..a0d9024
--- /dev/null
+++ b/packages/mcp-server/src/rust-engine.ts
@@ -0,0 +1,92 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+export type RustSearchEnvelope = {
+	status: string
+	query?: string
+	results?: Array<{
+		path: string
+		score: number
+		matchedTerms: string[]
+		scoreComponents?: Array<{
+			term: string
+			termFrequency: number
+			documentFrequency: number
+			idf: number
+			bm25: number
+		}>
+		startLine?: number
+		endLine?: number
+		snippet?: string
+		symbolName?: string
+		chunkType?: string
+	}>
+	index?: {
+		refreshMode?: string
+		filesChanged?: number
+		filesRemoved?: number
+		filesScanned?: number
+		chunksIndexed?: number
+	}
+	code?: string
+	message?: string
+}
+
+export function resolveRustCliBinary(): string {
+	const env = process.env.CODERAG_RUST_CLI
+	if (env && existsSync(env)) return env
+
+	const release = join(here, '../../../target/release/coderag-cli')
+	if (existsSync(release)) return release
+
+	const debug = join(here, '../../../target/debug/coderag-cli')
+	if (existsSync(debug)) return debug
+
+	return 'coderag-cli'
+}
+
+export function isRustCliAvailable(): boolean {
+	return resolveRustCliBinary() !== 'coderag-cli'
+}
+
+export function invokeRustEngine(tool: string, input: Record<string, unknown>): RustSearchEnvelope {
+	const binary = resolveRustCliBinary()
+	const payload = JSON.stringify({ tool, input })
+	const result = spawnSync(binary, [], {
+		input: payload,
+		encoding: 'utf8',
+		maxBuffer: 16 * 1024 * 1024,
+	})
+
+	if (result.error) {
+		return {
+			status: 'error',
+			code: 'ENGINE_UNAVAILABLE',
+			message: result.error.message,
+		}
+	}
+
+	if (result.status !== 0) {
+		return {
+			status: 'error',
+			code: 'ENGINE_FAILED',
+			message: result.stderr || `Rust engine exited with status ${result.status}`,
+		}
+	}
+
+	return JSON.parse(result.stdout) as RustSearchEnvelope
+}
+
+export function shouldUseRustEngine(): boolean {
+	if (process.env.CODERAG_USE_RUST_ENGINE === '0') {
+		return false
+	}
+	if (process.env.CODERAG_USE_RUST_ENGINE === '1') {
+		return true
+	}
+	return isRustCliAvailable()
+}
diff --git a/packages/mcp-server/src/search-coordinator.ts b/packages/mcp-server/src/search-coordinator.ts
new file mode 100644
index 0000000..a9e891d
--- /dev/null
+++ b/packages/mcp-server/src/search-coordinator.ts
@@ -0,0 +1,82 @@
+import type { HybridSearchResult, SearchResult } from '@sylphx/coderag'
+import type { RetrievalEngineEvidence, RetrievalRoute } from './evidence.js'
+import { mapRustHitsToSearchResults } from './evidence.js'
+import type { RustSearchEnvelope } from './rust-engine.js'
+
+export const RETRIEVAL_CONTRACT_VERSION = 'coderag-retrieval-v1'
+
+const resultKey = (result: { path: string; startLine?: number; endLine?: number }): string =>
+	`${result.path}:${result.startLine ?? 0}:${result.endLine ?? 0}`
+
+export const mapHybridResultsToSearchResults = (results: HybridSearchResult[]): SearchResult[] =>
+	results.map((result) => ({
+		path: result.path,
+		score: result.score,
+		matchedTerms: result.matchedTerms ?? [],
+		size: result.content?.length ?? 0,
+		snippet: result.content,
+		chunkType: result.chunkType,
+		startLine: result.startLine,
+		endLine: result.endLine,
+		language: result.language,
+	}))
+
+export const mergeRustLexicalWithSemantic = (
+	rustHits: SearchResult[],
+	semanticHits: SearchResult[],
+	limit: number
+): SearchResult[] => {
+	const rustByKey = new Map(rustHits.map((hit) => [resultKey(hit), hit]))
+	const semanticByKey = new Map(semanticHits.map((hit) => [resultKey(hit), hit]))
+	const mergedKeys = new Set([...rustByKey.keys(), ...semanticByKey.keys()])
+
+	const merged = [...mergedKeys].map((key) => {
+		const rustHit = rustByKey.get(key)
+		const semanticHit = semanticByKey.get(key)
+
+		if (rustHit && semanticHit) {
+			return {
+				...semanticHit,
+				score: semanticHit.score * 0.7 + rustHit.score * 0.3,
+				matchedTerms: [
+					...new Set([...(semanticHit.matchedTerms ?? []), ...(rustHit.matchedTerms ?? [])]),
+				],
+				...(rustHit.scoreComponents && rustHit.scoreComponents.length > 0
+					? { scoreComponents: rustHit.scoreComponents }
+					: {}),
+			}
+		}
+
+		if (semanticHit) {
+			return { ...semanticHit, score: semanticHit.score * 0.85 }
+		}
+
+		if (!rustHit) {
+			throw new Error('Merged retrieval key is missing both rust and semantic hits.')
+		}
+
+		return { ...rustHit, score: rustHit.score * 0.35 }
+	})
+
+	return merged.sort((left, right) => right.score - left.score).slice(0, limit)
+}
+
+export const buildRetrievalEngineEvidence = (input: {
+	useRustIndexing: boolean
+	route: RetrievalRoute
+}): RetrievalEngineEvidence => ({
+	contract_version: RETRIEVAL_CONTRACT_VERSION,
+	index: input.useRustIndexing ? 'rust-tfidf' : 'typescript',
+	search: input.route,
+})
+
+export const mapRustSearchEnvelope = (
+	envelope: RustSearchEnvelope,
+	limit: number
+): SearchResult[] => {
+	if (envelope.status !== 'ok' || !envelope.results) {
+		return []
+	}
+
+	return mapRustHitsToSearchResults(envelope.results).slice(0, limit)
+}
diff --git a/packages/mcp-server/test/boundary.test.ts b/packages/mcp-server/test/boundary.test.ts
new file mode 100644
index 0000000..b7397d4
--- /dev/null
+++ b/packages/mcp-server/test/boundary.test.ts
@@ -0,0 +1,54 @@
+import { beforeAll, describe, expect, test } from 'bun:test'
+import { execSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { invokeRustEngine, isRustCliAvailable, shouldUseRustEngine } from '../src/rust-engine.js'
+
+const fixtureRoot = join(dirname(fileURLToPath(import.meta.url)), '../../../fixtures/benchmark-corpus')
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+
+describe('Rust core boundary', () => {
+	beforeAll(() => {
+		execSync('cargo build -q --release', { cwd: repoRoot, stdio: 'pipe', timeout: 180_000 })
+	}, 180_000)
+	test('defaults to the Rust CLI when it is built', () => {
+		expect(isRustCliAvailable()).toBe(true)
+		expect(shouldUseRustEngine()).toBe(true)
+	})
+
+	test('indexes and searches fixture corpus via coderag-cli', () => {
+		const index = invokeRustEngine('coderag_index', { root: fixtureRoot, mode: 'full' })
+		expect(index.status).toBe('ok')
+
+		const search = invokeRustEngine('coderag_search', {
+			root: fixtureRoot,
+			query: 'user authentication login',
+			limit: 5,
+		})
+		expect(search.status).toBe('ok')
+		expect(search.results?.length).toBeGreaterThan(0)
+		expect(search.results?.some((hit) => hit.path.includes('auth/login'))).toBe(true)
+	})
+
+	test('returns cache_hit on unchanged auto refresh and score explainability', () => {
+		const first = invokeRustEngine('coderag_index', { root: fixtureRoot, mode: 'auto' })
+		const second = invokeRustEngine('coderag_index', { root: fixtureRoot, mode: 'auto' })
+		expect(first.status).toBe('ok')
+		expect(second.status).toBe('ok')
+		expect(second.index?.refreshMode).toBe('cache_hit')
+
+		const search = invokeRustEngine('coderag_search', {
+			root: fixtureRoot,
+			query: 'database connection pool',
+			limit: 1,
+		})
+		expect(search.results?.[0]?.scoreComponents?.length).toBeGreaterThan(0)
+	})
+
+	test('keeps retrieval logic out of the TypeScript adapter sources', () => {
+		const engineSrc = readFileSync(join(dirname(fileURLToPath(import.meta.url)), '../src/rust-engine.ts'), 'utf8')
+		expect(engineSrc).toContain('spawnSync')
+		expect(engineSrc).not.toContain('buildSearchIndex')
+	})
+})
diff --git a/packages/mcp-server/test/evidence.test.ts b/packages/mcp-server/test/evidence.test.ts
new file mode 100644
index 0000000..9c215dc
--- /dev/null
+++ b/packages/mcp-server/test/evidence.test.ts
@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test'
+import { buildCodebaseSearchEnvelope } from '../src/evidence.js'
+
+describe('codebase search evidence envelope', () => {
+	test('builds structured retrieval contract fields', () => {
+		const envelope = buildCodebaseSearchEnvelope({
+			query: 'user authentication login',
+			route: 'rust-tfidf',
+			engine: {
+				contract_version: 'coderag-retrieval-v1',
+				index: 'rust-tfidf',
+				search: 'rust-tfidf',
+			},
+			indexedFiles: 31,
+			indexing: false,
+			results: [
+				{
+					path: 'src/auth/login.ts',
+					score: 1.2,
+					matchedTerms: ['authentication', 'login'],
+					size: 120,
+					startLine: 1,
+					endLine: 12,
+					snippet: 'export function authenticate() {}',
+				},
+			],
+		})
+
+		expect(envelope.status).toBe('ok')
+		expect(envelope.subject).toBe('codebase_search')
+		expect(envelope.route).toBe('rust-tfidf')
+		expect(envelope.engine.contract_version).toBe('coderag-retrieval-v1')
+		expect(envelope.engine.index).toBe('rust-tfidf')
+		expect(envelope.results[0]?.locator.startLine).toBe(1)
+		expect(envelope.results[0]?.confidence).toBe('deterministic')
+		expect(envelope.nextActions.length).toBeGreaterThan(0)
+	})
+})
diff --git a/packages/mcp-server/test/search-coordinator.test.ts b/packages/mcp-server/test/search-coordinator.test.ts
new file mode 100644
index 0000000..264af05
--- /dev/null
+++ b/packages/mcp-server/test/search-coordinator.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, test } from 'bun:test'
+import {
+	buildRetrievalEngineEvidence,
+	mergeRustLexicalWithSemantic,
+	RETRIEVAL_CONTRACT_VERSION,
+} from '../src/search-coordinator.js'
+
+describe('search coordinator', () => {
+	test('merges rust lexical and semantic hits into a hybrid ranking', () => {
+		const merged = mergeRustLexicalWithSemantic(
+			[
+				{
+					path: 'src/auth/login.ts',
+					score: 2,
+					matchedTerms: ['login'],
+					size: 100,
+					startLine: 1,
+					endLine: 10,
+				},
+			],
+			[
+				{
+					path: 'src/auth/login.ts',
+					score: 1,
+					matchedTerms: ['authentication'],
+					size: 100,
+					startLine: 1,
+					endLine: 10,
+				},
+				{
+					path: 'src/db/pool.ts',
+					score: 0.9,
+					matchedTerms: ['database'],
+					size: 80,
+				},
+			],
+			2
+		)
+
+		expect(merged).toHaveLength(2)
+		expect(merged[0]?.path).toBe('src/auth/login.ts')
+		expect(merged[0]?.matchedTerms).toEqual(expect.arrayContaining(['login', 'authentication']))
+	})
+
+	test('builds unified engine metadata across retrieval routes', () => {
+		expect(
+			buildRetrievalEngineEvidence({
+				useRustIndexing: true,
+				route: 'rust-semantic-hybrid',
+			})
+		).toEqual({
+			contract_version: RETRIEVAL_CONTRACT_VERSION,
+			index: 'rust-tfidf',
+			search: 'rust-semantic-hybrid',
+		})
+	})
+})
diff --git a/packages/mcp-server/tsconfig.json b/packages/mcp-server/tsconfig.json
index 93d4657..fda07a5 100644
--- a/packages/mcp-server/tsconfig.json
+++ b/packages/mcp-server/tsconfig.json
@@ -17,9 +17,14 @@
 		"skipLibCheck": true,
 		"forceConsistentCasingInFileNames": true,
 		"resolveJsonModule": true,
-		"allowSyntheticDefaultImports": true
+		"allowSyntheticDefaultImports": true,
+		"types": ["bun"]
 	},
 	"include": ["src/**/*"],
 	"exclude": ["node_modules", "dist"],
-	"references": [{ "path": "../core" }]
+	"references": [
+		{
+			"path": "../core"
+		}
+	]
 }
diff --git a/scripts/benchmark-public-proof.ts b/scripts/benchmark-public-proof.ts
new file mode 100644
index 0000000..520e69b
--- /dev/null
+++ b/scripts/benchmark-public-proof.ts
@@ -0,0 +1,117 @@
+#!/usr/bin/env bun
+/**
+ * Reproducible public benchmark for CodeRAG README claims.
+ * Indexes fixtures/benchmark-corpus, runs hybrid TF-IDF search 20x, prints p50 latency.
+ */
+
+import fs from 'node:fs'
+import path from 'node:path'
+import { performance } from 'node:perf_hooks'
+import { fileURLToPath } from 'node:url'
+import { CodebaseIndexer } from '../packages/core/src/indexer.ts'
+import { MemoryStorage } from '../packages/core/src/storage.ts'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const corpusRoot = path.resolve(__dirname, '../fixtures/benchmark-corpus')
+const SEARCH_ITERATIONS = 20
+const WARMUP_ITERATIONS = 3
+
+const queries = [
+	'user authentication login',
+	'database connection pool',
+	'handle request router',
+	'rate limit middleware',
+	'retry utility function',
+]
+
+const countTypeScriptFiles = (dir: string): number => {
+	let count = 0
+	for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+		const fullPath = path.join(dir, entry.name)
+		if (entry.isDirectory()) {
+			count += countTypeScriptFiles(fullPath)
+		} else if (entry.isFile() && entry.name.endsWith('.ts')) {
+			count += 1
+		}
+	}
+	return count
+}
+
+const percentile = (sorted: number[], p: number): number => {
+	const index = Math.ceil((p / 100) * sorted.length) - 1
+	return sorted[Math.max(0, Math.min(index, sorted.length - 1))]
+}
+
+const formatMs = (value: number): string => `${value.toFixed(1)} ms`
+
+async function main(): Promise<void> {
+	const fixtureFileCount = countTypeScriptFiles(path.join(corpusRoot, 'src'))
+	const storage = new MemoryStorage()
+	const indexer = new CodebaseIndexer({
+		codebaseRoot: corpusRoot,
+		storage,
+		lowMemoryMode: false,
+	})
+
+	const indexStart = performance.now()
+	await indexer.index()
+	const indexDurationMs = performance.now() - indexStart
+
+	const indexedFiles = await storage.count()
+	const status = indexer.getStatus()
+	const filesPerSecond = indexedFiles / (indexDurationMs / 1000)
+
+	for (let i = 0; i < WARMUP_ITERATIONS; i++) {
+		await indexer.search(queries[i % queries.length], { limit: 10, includeContent: true })
+	}
+
+	const latencies: number[] = []
+	for (let i = 0; i < SEARCH_ITERATIONS; i++) {
+		const query = queries[i % queries.length]
+		const start = performance.now()
+		await indexer.search(query, { limit: 10, includeContent: true })
+		latencies.push(performance.now() - start)
+	}
+
+	await indexer.close()
+
+	const sorted = [...latencies].sort((a, b) => a - b)
+	const report = {
+		profile: 'coderag-public-proof',
+		corpus: {
+			path: corpusRoot,
+			fixtureTypeScriptFiles: fixtureFileCount,
+			indexedFiles,
+			indexedChunks: status.totalChunks,
+		},
+		indexing: {
+			durationMs: Number(indexDurationMs.toFixed(1)),
+			filesPerSecond: Number(filesPerSecond.toFixed(1)),
+		},
+		search: {
+			iterations: SEARCH_ITERATIONS,
+			warmupIterations: WARMUP_ITERATIONS,
+			queries,
+			p50Ms: Number(percentile(sorted, 50).toFixed(1)),
+			minMs: Number(sorted[0].toFixed(1)),
+			maxMs: Number(sorted[sorted.length - 1].toFixed(1)),
+			avgMs: Number((sorted.reduce((sum, value) => sum + value, 0) / sorted.length).toFixed(1)),
+		},
+	}
+
+	console.log(JSON.stringify(report, null, 2))
+	console.error('')
+	console.error('CodeRAG public benchmark proof')
+	console.error(
+		`Corpus: ${fixtureFileCount} fixture .ts files, ${indexedFiles} indexed files, ${status.totalChunks} chunks`
+	)
+	console.error(`Indexing: ${formatMs(indexDurationMs)} (${filesPerSecond.toFixed(1)} files/sec)`)
+	console.error(
+		`Search (TF-IDF, ${SEARCH_ITERATIONS} runs after ${WARMUP_ITERATIONS} warmup): p50 ${formatMs(report.search.p50Ms)}, avg ${formatMs(report.search.avgMs)}, min ${formatMs(report.search.minMs)}, max ${formatMs(report.search.maxMs)}`
+	)
+}
+
+main().catch((error) => {
+	console.error(error)
+	process.exit(1)
+})
diff --git a/scripts/release-gate.ts b/scripts/release-gate.ts
new file mode 100644
index 0000000..7929a7c
--- /dev/null
+++ b/scripts/release-gate.ts
@@ -0,0 +1,235 @@
+import { spawnSync } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { runDoctor } from '../packages/mcp-server/src/doctor.ts'
+import { buildCodebaseSearchEnvelope } from '../packages/mcp-server/src/evidence.ts'
+import { invokeRustEngine } from '../packages/mcp-server/src/rust-engine.ts'
+import {
+	buildRetrievalEngineEvidence,
+	RETRIEVAL_CONTRACT_VERSION,
+} from '../packages/mcp-server/src/search-coordinator.ts'
+
+const ARTIFACT_DIR_ENV = 'CODERAG_BENCHMARK_OUTPUT_DIR'
+const DEFAULT_ARTIFACT_DIR = 'benchmark-artifacts'
+const ARTIFACT_FILE = 'coderag_release_gate.json'
+
+type GateStatus = 'passed' | 'failed'
+
+interface GateCheck {
+	id: string
+	status: GateStatus
+	message: string
+	evidence?: Record<string, unknown>
+}
+
+interface ReleaseGateReport {
+	profile: 'coderag_release_gate'
+	generated_at: string
+	artifact_dir: string
+	status: GateStatus
+	summary: {
+		total: number
+		passed: number
+		failed: number
+	}
+	checks: GateCheck[]
+}
+
+const repoRoot = path.resolve(import.meta.dirname, '..')
+const fixtureRoot = path.join(repoRoot, 'fixtures/benchmark-corpus')
+
+const GOLDEN_QUERIES: Array<{ query: string; expectedPath: string }> = [
+	{ query: 'user authentication login', expectedPath: 'src/auth/login.ts' },
+	{ query: 'database connection pool', expectedPath: 'src/db/pool.ts' },
+	{ query: 'checkRateLimit windowMs', expectedPath: 'src/api/rate-limit.ts' },
+]
+
+const addCheck = (
+	checks: GateCheck[],
+	id: string,
+	passed: boolean,
+	message: string,
+	evidence?: Record<string, unknown>
+): void => {
+	checks.push({
+		id,
+		status: passed ? 'passed' : 'failed',
+		message,
+		...(evidence ? { evidence } : {}),
+	})
+}
+
+const fileExists = (relativePath: string): boolean => existsSync(path.join(repoRoot, relativePath))
+
+export async function buildReleaseGateReport(artifactDir: string): Promise<ReleaseGateReport> {
+	const checks: GateCheck[] = []
+
+	addCheck(
+		checks,
+		'rust:retrieval_core',
+		fileExists('crates/coderag-core/src/engine.rs'),
+		'Rust coderag-core retrieval engine is present'
+	)
+
+	addCheck(
+		checks,
+		'fixtures:benchmark_corpus',
+		fileExists('fixtures/benchmark-corpus/src/auth/login.ts'),
+		'Golden retrieval benchmark corpus is checked in'
+	)
+
+	addCheck(
+		checks,
+		'tests:golden_retrieval',
+		fileExists('test/golden-retrieval.test.ts'),
+		'Golden retrieval eval test harness is present'
+	)
+
+	const doctor = await runDoctor('0.0.0')
+	addCheck(
+		checks,
+		'doctor:golden_fixture',
+		doctor.checks.find((check) => check.id === 'golden_fixture')?.status === 'ok',
+		'doctor reports the golden retrieval corpus is available',
+		{ doctorStatus: doctor.status }
+	)
+
+	const index = invokeRustEngine('coderag_index', { root: fixtureRoot, mode: 'full' })
+	addCheck(
+		checks,
+		'boundary:coderag_index',
+		index.status === 'ok',
+		'coderag_index returns ok from the Rust CLI on the benchmark corpus'
+	)
+
+	const autoRefresh = invokeRustEngine('coderag_index', { root: fixtureRoot, mode: 'auto' })
+	addCheck(
+		checks,
+		'boundary:incremental_cache_hit',
+		autoRefresh.status === 'ok' && autoRefresh.index?.refreshMode === 'cache_hit',
+		'coderag_index mode=auto reuses the persisted index when file hashes are unchanged',
+		{ refreshMode: autoRefresh.index?.refreshMode }
+	)
+
+	for (const { query, expectedPath } of GOLDEN_QUERIES) {
+		const search = invokeRustEngine('coderag_search', {
+			root: fixtureRoot,
+			query,
+			limit: 5,
+		})
+		const hit = search.results?.some((result) => result.path.endsWith(expectedPath)) ?? false
+		addCheck(
+			checks,
+			`golden:${expectedPath}`,
+			search.status === 'ok' && hit,
+			`Rust retrieval returns ${expectedPath} for "${query}"`,
+			{ query, expectedPath, hit }
+		)
+	}
+
+	const sampleEnvelope = buildCodebaseSearchEnvelope({
+		query: 'user authentication login',
+		route: 'rust-semantic-hybrid',
+		engine: buildRetrievalEngineEvidence({
+			useRustIndexing: true,
+			route: 'rust-semantic-hybrid',
+		}),
+		indexedFiles: index.index?.chunksIndexed ?? 0,
+		indexing: false,
+		results: [],
+	})
+	addCheck(
+		checks,
+		'contract:retrieval_envelope',
+		sampleEnvelope.engine.contract_version === RETRIEVAL_CONTRACT_VERSION &&
+			sampleEnvelope.engine.index === 'rust-tfidf' &&
+			sampleEnvelope.engine.search === 'rust-semantic-hybrid',
+		'Unified retrieval envelope documents versioned Rust index and hybrid semantic search routes',
+		{
+			contractVersion: sampleEnvelope.engine.contract_version,
+			indexRoute: sampleEnvelope.engine.index,
+			searchRoute: sampleEnvelope.engine.search,
+		}
+	)
+
+	const pkg = JSON.parse(readFileSync(path.join(repoRoot, 'package.json'), 'utf8')) as {
+		bin?: Record<string, string>
+	}
+
+	const binWrapper = readFileSync(path.join(repoRoot, 'bin/coderag-mcp'), 'utf8')
+	addCheck(
+		checks,
+		'mcp:rust_adapter_default',
+		typeof pkg.bin?.['coderag-mcp'] === 'string' &&
+			binWrapper.includes('coderag-mcp-server') &&
+			binWrapper.includes('resolve_rust_bin') &&
+			binWrapper.includes('use_ts_transport'),
+		'Default npm bin launches the Rust rmcp MCP server; TypeScript adapter is opt-in only'
+	)
+
+	const matrixProbe = spawnSync('bun', ['test', 'test/shippedPath.matrix.test.ts'], {
+		cwd: repoRoot,
+		encoding: 'utf8',
+		env: {
+			...process.env,
+			CODERAG_USE_RUST_ENGINE: '1',
+			CODERAG_MCP_TRANSPORT: '',
+		},
+		timeout: 300_000,
+	})
+	addCheck(
+		checks,
+		'boundary:rust_cli_engine',
+		fileExists('crates/coderag-mcp-server/src/tool_routes.rs') && matrixProbe.status === 0,
+		'Shipped-path matrix test proves primary retrieval routes through Rust core without legacy runtime',
+		matrixProbe.status === 0
+			? { exitCode: 0 }
+			: {
+					exitCode: matrixProbe.status,
+					stderr: matrixProbe.stderr?.slice(-2000),
+					stdout: matrixProbe.stdout?.slice(-2000),
+				}
+	)
+
+	const passed = checks.filter((check) => check.status === 'passed').length
+	const failed = checks.length - passed
+
+	return {
+		profile: 'coderag_release_gate',
+		generated_at: new Date().toISOString(),
+		artifact_dir: artifactDir,
+		status: failed === 0 ? 'passed' : 'failed',
+		summary: {
+			total: checks.length,
+			passed,
+			failed,
+		},
+		checks,
+	}
+}
+
+async function main(): Promise<void> {
+	const artifactDir = path.resolve(
+		process.env[ARTIFACT_DIR_ENV] ?? path.join(repoRoot, DEFAULT_ARTIFACT_DIR)
+	)
+
+	const report = await buildReleaseGateReport(artifactDir)
+	mkdirSync(artifactDir, { recursive: true })
+	const outputPath = path.join(artifactDir, ARTIFACT_FILE)
+	writeFileSync(outputPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8')
+	console.error(`CodeRAG release gate report written to ${outputPath}`)
+
+	if (report.status !== 'passed') {
+		for (const check of report.checks.filter((entry) => entry.status === 'failed')) {
+			console.error(`[FAILED] ${check.id}: ${check.message}`)
+		}
+		process.exit(1)
+	}
+}
+
+if (import.meta.main) {
+	main().catch((error: unknown) => {
+		console.error(error)
+		process.exit(1)
+	})
+}
diff --git a/scripts/stage-rust-mcp.ts b/scripts/stage-rust-mcp.ts
new file mode 100644
index 0000000..661aa18
--- /dev/null
+++ b/scripts/stage-rust-mcp.ts
@@ -0,0 +1,18 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+const repoRoot = path.resolve(import.meta.dirname, '..')
+const source = path.join(repoRoot, 'target/release/coderag-mcp-server')
+const targetDir = path.join(repoRoot, 'bin/native')
+const target = path.join(targetDir, 'coderag-mcp-server')
+
+if (!fs.existsSync(source)) {
+	console.error(`[stage-rust-mcp] Missing release binary at ${source}. Run: bun run build:rust`)
+	process.exit(1)
+}
+
+fs.mkdirSync(targetDir, { recursive: true })
+fs.copyFileSync(source, target)
+fs.chmodSync(target, 0o755)
+
+console.log(`[stage-rust-mcp] Staged ${target}`)
diff --git a/sylphx.json b/sylphx.json
index 10d93ba..6698515 100644
--- a/sylphx.json
+++ b/sylphx.json
@@ -1,4 +1,4 @@
 {
-  "buildDir": "docs",
-  "framework": "static"
+	"buildDir": "docs",
+	"framework": "static"
 }
diff --git a/test/golden-retrieval.test.ts b/test/golden-retrieval.test.ts
new file mode 100644
index 0000000..19cdb1f
--- /dev/null
+++ b/test/golden-retrieval.test.ts
@@ -0,0 +1,53 @@
+import { beforeAll, describe, expect, it } from 'bun:test'
+import { execSync } from 'node:child_process'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { invokeRustEngine } from '../packages/mcp-server/src/rust-engine.ts'
+
+const fixtureRoot = join(dirname(fileURLToPath(import.meta.url)), '../fixtures/benchmark-corpus')
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..')
+
+const GOLDEN_QUERIES: Array<{ query: string; expectedPath: string }> = [
+	{ query: 'user authentication login', expectedPath: 'src/auth/login.ts' },
+	{ query: 'database connection pool', expectedPath: 'src/db/pool.ts' },
+	{ query: 'checkRateLimit windowMs', expectedPath: 'src/api/rate-limit.ts' },
+]
+
+describe('golden retrieval evals (rust-tfidf)', () => {
+	beforeAll(() => {
+		execSync('cargo build -q --release', { cwd: repoRoot, stdio: 'pipe', timeout: 180_000 })
+	}, 180_000)
+
+	it('indexes the public benchmark fixture corpus', () => {
+		const index = invokeRustEngine('coderag_index', { root: fixtureRoot, mode: 'full' })
+		expect(index.status).toBe('ok')
+	})
+
+	it('reuses the persisted index on auto refresh when files are unchanged', () => {
+		const refresh = invokeRustEngine('coderag_index', { root: fixtureRoot, mode: 'auto' })
+		expect(refresh.status).toBe('ok')
+		expect(refresh.index?.refreshMode).toBe('cache_hit')
+	})
+
+	it('loads a persisted snapshot on a fresh engine process without re-indexing', () => {
+		const search = invokeRustEngine('coderag_search', {
+			root: fixtureRoot,
+			query: 'user authentication login',
+			limit: 5,
+		})
+		expect(search.status).toBe('ok')
+		expect(search.results?.some((hit) => hit.path.endsWith('src/auth/login.ts'))).toBe(true)
+	})
+
+	for (const { query, expectedPath } of GOLDEN_QUERIES) {
+		it(`returns ${expectedPath} for "${query}"`, () => {
+			const search = invokeRustEngine('coderag_search', {
+				root: fixtureRoot,
+				query,
+				limit: 5,
+			})
+			expect(search.status).toBe('ok')
+			expect(search.results?.some((hit) => hit.path.endsWith(expectedPath))).toBe(true)
+		})
+	}
+})
diff --git a/test/readmeDiscovery.test.ts b/test/readmeDiscovery.test.ts
new file mode 100644
index 0000000..d742568
--- /dev/null
+++ b/test/readmeDiscovery.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'bun:test'
+import { existsSync, readFileSync } from 'node:fs'
+
+const readText = (path: string) => readFileSync(path, 'utf8')
+
+describe('README discovery surfaces', () => {
+	it('keeps pain-first fold content and honest discovery status', () => {
+		const readme = readText('README.md')
+
+		expect(readme).toContain('Did it find the right code?')
+		expect(readme).toContain('## Why not grep alone?')
+		expect(readme).toContain('claude mcp add coderag')
+		expect(readme).toContain('@sylphx/coderag-mcp')
+		expect(readme).toMatch(/Star the repo|Star this repo/)
+		expect(readme).toContain('Not listed yet')
+		expect(readme).toContain('### Discovery')
+		expect(readme).toContain('grep/ripgrep')
+		expect(readme).toContain('Cloud RAG')
+		expect(readme).toContain('docs/benchmark.md')
+		expect(readme).toContain('docs/articles/stop-code-search-guessing.md')
+		expect(readme).toContain('bun run benchmark:public-proof')
+		expect(readme).toContain('## Security model')
+		expect(readme).toContain('examples/codebase-search-request.json')
+		expect(readme).not.toContain('MacBook Pro')
+		expect(readme).not.toContain('<50ms')
+		expect(readme).not.toContain('1000-2000 files/sec')
+	})
+
+	it('ships the public benchmark script and fixture corpus', () => {
+		expect(existsSync('scripts/benchmark-public-proof.ts')).toBe(true)
+		expect(existsSync('fixtures/benchmark-corpus/src/auth/login.ts')).toBe(true)
+		expect(readText('package.json')).toContain('benchmark:public-proof')
+	})
+
+	it('links the shareable discovery article from docs surfaces', () => {
+		const vitepress = readText('docs/.vitepress/config.ts')
+		const gettingStarted = readText('docs/guide/getting-started.md')
+		const index = readText('docs/index.md')
+
+		expect(existsSync('docs/articles/stop-code-search-guessing.md')).toBe(true)
+		expect(existsSync('docs/benchmark.md')).toBe(true)
+		expect(vitepress).toContain('/articles/stop-code-search-guessing')
+		expect(gettingStarted).toContain('/articles/stop-code-search-guessing')
+		expect(index).toContain('Did it find the right code?')
+	})
+})
diff --git a/test/shippedPath.matrix.test.ts b/test/shippedPath.matrix.test.ts
new file mode 100644
index 0000000..f652060
--- /dev/null
+++ b/test/shippedPath.matrix.test.ts
@@ -0,0 +1,85 @@
+import { beforeAll, describe, expect, it } from 'bun:test'
+import { execSync, spawnSync } from 'node:child_process'
+import { chmodSync, existsSync, mkdtempSync, writeFileSync } from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+const repoRoot = path.resolve(import.meta.dirname, '..')
+const rustCliBin = path.join(repoRoot, 'target/release/coderag-cli')
+const fixtureRoot = path.join(repoRoot, 'fixtures/benchmark-corpus')
+
+type CliEnvelope = {
+	status?: string
+	query?: string
+	results?: Array<{ path?: string; score?: number }>
+	index?: { refreshMode?: string; chunksIndexed?: number }
+	search?: { route?: string }
+	code?: string
+	message?: string
+}
+
+const invokeCli = (tool: string, input: Record<string, unknown>, env: NodeJS.ProcessEnv) => {
+	const probe = spawnSync(rustCliBin, [], {
+		cwd: repoRoot,
+		encoding: 'utf8',
+		env,
+		input: JSON.stringify({ tool, input }),
+		timeout: 60_000,
+	})
+	expect(probe.status).toBe(0)
+	return JSON.parse(probe.stdout) as CliEnvelope
+}
+
+describe('shipped path matrix (Rust core, no legacy flags)', () => {
+	let fakeNodeEnv: NodeJS.ProcessEnv
+	let nodeInvokeLog: string
+
+	beforeAll(() => {
+		execSync('cargo build --release -p coderag-core -p coderag-cli -p coderag-mcp-server', {
+			cwd: repoRoot,
+			stdio: 'pipe',
+			timeout: 300_000,
+		})
+
+		const probeDir = mkdtempSync(path.join(os.tmpdir(), 'coderag-matrix-probe-'))
+		nodeInvokeLog = path.join(probeDir, 'node-invoke.log')
+		const fakeNode = path.join(probeDir, 'node')
+		writeFileSync(fakeNode, `#!/usr/bin/env bash\nprintf '%s\\n' "$@" >> "${nodeInvokeLog}"\nexit 99\n`)
+		chmodSync(fakeNode, 0o755)
+
+		fakeNodeEnv = {
+			...process.env,
+			CODERAG_NODE: fakeNode,
+			CODERAG_USE_RUST_ENGINE: '1',
+			CODERAG_MCP_TRANSPORT: '',
+		}
+	}, 300_000)
+
+	it('coderag_index routes through coderag-core without legacy runtime', () => {
+		const envelope = invokeCli('coderag_index', { root: fixtureRoot, mode: 'full' }, fakeNodeEnv)
+		expect(envelope.status).toBe('ok')
+		expect((envelope.index?.chunksIndexed ?? 0) > 0).toBe(true)
+		expect(existsSync(nodeInvokeLog)).toBe(false)
+	})
+
+	it('coderag_search returns rust-tfidf hits without legacy runtime', () => {
+		invokeCli('coderag_index', { root: fixtureRoot, mode: 'auto' }, fakeNodeEnv)
+		const envelope = invokeCli(
+			'coderag_search',
+			{ root: fixtureRoot, query: 'user authentication login', limit: 5 },
+			fakeNodeEnv
+		)
+		expect(envelope.status).toBe('ok')
+		expect(envelope.search?.route).toBe('rust-tfidf')
+		expect((envelope.results?.length ?? 0) > 0).toBe(true)
+		expect(envelope.results?.some((hit) => hit.path?.includes('auth/login'))).toBe(true)
+		expect(existsSync(nodeInvokeLog)).toBe(false)
+	})
+
+	it('default bin resolves staged rmcp server', () => {
+		const bin = path.join(repoRoot, 'bin/coderag-mcp')
+		expect(existsSync(bin)).toBe(true)
+		const staged = path.join(repoRoot, 'bin/native/coderag-mcp-server')
+		expect(existsSync(staged)).toBe(true)
+	})
+})