scythe-context-mcp 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -6,6 +6,24 @@ This project follows semantic versioning before npm publication where practical.
 
 ## [Unreleased]
 
+## [0.1.4] - 2026-06-14
+
+### Added
+
+- Add keyword-only fallback for hybrid search/context-pack calls when query embedding is unavailable, while preserving explicit `embedding_unavailable` diagnostics for semantic-only mode.
+
+## [0.1.3] - 2026-06-14
+
+### Changed
+
+- Clarify MCP server instructions so Codex prefers Scythe Context for unknown-location, semantic, and related-file lookup, while using `rg` or direct file reads for exact strings, known paths, and small targeted checks.
+- Update Windows Codex App + WSL documentation to prefer a `wsl.exe` wrapper that starts WSL Node, avoiding Windows Node direct access to WSL repo-local SQLite indexes.
+
+### Fixed
+
+- Avoid false binary detection when a UTF-8 scan prefix ends in the middle of a multibyte character.
+- Overwrite stale sqlite-vec rows before inserting embeddings so incremental reindexing cannot fail when embedding ids are reused.
+
 ## [0.1.2] - 2026-06-13
 
 ### Fixed

package/README.en.md

@@ -52,7 +52,7 @@ Codex MCP configuration uses fields such as `command`, `args`, `cwd`, `env`, and
 | --- | --- |
 | Codex and MCP both run on Windows | Use Windows `node.exe` plus Windows npm `npx-cli.js`. |
 | Codex CLI runs inside WSL/Linux/macOS | Use `npx` or `node dist/index.js` from the same environment. |
-| Codex App on Windows opens a WSL repo | The App's WSL MCP bridge may still be unreliable; run MCP on Windows Node and pass the current WSL workspace to the Windows process with `PWD` + `WSLENV`. |
+| Codex App on Windows opens a WSL repo | Use Windows `wsl.exe` to start WSL Node, so the SQLite index stays on the WSL filesystem. Avoid Windows Node directly reading or writing `.scythe-context/` inside a WSL repo. |
 
 ### Native Windows
 
@@ -99,40 +99,42 @@ Here `args` points to the built Scythe Context MCP entrypoint; do not pin `cwd`
 
 ### Windows Codex App + WSL repo
 
-Codex App on Windows may not reliably start WSL-side stdio MCP servers while using WSL agent mode. If MCP tools do not appear in the App, MCP handshakes time out, or config paths cross Windows/WSL boundaries, run the MCP server on Windows Node and let Scythe Context index the WSL repo path.
+Codex App on Windows may not reliably start WSL-side stdio MCP servers while using WSL agent mode. The most reliable tested workaround is to let Codex run Windows `wsl.exe`, then let `wsl.exe` start WSL Node and the WSL npm package.
 
-Minimum config:
+Install inside WSL first:
 
-```toml
-[mcp_servers.scythe_context]
-command = "/mnt/c/nvm4w/nodejs/node.exe"
-args = ['C:\nvm4w\nodejs\node_modules\npm\bin\npx-cli.js', "-y", "scythe-context-mcp"]
-cwd = "/mnt/c/Users/you"
-env_vars = ["GEMINI_API_KEY", "PWD"]
-
-[mcp_servers.scythe_context.env]
-WSLENV = "PWD/p"
+```bash
+npm install -g scythe-context-mcp
+command -v scythe-context-mcp
+scythe-context-mcp --version
 ```
 
-Notes:
-
-- Keep `cwd` on a Windows-accessible directory such as `/mnt/c/Users/you`. Do not use the WSL repo's UNC directory as `cwd`, because npm/npx may go through CMD, and CMD does not support UNC current directories.
-- This `cwd` is not the repo to index; it is only a safe startup directory for the Windows process. The real WSL repo is passed through `PWD/p`.
-- `PWD/p` lets WSL convert the current workspace path into a UNC path readable by the Windows process, so you do not need to edit config for every repo.
-- If `GEMINI_API_KEY` already exists in the Windows user environment or is forwarded by Codex `env_vars`, you do not need to put the key in `WSLENV`.
-- Do not point Windows `node.exe` at `dist/index.js` inside a WSL checkout unless that checkout's dependencies were installed by Windows npm. `better-sqlite3` and `sqlite-vec` include native modules, and Windows Node cannot load native binaries installed by Linux npm.
-
-Proxy URL, model, and auth mode can be written directly in Codex config; they do not need to go through `WSLENV`:
+Then use this Codex config:
 
 ```toml
+[mcp_servers.scythe_context]
+command = "/mnt/c/Windows/System32/wsl.exe"
+args = ["-d", "Ubuntu", "--", "bash", "-lc", "PATH=/home/you/.nvm/current/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin exec /home/you/.nvm/current/bin/scythe-context-mcp"]
+startup_timeout_sec = 40
+tool_timeout_sec = 120
+env_vars = ["PWD", "GEMINI_API_KEY"]
+
 [mcp_servers.scythe_context.env]
-WSLENV = "PWD/p"
+WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
 GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+Notes:
+
+- Replace `Ubuntu` with your WSL distribution name; check it with `wsl.exe -l -v`.
+- Replace `/home/you/.nvm/current/bin` with your WSL Node/npm path; check it inside WSL with `which node` and `which scythe-context-mcp`.
+- Do not pin `cwd` or `SCYTHE_CONTEXT_DEFAULT_PROJECT` in global config. This setup follows the current Codex workspace, so you do not need to edit config for every repo.
+- `WSLENV` lists variable names to preserve across WSL/Windows interop; it does not contain the key itself. Prefer keeping `GEMINI_API_KEY` in the environment that starts Codex, then forward it with `env_vars`; write it directly under `[mcp_servers.scythe_context.env]` only for local throwaway testing.
+- Avoid using Windows Node to index `.scythe-context/` directly inside a WSL repo. SQLite can report `database is locked` across the UNC / WSL filesystem boundary, and native modules can also accidentally mix Windows and WSL binaries.
+
 ### Optional hardening
 
 These settings are not required for a minimal launch, but they help for large repos, first-time `npx` downloads, or a fixed tool surface:
@@ -186,17 +188,19 @@ Supported auth modes:
 
 Official Gemini usually uses `x-goog-api-key`; many third-party proxies use `bearer`. If a proxy requires a query-string key, use `query` and set `GEMINI_API_KEY_QUERY_PARAM` if needed.
 
-`WSLENV` is a WSL interop rule, not a Codex-specific field. You only need it when the Windows Codex App opens a WSL repo and the MCP server is launched through Windows Node. Add `GEMINI_API_KEY`, URL, or model variables to `WSLENV` only when they exist only in the WSL environment:
+`WSLENV` is a WSL interop rule, not a Codex-specific field. You only need it when Windows Codex App opens a WSL repo and the server is launched through a `wsl.exe` wrapper or another cross-environment command. With the `wsl.exe` wrapper above, use the no-suffix form:
 
 ```toml
 [mcp_servers.scythe_context.env]
-WSLENV = "PWD/p:GEMINI_API_KEY/w:GEMINI_BASE_URL/w:GEMINI_MODEL/w:GEMINI_AUTH_MODE/w:GEMINI_OUTPUT_DIMENSIONALITY/w"
+WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
 GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+Use `PWD/p` only if you intentionally run a Windows Node process and need WSL to convert the workspace path to a Windows-readable UNC path. That mode is currently not recommended for directly reading or writing the repo-local SQLite index in WSL.
+
 ## Typical Workflow
 
 1. Check index status first:
@@ -240,6 +244,8 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | Shows symbols, imports, and importedBy for one file. |
 | `gemini_embedding_probe` | Tests Gemini or proxy compatibility and returns endpoint, latency, error classification, and remediation hints. |
 
+`repo_context_pack(mode="hybrid")` and `repo_semantic_search(mode="hybrid")` degrade to keyword-only results when query embedding is unavailable, returning `effectiveMode: "keyword"` and `fallback.reason: "embedding_unavailable"`. `mode="semantic"` does not degrade and returns `status: "embedding_unavailable"` because pure semantic search requires query embedding. Use `rg` / direct file reads for exact strings, known paths, or small targeted checks.
+
 ## Feature Status
 
 Implemented: repo scanning, chunking, SQLite metadata, SQLite FTS5, sqlite-vec, Gemini Embedding 2 provider, semantic/keyword/hybrid search, lightweight symbol/dependency graph, related-file lookup, `repo_context_pack`, provider diagnostics, and index freshness diagnostics.

package/README.md

@@ -52,7 +52,7 @@ Codex MCP 設定使用 `command`、`args`、`cwd`、`env` 與 `env_vars` 等欄
 | --- | --- |
 | Codex 和 MCP 都在 Windows | 用 Windows `node.exe` + Windows npm `npx-cli.js`。 |
 | Codex CLI 在 WSL/Linux/macOS | 用同一個環境內的 `npx` 或 `node dist/index.js`。 |
-| Codex App on Windows 開 WSL repo | 目前 App 的 WSL MCP bridge 仍可能不穩；建議 MCP 跑 Windows Node，再用 `PWD` + `WSLENV` 把目前 WSL workspace 傳給 Windows process。 |
+| Codex App on Windows 開 WSL repo | 建議用 Windows `wsl.exe` 啟動 WSL Node，讓 SQLite index 留在 WSL filesystem。避免 Windows Node 直接讀寫 WSL repo 內的 `.scythe-context/`。 |
 
 ### Native Windows
 
@@ -99,40 +99,42 @@ env_vars = ["GEMINI_API_KEY"]
 
 ### Windows Codex App + WSL repo
 
-目前 Codex App on Windows 的 WSL agent mode 可能無法可靠啟動 WSL-side stdio MCP server。若你遇到 App 裡看不到 MCP tools、MCP handshake timeout、或 config path 混到 Windows/WSL 的問題，建議使用 Windows Node 啟動 MCP，並讓 Scythe Context 透過 WSL path 索引 repo。
+目前 Codex App on Windows 的 WSL agent mode 可能無法可靠直接啟動 WSL-side stdio MCP server。實測較穩的做法是讓 Codex 執行 Windows `wsl.exe`，再由 `wsl.exe` 在 WSL 內啟動 WSL Node 與 WSL npm package。
 
-最小設定：
+先在 WSL 內安裝：
 
-```toml
-[mcp_servers.scythe_context]
-command = "/mnt/c/nvm4w/nodejs/node.exe"
-args = ['C:\nvm4w\nodejs\node_modules\npm\bin\npx-cli.js', "-y", "scythe-context-mcp"]
-cwd = "/mnt/c/Users/you"
-env_vars = ["GEMINI_API_KEY", "PWD"]
-
-[mcp_servers.scythe_context.env]
-WSLENV = "PWD/p"
+```bash
+npm install -g scythe-context-mcp
+command -v scythe-context-mcp
+scythe-context-mcp --version
 ```
 
-注意：
-
-- `cwd` 放 Windows 可用目錄，例如 `/mnt/c/Users/you`。不要把 `cwd` 設成 WSL repo 的 UNC 目錄，因為 npm/npx 可能經過 CMD，而 CMD 不支援 UNC current directory。
-- 這個 `cwd` 不是要索引的 repo，只是 Windows process 的安全啟動位置；真正的 WSL repo 由 `PWD/p` 傳入。
-- `PWD/p` 會讓 WSL 把目前 workspace 路徑轉成 Windows process 可讀的 UNC path；所以不需要每換一個 repo 就改設定。
-- 如果 `GEMINI_API_KEY` 已存在 Windows 使用者環境或由 Codex `env_vars` 直接轉發，就不需要把 key 放進 `WSLENV`。
-- 不要用 Windows `node.exe` 直接執行 WSL checkout 裡的 `dist/index.js`，除非該 checkout 的 dependencies 是用 Windows npm 安裝的。`better-sqlite3` 和 `sqlite-vec` 都包含 native module，Windows Node 不能載入 Linux npm 安裝出的 native binary。
-
-中轉站 URL、model、auth mode 可以直接寫在 Codex config 裡，不需要透過 `WSLENV`：
+然後在 Codex config 使用：
 
 ```toml
+[mcp_servers.scythe_context]
+command = "/mnt/c/Windows/System32/wsl.exe"
+args = ["-d", "Ubuntu", "--", "bash", "-lc", "PATH=/home/you/.nvm/current/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin exec /home/you/.nvm/current/bin/scythe-context-mcp"]
+startup_timeout_sec = 40
+tool_timeout_sec = 120
+env_vars = ["PWD", "GEMINI_API_KEY"]
+
 [mcp_servers.scythe_context.env]
-WSLENV = "PWD/p"
+WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
 GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+注意：
+
+- `Ubuntu` 要換成你的 WSL distribution 名稱；可用 `wsl.exe -l -v` 查看。
+- `/home/you/.nvm/current/bin` 要換成你的 WSL Node/npm 路徑；可在 WSL 內用 `which node`、`which scythe-context-mcp` 確認。
+- 不要在全域 config 固定 `cwd` 或 `SCYTHE_CONTEXT_DEFAULT_PROJECT`。這個設定會跟著 Codex 目前 workspace 走，不需要每換 repo 就改一次。
+- `WSLENV` 這裡列的是要跨 WSL/Windows interop 保留的變數名，不是 key 內容。建議把 `GEMINI_API_KEY` 放在 Codex 啟動環境或系統環境，並用 `env_vars` 轉發；本機臨時測試才考慮直接寫在 `[mcp_servers.scythe_context.env]`。
+- 不建議用 Windows Node 直接索引 WSL repo 內的 `.scythe-context/`。SQLite 在 UNC / WSL filesystem 邊界可能出現 `database is locked`，而且 native modules 也容易混到 Windows/WSL 不同平台的 binary。
+
 ### 可選強化設定
 
 以下設定不是最小啟動必需，但在大型 repo、首次 `npx` 下載或想固定工具面時有用：
@@ -186,17 +188,19 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 
 官方 Gemini 通常使用 `x-goog-api-key`；很多第三方中轉站使用 `bearer`。如果中轉站要求 query string key，可以使用 `query`，必要時再設定 `GEMINI_API_KEY_QUERY_PARAM`。
 
-`WSLENV` 是 WSL interop 規則，不是 Codex 專用欄位。只有在 Windows Codex App + WSL repo 模式需要讓 WSL 把變數轉交給 Windows Node 時才需要。若 `GEMINI_API_KEY`、URL 或 model 只存在 WSL 環境變數，才把它們加進 `WSLENV`：
+`WSLENV` 是 WSL interop 規則，不是 Codex 專用欄位。只有在 Windows Codex App + WSL repo 並透過 `wsl.exe` wrapper 或 Windows Node 跨環境啟動時才需要。若使用上面的 `wsl.exe` wrapper，通常使用無 suffix 形式：
 
 ```toml
 [mcp_servers.scythe_context.env]
-WSLENV = "PWD/p:GEMINI_API_KEY/w:GEMINI_BASE_URL/w:GEMINI_MODEL/w:GEMINI_AUTH_MODE/w:GEMINI_OUTPUT_DIMENSIONALITY/w"
+WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
 GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+若你刻意採用 Windows Node 方案，才需要 `PWD/p` 把 WSL path 轉成 Windows 可讀 UNC path；但目前不建議用它直接讀寫 WSL repo 內的 SQLite index。
+
 ## 常用工作流
 
 1. 先檢查索引狀態：
@@ -240,6 +244,8 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | 查看單一檔案的 symbols、imports、importedBy。 |
 | `gemini_embedding_probe` | 測試 Gemini 或 proxy 相容性，回傳 endpoint、latency、錯誤分類與可修復建議。 |
 
+`repo_context_pack(mode="hybrid")` 和 `repo_semantic_search(mode="hybrid")` 在 query embedding 不可用時會降級成 keyword-only 結果，並回傳 `effectiveMode: "keyword"` 與 `fallback.reason: "embedding_unavailable"`。`mode="semantic"` 不會降級，會回傳 `status: "embedding_unavailable"`，因為純 semantic search 必須有 query embedding。精確字串、已知路徑或小範圍檢查仍建議直接用 `rg` / 直接讀檔。
+
 ## 功能狀態
 
 已完成：repo 掃描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、輕量 symbol/dependency graph、related-file lookup、`repo_context_pack`、provider diagnostics、index freshness diagnostics。

package/README.zh-CN.md

@@ -52,7 +52,7 @@ Codex MCP 配置使用 `command`、`args`、`cwd`、`env` 与 `env_vars` 等字
 | --- | --- |
 | Codex 和 MCP 都在 Windows | 用 Windows `node.exe` + Windows npm `npx-cli.js`。 |
 | Codex CLI 在 WSL/Linux/macOS | 用同一个环境内的 `npx` 或 `node dist/index.js`。 |
-| Codex App on Windows 打开 WSL repo | 目前 App 的 WSL MCP bridge 仍可能不稳定；建议 MCP 跑 Windows Node，再用 `PWD` + `WSLENV` 把当前 WSL workspace 传给 Windows process。 |
+| Codex App on Windows 打开 WSL repo | 建议用 Windows `wsl.exe` 启动 WSL Node，让 SQLite index 留在 WSL filesystem。避免 Windows Node 直接读写 WSL repo 内的 `.scythe-context/`。 |
 
 ### Native Windows
 
@@ -99,40 +99,42 @@ env_vars = ["GEMINI_API_KEY"]
 
 ### Windows Codex App + WSL repo
 
-目前 Codex App on Windows 的 WSL agent mode 可能无法可靠启动 WSL-side stdio MCP server。如果你遇到 App 里看不到 MCP tools、MCP handshake timeout、或 config path 混到 Windows/WSL 的问题，建议使用 Windows Node 启动 MCP，并让 Scythe Context 通过 WSL path 索引 repo。
+目前 Codex App on Windows 的 WSL agent mode 可能无法可靠直接启动 WSL-side stdio MCP server。实测较稳定的做法是让 Codex 执行 Windows `wsl.exe`，再由 `wsl.exe` 在 WSL 内启动 WSL Node 与 WSL npm package。
 
-最小配置：
+先在 WSL 内安装：
 
-```toml
-[mcp_servers.scythe_context]
-command = "/mnt/c/nvm4w/nodejs/node.exe"
-args = ['C:\nvm4w\nodejs\node_modules\npm\bin\npx-cli.js', "-y", "scythe-context-mcp"]
-cwd = "/mnt/c/Users/you"
-env_vars = ["GEMINI_API_KEY", "PWD"]
-
-[mcp_servers.scythe_context.env]
-WSLENV = "PWD/p"
+```bash
+npm install -g scythe-context-mcp
+command -v scythe-context-mcp
+scythe-context-mcp --version
 ```
 
-注意：
-
-- `cwd` 放 Windows 可用目录，例如 `/mnt/c/Users/you`。不要把 `cwd` 设成 WSL repo 的 UNC 目录，因为 npm/npx 可能经过 CMD，而 CMD 不支持 UNC current directory。
-- 这个 `cwd` 不是要索引的 repo，只是 Windows process 的安全启动位置；真正的 WSL repo 由 `PWD/p` 传入。
-- `PWD/p` 会让 WSL 把当前 workspace 路径转成 Windows process 可读的 UNC path；所以不需要每换一个 repo 就改配置。
-- 如果 `GEMINI_API_KEY` 已存在 Windows 用户环境或由 Codex `env_vars` 直接转发，就不需要把 key 放进 `WSLENV`。
-- 不要用 Windows `node.exe` 直接执行 WSL checkout 里的 `dist/index.js`，除非该 checkout 的 dependencies 是用 Windows npm 安装的。`better-sqlite3` 和 `sqlite-vec` 都包含 native module，Windows Node 不能加载 Linux npm 安装出的 native binary。
-
-中转站 URL、model、auth mode 可以直接写在 Codex config 里，不需要通过 `WSLENV`：
+然后在 Codex config 使用：
 
 ```toml
+[mcp_servers.scythe_context]
+command = "/mnt/c/Windows/System32/wsl.exe"
+args = ["-d", "Ubuntu", "--", "bash", "-lc", "PATH=/home/you/.nvm/current/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin exec /home/you/.nvm/current/bin/scythe-context-mcp"]
+startup_timeout_sec = 40
+tool_timeout_sec = 120
+env_vars = ["PWD", "GEMINI_API_KEY"]
+
 [mcp_servers.scythe_context.env]
-WSLENV = "PWD/p"
+WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
 GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+注意：
+
+- `Ubuntu` 要换成你的 WSL distribution 名称；可用 `wsl.exe -l -v` 查看。
+- `/home/you/.nvm/current/bin` 要换成你的 WSL Node/npm 路径；可在 WSL 内用 `which node`、`which scythe-context-mcp` 确认。
+- 不要在全局 config 固定 `cwd` 或 `SCYTHE_CONTEXT_DEFAULT_PROJECT`。这个设置会跟着 Codex 当前 workspace 走，不需要每换 repo 就改一次。
+- `WSLENV` 这里列的是要跨 WSL/Windows interop 保留的变量名，不是 key 内容。建议把 `GEMINI_API_KEY` 放在 Codex 启动环境或系统环境，并用 `env_vars` 转发；只有本机临时测试才考虑直接写在 `[mcp_servers.scythe_context.env]`。
+- 不建议用 Windows Node 直接索引 WSL repo 内的 `.scythe-context/`。SQLite 在 UNC / WSL filesystem 边界可能出现 `database is locked`，而且 native modules 也容易混到 Windows/WSL 不同平台的 binary。
+
 ### 可选强化配置
 
 以下配置不是最小启动必需，但在大型 repo、首次 `npx` 下载或想固定工具面时有用：
@@ -186,17 +188,19 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 
 官方 Gemini 通常使用 `x-goog-api-key`；很多第三方中转站使用 `bearer`。如果中转站要求 query string key，可以使用 `query`，必要时再设置 `GEMINI_API_KEY_QUERY_PARAM`。
 
-`WSLENV` 是 WSL interop 规则，不是 Codex 专用字段。只有在 Windows Codex App + WSL repo 模式需要让 WSL 把变量转交给 Windows Node 时才需要。若 `GEMINI_API_KEY`、URL 或 model 只存在 WSL 环境变量，才把它们加进 `WSLENV`：
+`WSLENV` 是 WSL interop 规则，不是 Codex 专用字段。只有在 Windows Codex App + WSL repo 并通过 `wsl.exe` wrapper 或 Windows Node 跨环境启动时才需要。若使用上面的 `wsl.exe` wrapper，通常使用无 suffix 形式：
 
 ```toml
 [mcp_servers.scythe_context.env]
-WSLENV = "PWD/p:GEMINI_API_KEY/w:GEMINI_BASE_URL/w:GEMINI_MODEL/w:GEMINI_AUTH_MODE/w:GEMINI_OUTPUT_DIMENSIONALITY/w"
+WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
 GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+若你刻意采用 Windows Node 方案，才需要 `PWD/p` 把 WSL path 转成 Windows 可读 UNC path；但目前不建议用它直接读写 WSL repo 内的 SQLite index。
+
 ## 常用工作流
 
 1. 先检查索引状态：
@@ -240,6 +244,8 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | 查看单一文件的 symbols、imports、importedBy。 |
 | `gemini_embedding_probe` | 测试 Gemini 或 proxy 兼容性，返回 endpoint、latency、错误分类与可修复建议。 |
 
+`repo_context_pack(mode="hybrid")` 和 `repo_semantic_search(mode="hybrid")` 在 query embedding 不可用时会降级成 keyword-only 结果，并返回 `effectiveMode: "keyword"` 与 `fallback.reason: "embedding_unavailable"`。`mode="semantic"` 不会降级，会返回 `status: "embedding_unavailable"`，因为纯 semantic search 必须有 query embedding。精确字符串、已知路径或小范围检查仍建议直接用 `rg` / 直接读文件。
+
 ## 功能状态
 
 已完成：repo 扫描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、轻量 symbol/dependency graph、related-file lookup、`repo_context_pack`、provider diagnostics、index freshness diagnostics。

package/dist/cli.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "0.1.2";
+export const PACKAGE_VERSION = "0.1.4";
 export function parseCliArgs(args) {
     if (args.length === 0)
         return { kind: "serve" };

package/dist/index.js

@@ -24,7 +24,7 @@ const server = new McpServer({
     name: "scythe-context-mcp",
     version: PACKAGE_VERSION,
 }, {
-    instructions: "Scythe Context is a local code-context MCP server for Codex. Use repo_index_status first, repo_reindex(dry_run=false) when metadata is missing or stale, and repo_context_pack for task lookup. Only set index_embeddings=true when semantic vectors are needed because chunk text is sent to the configured embedding endpoint. Keep max_context_chars and max_related_context_chars bounded. Use repo_semantic_search for ranking/debugging and repo_related_files for a focused file graph.",
+    instructions: "Scythe Context is a code-context MCP server for Codex. Use it for unknown file locations, semantic/code-intent search, or related files/imports/snippets. Use rg/direct reads for exact strings, known paths, or small checks. Start with repo_index_status; repo_reindex(dry_run=false) only if metadata is missing/stale. Prefer repo_context_pack for task lookup. Set index_embeddings=true only when semantic vectors are needed; chunk text goes to the configured endpoint. Use repo_related_files for focused graphs.",
 });
 registerTools(server, config);
 const transport = new StdioServerTransport();

package/dist/indexing/binary.js

@@ -1,12 +1,11 @@
 import { TextDecoder } from "node:util";
-const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
 export function isProbablyBinary(buffer) {
     if (buffer.length === 0)
         return false;
     if (buffer.includes(0))
         return true;
     try {
-        utf8Decoder.decode(buffer);
+        new TextDecoder("utf-8", { fatal: true }).decode(buffer, { stream: true });
         return false;
     }
     catch {

package/dist/indexing/embeddingWriter.js

@@ -62,9 +62,12 @@ export async function indexMissingEmbeddings(options) {
         ${limitSql}
       `)
             .all({ embeddingSetId, maxChunks: options.maxChunks });
-        const insertVector = db.prepare(`insert or replace into ${vectorTableName(options.dimensions)}(rowid, embedding) values (?, ?)`);
+        const vectorTable = vectorTableName(options.dimensions);
+        const deleteVector = db.prepare(`delete from ${vectorTable} where rowid = ?`);
+        const insertVector = db.prepare(`insert into ${vectorTable}(rowid, embedding) values (?, ?)`);
         const writeEmbedding = db.transaction((chunkId, vector) => {
             const embeddingId = getOrCreateEmbeddingRecord(db, { chunkId, embeddingSetId });
+            deleteVector.run(BigInt(embeddingId));
             insertVector.run(BigInt(embeddingId), vectorToFloat32Buffer(vector, options.dimensions));
         });
         for (const batch of chunkArray(pendingChunks, options.batchSize)) {

package/dist/indexing/hybridSearch.js

@@ -65,3 +65,12 @@ export function searchHybrid(options) {
     });
     return mergeHybridResults(semanticResults, keywordResults, options.maxResults);
 }
+export function searchKeywordOnly(options) {
+    const keywordResults = searchByKeyword({
+        dbPath: options.dbPath,
+        query: options.query,
+        maxResults: Math.max(options.maxResults * 2, options.maxResults),
+        maxSnippetChars: options.maxSnippetChars,
+    });
+    return mergeHybridResults([], keywordResults, options.maxResults);
+}

package/dist/tools/registerTools.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { buildContextPack } from "../indexing/contextPack.js";
 import { reindexDryRun } from "../indexing/dryRun.js";
 import { indexMissingEmbeddings } from "../indexing/embeddingWriter.js";
-import { searchHybrid } from "../indexing/hybridSearch.js";
+import { searchHybrid, searchKeywordOnly } from "../indexing/hybridSearch.js";
 import { readDetailedIndexStatus, readIndexFreshness, recommendedNextActions } from "../indexing/indexStatus.js";
 import { persistentReindexMetadata } from "../indexing/indexWriter.js";
 import { readRelatedFileGraph, readRelatedFiles } from "../indexing/relatedFiles.js";
@@ -35,6 +35,37 @@ function searchIndexedChunks(options) {
             maxSnippetChars: options.maxSnippetChars,
         });
 }
+function searchKeywordOnlyChunks(options) {
+    return searchKeywordOnly({
+        dbPath: options.dbPath,
+        query: options.query,
+        maxResults: options.maxResults,
+        maxSnippetChars: options.maxSnippetChars,
+    });
+}
+function embeddingFailureDetails(error) {
+    const geminiError = error instanceof GeminiEmbeddingError ? error : undefined;
+    return {
+        type: error instanceof Error ? error.name : "UnknownError",
+        message: error instanceof Error ? error.message : String(error),
+        httpStatus: geminiError?.status,
+        retryable: geminiError?.retryable ?? false,
+        bodySnippet: geminiError?.bodySnippet,
+    };
+}
+function embeddingUnavailablePayload(error) {
+    return {
+        status: "embedding_unavailable",
+        fallbackAvailable: "Use mode=hybrid to allow keyword-only fallback, or use rg/direct file reads for exact strings and known paths.",
+        error: embeddingFailureDetails(error),
+        recommendedNextActions: [
+            "Run gemini_embedding_probe with a short test string.",
+            "Verify GEMINI_API_KEY, GEMINI_BASE_URL, GEMINI_AUTH_MODE, and GEMINI_OUTPUT_DIMENSIONALITY.",
+            "Use repo_context_pack with mode=hybrid for keyword-only degraded results while embeddings are unavailable.",
+            "Use rg/direct file reads for exact strings, known paths, or small targeted checks.",
+        ],
+    };
+}
 function buildGeminiDiagnostics(config, expectedDimensions) {
     const diagnostics = {
         baseUrl: config.baseUrl,
@@ -223,20 +254,50 @@ export function registerTools(server, config) {
                 message: "Run repo_reindex with dry_run=false and index_embeddings=true before semantic search.",
             });
         }
-        const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
         const dimensions = expectedDimensions;
-        if (queryEmbedding.dimensions !== dimensions) {
-            throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+        let effectiveMode = mode;
+        let fallback;
+        let rawResults;
+        try {
+            const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
+            if (queryEmbedding.dimensions !== dimensions) {
+                throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+            }
+            rawResults = searchIndexedChunks({
+                dbPath,
+                query,
+                dimensions,
+                queryVector: queryEmbedding.vector,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+                mode,
+            });
+        }
+        catch (error) {
+            if (mode === "semantic") {
+                return asJsonText({
+                    query,
+                    projectPath,
+                    dbPath,
+                    dimensions,
+                    mode,
+                    ...embeddingUnavailablePayload(error),
+                });
+            }
+            effectiveMode = "keyword";
+            fallback = {
+                reason: "embedding_unavailable",
+                fromMode: mode,
+                toMode: "keyword",
+                error: embeddingFailureDetails(error),
+            };
+            rawResults = searchKeywordOnlyChunks({
+                dbPath,
+                query,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+            });
         }
-        const rawResults = searchIndexedChunks({
-            dbPath,
-            query,
-            dimensions,
-            queryVector: queryEmbedding.vector,
-            maxResults: max_results,
-            maxSnippetChars: max_snippet_chars,
-            mode,
-        });
         const formatted = formatSearchResults(query, rawResults, { maxContextChars: max_context_chars });
         return asJsonText({
             query,
@@ -244,6 +305,8 @@ export function registerTools(server, config) {
             dbPath,
             dimensions,
             mode,
+            effectiveMode,
+            fallback,
             results: formatted.results,
             context: formatted.summary,
             resultCount: rawResults.length,
@@ -308,20 +371,50 @@ export function registerTools(server, config) {
                 message: "Run repo_reindex with dry_run=false and index_embeddings=true before building a context pack.",
             });
         }
-        const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
         const dimensions = expectedDimensions;
-        if (queryEmbedding.dimensions !== dimensions) {
-            throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+        let effectiveMode = mode;
+        let fallback;
+        let rawResults;
+        try {
+            const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
+            if (queryEmbedding.dimensions !== dimensions) {
+                throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+            }
+            rawResults = searchIndexedChunks({
+                dbPath,
+                query,
+                dimensions,
+                queryVector: queryEmbedding.vector,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+                mode,
+            });
+        }
+        catch (error) {
+            if (mode === "semantic") {
+                return asJsonText({
+                    query,
+                    projectPath,
+                    dbPath,
+                    dimensions,
+                    mode,
+                    ...embeddingUnavailablePayload(error),
+                });
+            }
+            effectiveMode = "keyword";
+            fallback = {
+                reason: "embedding_unavailable",
+                fromMode: mode,
+                toMode: "keyword",
+                error: embeddingFailureDetails(error),
+            };
+            rawResults = searchKeywordOnlyChunks({
+                dbPath,
+                query,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+            });
         }
-        const rawResults = searchIndexedChunks({
-            dbPath,
-            query,
-            dimensions,
-            queryVector: queryEmbedding.vector,
-            maxResults: max_results,
-            maxSnippetChars: max_snippet_chars,
-            mode,
-        });
         const relatedPaths = Array.from(new Set(rawResults.map((result) => result.path))).slice(0, Math.min(max_seed_files, max_related_files));
         const relatedFiles = readRelatedFileGraph({
             dbPath,
@@ -355,6 +448,8 @@ export function registerTools(server, config) {
             dbPath,
             dimensions,
             mode,
+            effectiveMode,
+            fallback,
             relatedDepth: related_depth,
             relatedSeedCount: relatedPaths.length,
             includeRelatedSnippets: include_related_snippets,

package/docs/codex-integration.md

@@ -42,22 +42,23 @@ Codex's official MCP configuration model is platform-neutral: a stdio server has
 
 - Native Windows: use Windows `node.exe` and npm's `npx-cli.js`, or the short binary command only when Codex can reliably see the npm global binary on PATH.
 - WSL/Linux/macOS: use `npx -y scythe-context-mcp` or `node dist/index.js` from a build produced in that same environment.
-- Windows Codex App with WSL workspaces: use Windows `node.exe` and Windows npm package dependencies, but pass the current WSL workspace through `PWD` and `WSLENV`. Use `SCYTHE_CONTEXT_DEFAULT_PROJECT` only when intentionally pinning one fixed default project.
+- Windows Codex App with WSL workspaces: prefer Windows `wsl.exe` as a wrapper that starts WSL Node and WSL npm package dependencies. This keeps the repo-local SQLite index on the WSL filesystem. Use `SCYTHE_CONTEXT_DEFAULT_PROJECT` only when intentionally pinning one fixed default project.
 
 Do not mix a Node runtime from one OS with `node_modules` installed by another OS. This matters because Scythe Context depends on native SQLite modules.
 
 ### Windows App with WSL workspaces
 
-When Codex App runs a WSL project but MCP servers need to use Windows Node, prefer launching Scythe Context through Windows `node.exe` and npm's `npx-cli.js`:
+When Codex App runs a WSL project, prefer launching Scythe Context through Windows `wsl.exe` and a WSL-installed `scythe-context-mcp` binary:
 
-- Current Codex App on Windows may not reliably start WSL-side stdio MCP servers while using WSL agent mode. If MCP tools are missing, handshakes time out, or config paths cross Windows/WSL boundaries, use the Windows Node workaround.
-- Use `command = "/mnt/c/.../node.exe"` with the Windows npm `npx-cli.js` path as the first arg.
-- Keep `cwd` on a Windows-accessible directory such as `/mnt/c/Users/you`; do not use a WSL repo UNC path as `cwd` because npm/npx may invoke CMD and CMD does not support UNC current directories.
-- Forward `PWD` with `PWD/p` in `WSLENV` so WSL converts the current workspace to a UNC path for the Windows process.
-- Include provider variables in `WSLENV` with `/w` only when those values exist in WSL and must be forwarded to Windows Node.
+- Current Codex App on Windows may not reliably start WSL-side stdio MCP servers directly while using WSL agent mode. If MCP tools are missing, handshakes time out, or config paths cross Windows/WSL boundaries, use `wsl.exe` as a wrapper.
+- Install the package inside WSL, then point the wrapper command at the WSL global binary, for example `/home/you/.nvm/current/bin/scythe-context-mcp`.
+- Keep the WSL Node path at the front of `PATH` inside the wrapper command. This avoids accidentally resolving a Windows npm global shim from the inherited Windows PATH.
+- Do not pin `cwd` in global config. Let Codex's current workspace and `PWD` decide the target repo.
+- Use `WSLENV = "PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY"` when config env variables must survive the WSL -> Windows `wsl.exe` -> WSL round trip.
+- Do not use Windows Node to directly read or write `.scythe-context/index.sqlite` inside a WSL repo. In live testing this can fail with `database is locked` across the UNC / WSL filesystem boundary.
 - Do not point Windows `node.exe` at a WSL checkout's `dist/index.js` unless dependencies were installed by Windows npm in that checkout.
 
-The reason is native dependency compatibility. `better-sqlite3` and `sqlite-vec` load platform-specific binaries. Windows Node should load Windows-installed package dependencies, while WSL Node should load WSL-installed package dependencies.
+The reason is both filesystem and native dependency compatibility. `better-sqlite3` and `sqlite-vec` load platform-specific binaries, and SQLite locking is more predictable when the Node process and index database live in the same OS filesystem.
 
 ### AGENTS.md
 
@@ -90,7 +91,7 @@ Recommended config should expose all tools by default during development, but `e
 - Valid Codex TOML examples using `[mcp_servers.scythe_context.env]`.
 - Secret-safe config examples using `env_vars` for `GEMINI_API_KEY`.
 - `cwd` in MCP config so relative `.env` loading is predictable.
-- Windows App + WSL setup guidance using Windows `node.exe`, npm `npx-cli.js`, `PWD`, and `WSLENV`.
+- Windows App + WSL setup guidance using Windows `wsl.exe`, WSL Node, npm package dependencies installed in WSL, `PWD`, and `WSLENV`.
 - `startup_timeout_sec` and `tool_timeout_sec` tuned above defaults.
 - Bounded context output for primary and related snippets.
 - Explicit opt-in embedding and opt-in related snippet packing.
@@ -114,12 +115,13 @@ Recommended config should expose all tools by default during development, but `e
 
 ### Windows App starts but WSL repo indexing fails
 
-1. Prefer the npm package path through Windows `node.exe` plus npm `npx-cli.js`.
-2. Keep `cwd` on `/mnt/c/...`, not the WSL repo.
-3. Forward the current workspace with `env_vars = ["PWD", ...]` and `WSLENV = "PWD/p:..."`.
-4. Forward provider environment variables with `WSLENV` only when they exist in WSL but the MCP server runs through Windows Node.
-5. Avoid mixing Windows Node with Linux-installed `node_modules`.
-6. Run the same Windows Node + `npx-cli.js` command from a WSL shell with `cwd` under `/mnt/c/Users/...` to verify the launch path before configuring Codex.
+1. Prefer the `wsl.exe` wrapper that starts WSL Node and a WSL-installed `scythe-context-mcp` binary.
+2. Confirm WSL has its own install: `npm install -g scythe-context-mcp`, then `command -v scythe-context-mcp`.
+3. Keep WSL Node's bin directory before Windows paths in the wrapper command's `PATH`.
+4. Do not set global `cwd` or `SCYTHE_CONTEXT_DEFAULT_PROJECT` unless you intentionally want one fixed repo.
+5. Use `WSLENV` without suffixes for the wrapper mode, for example `PWD:GEMINI_API_KEY:GEMINI_BASE_URL:GEMINI_MODEL:GEMINI_AUTH_MODE:GEMINI_OUTPUT_DIMENSIONALITY`.
+6. If you see `invalid ELF header`, the process probably loaded a Windows npm package or shim from WSL; fix `PATH` or reinstall inside WSL.
+7. If you see `database is locked` while using Windows Node against a WSL repo, switch to the `wsl.exe` wrapper so SQLite is opened by WSL Node on the WSL filesystem.
 
 ### Tool starts but embedding fails
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scythe-context-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Local MCP context engine for Codex with Gemini Embedding 2 support.",
   "type": "module",
   "license": "Apache-2.0",