scythe-context-mcp 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning before npm publication where practical.
 
+## [Unreleased]
+
+## [0.1.2] - 2026-06-13
+
+### Fixed
+
+- Ensure the npm bin entrypoint is executable so `npx -y scythe-context-mcp` works on Unix-like environments.
+
+## [0.1.1] - 2026-06-13
+
+### Added
+
+- CLI smoke-test flags: `--help` and `--version`.
+- npm and GitHub package metadata for homepage and issue links.
+- Windows Codex App + WSL workspace setup guidance using Windows `npx.cmd`.
+- CI coverage for CLI smoke tests.
+- `PWD` fallback for default project detection, reducing the need for fixed per-repo MCP configuration.
+- README clarification for WSL `PWD/p` forwarding versus direct Gemini proxy configuration.
+
 ## [0.1.0] - 2026-06-13
 
 ### Added

package/README.en.md

@@ -1,6 +1,7 @@
 # Scythe Context MCP
 
 [![CI](https://github.com/Lianye-Scythe/scythe-context-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Lianye-Scythe/scythe-context-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/scythe-context-mcp.svg)](https://www.npmjs.com/package/scythe-context-mcp)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 [![Node.js >=24.11](https://img.shields.io/badge/Node.js-%3E%3D24.11-339933.svg)](package.json)
 
@@ -8,47 +9,28 @@
 
 Scythe Context MCP is a local code-context engine for Codex App / Codex CLI. It builds a SQLite/sqlite-vec index inside the repo and combines semantic search, keyword search, symbol/dependency metadata, and context packing so Codex can retrieve actionable files, line ranges, snippets, and related paths faster.
 
-## Why Use It
+## Highlights
 
-- **Local-first**: metadata, FTS, and vector indexes live under `.scythe-context/`.
-- **Hybrid retrieval**: combines Gemini embeddings, SQLite FTS5, path boosts, and symbol-aware ranking instead of relying on one retrieval path.
-- **Codex-oriented output**: returns line ranges, snippets, match reasons, grep keywords, related files, and suggested paths.
-- **Bring your own provider**: supports the official Gemini API and third-party Gemini-compatible v1beta proxies.
-- **Diagnosable**: includes provider probe, index freshness, embedding coverage, and actionable remediation hints.
+- Local-first: metadata, FTS, and vector indexes live under `.scythe-context/`.
+- Hybrid retrieval: combines Gemini embeddings, SQLite FTS5, path boosts, and symbol-aware ranking instead of relying on one retrieval path.
+- Codex-oriented output: returns line ranges, snippets, match reasons, grep keywords, related files, and suggested paths.
+- Gemini-compatible: supports the official Gemini API and third-party v1beta proxies.
+- Diagnosable: includes provider probe, index freshness, embedding coverage, and actionable remediation hints.
 
 Privacy note: query or chunk text is sent to the configured Gemini-compatible endpoint only when embedding features are used. Treat third-party proxies as services that can see that text.
 
-## Feature Status
-
-Implemented:
-
-- repo scanning, binary/large-file skipping, and chunking
-- SQLite metadata, SQLite FTS5, and sqlite-vec vector indexes
-- Gemini Embedding 2 provider and batch fallback
-- semantic / keyword / hybrid search
-- lightweight symbol/dependency graph
-- related-file lookup and bounded multi-hop traversal
-- `repo_context_pack` context budgeting and related snippet packing
-- provider diagnostics and index freshness diagnostics
-
-Next:
-
-- provider capability cache
-- fuller install/native dependency doctor
-- keyword-only fallback when embeddings fail
-- tree-sitter symbol extraction if needed
-
-## Installation
+## Quick Start
 
-### From npm
-
-Install the CLI globally from npm:
+Codex MCP config can use `npx -y scythe-context-mcp` directly; a global install is not required. Global installation is mostly useful for checking that the CLI runs, or for using the short command form in Codex config.
 
 ```bash
 npm install -g scythe-context-mcp
+scythe-context-mcp --version
 ```
 
-### From source
+Runtime target: Node.js 24 LTS. Node 26 may work, but it is not the baseline until it enters LTS.
+
+Run from source:
 
 ```bash
 git clone https://github.com/Lianye-Scythe/scythe-context-mcp.git
@@ -58,72 +40,162 @@ cp .env.example .env
 npm run build
 ```
 
-Runtime target: Node.js 24 LTS. Node 26 may work, but it is not the baseline until it enters LTS.
-
 The old project name `repo-beacon-mcp` has been renamed to `scythe-context-mcp`. Legacy `REPO_BEACON_*` environment variables are still accepted as fallback, but new setups should use `SCYTHE_CONTEXT_*`.
 
 ## Codex Setup
 
-### npm binary
+Codex MCP configuration uses fields such as `command`, `args`, `cwd`, `env`, and `env_vars`; see the official [Model Context Protocol](https://developers.openai.com/codex/mcp) and [Configuration Reference](https://developers.openai.com/codex/config-reference) docs.
 
-If installed globally from npm:
+### Choose The Runtime
+
+| Scenario | Recommendation |
+| --- | --- |
+| 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`. |
+
+### Native Windows
+
+Use `where node` and `npm root -g` to confirm your own Windows Node/npm paths first; the example below uses an nvm4w installation path.
+
+Minimum config:
 
 ```toml
 [mcp_servers.scythe_context]
-command = "scythe-context-mcp"
-enabled = true
-required = false
-startup_timeout_sec = 20
-tool_timeout_sec = 120
+command = 'C:\nvm4w\nodejs\node.exe'
+args = ['C:\nvm4w\nodejs\node_modules\npm\bin\npx-cli.js', '-y', 'scythe-context-mcp']
 env_vars = ["GEMINI_API_KEY"]
-enabled_tools = [
-  "repo_index_status",
-  "repo_reindex",
-  "repo_context_pack",
-  "repo_semantic_search",
-  "repo_related_files",
-  "gemini_embedding_probe"
-]
+```
 
-[mcp_servers.scythe_context.env]
-GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+If `scythe-context-mcp` is installed globally and Codex can see it on PATH, it can be shorter:
+
+```toml
+[mcp_servers.scythe_context]
+command = "scythe-context-mcp"
+env_vars = ["GEMINI_API_KEY"]
 ```
 
-### Local checkout
+### WSL/Linux/macOS
 
-If running from source:
+When Codex and the MCP server both run in the same Unix-like environment, the minimum config is:
+
+```toml
+[mcp_servers.scythe_context]
+command = "npx"
+args = ["-y", "scythe-context-mcp"]
+env_vars = ["GEMINI_API_KEY"]
+```
+
+When running from source:
 
 ```toml
 [mcp_servers.scythe_context]
 command = "node"
 args = ["/path/to/scythe-context-mcp/dist/index.js"]
-cwd = "/path/to/scythe-context-mcp"
-enabled = true
-required = false
-startup_timeout_sec = 20
-tool_timeout_sec = 120
 env_vars = ["GEMINI_API_KEY"]
+```
+
+Here `args` points to the built Scythe Context MCP entrypoint; do not pin `cwd` to one repo in global config. Scythe prefers a tool call's `project_path`, then the workspace `PWD` / process `cwd` used when Codex starts the MCP server. Set `cwd` or `SCYTHE_CONTEXT_DEFAULT_PROJECT` only in project-scoped `.codex/config.toml`, or when you intentionally want to pin one repo.
+
+### 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.
+
+Minimum config:
 
+```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"
+```
+
+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`:
+
+```toml
 [mcp_servers.scythe_context.env]
+WSLENV = "PWD/p"
+GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
+GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
-### Third-party v1beta proxy
+### 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:
+
+```toml
+[mcp_servers.scythe_context]
+startup_timeout_sec = 40
+tool_timeout_sec = 120
+enabled_tools = [
+  "repo_index_status",
+  "repo_reindex",
+  "repo_context_pack",
+  "repo_semantic_search",
+  "repo_related_files",
+  "gemini_embedding_probe"
+]
+```
+
+`enabled = true` and `required = false` are usually the default behavior and do not need to be written explicitly.
+
+If you really want to pin one default project, set `SCYTHE_CONTEXT_DEFAULT_PROJECT` under `[mcp_servers.scythe_context.env]`. Normal multi-repo usage should not need this; Scythe prefers a tool call's `project_path`, then `PWD`, then the MCP process `cwd`.
+
+### Gemini / v1beta proxy
+
+If URL/model/auth are not set, Scythe uses the official Gemini-compatible defaults:
+
+- `GEMINI_BASE_URL`: `https://generativelanguage.googleapis.com/v1beta`
+- `GEMINI_MODEL`: `gemini-embedding-2`
+- `GEMINI_AUTH_MODE`: `x-goog-api-key`
+- `GEMINI_OUTPUT_DIMENSIONALITY`: `1536`
+
+Official Gemini users usually only need to provide `GEMINI_API_KEY`. Third-party proxies or custom models can override these non-secret settings:
+
+For model names and REST endpoint behavior, see Google's official [Gemini embeddings docs](https://ai.google.dev/gemini-api/docs/embeddings).
 
 ```toml
 [mcp_servers.scythe_context.env]
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+Set `GEMINI_API_KEY` in the environment that starts Codex, or in the system environment, and forward it with `env_vars = ["GEMINI_API_KEY"]`. Do not write the key into synced or committed config files except for local throwaway testing.
+
 Supported auth modes:
 
 - `x-goog-api-key`
 - `bearer`
 - `query`
 
-Set `GEMINI_API_KEY` in the shell or system environment before starting Codex. Do not write API keys into synced or committed config files.
+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:
+
+```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"
+GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
+GEMINI_AUTH_MODE = "bearer"
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
 
 ## Typical Workflow
 
@@ -168,6 +240,12 @@ Set `GEMINI_API_KEY` in the shell or system environment before starting Codex. D
 | `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. |
 
+## 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.
+
+Next: provider capability cache, install/native dependency doctor, keyword-only fallback when embeddings fail, and tree-sitter symbol extraction if needed.
+
 ## Privacy and Local Files
 
 - `.scythe-context/`: default index directory, not committed.

package/README.md

@@ -1,6 +1,7 @@
 # Scythe Context MCP
 
 [![CI](https://github.com/Lianye-Scythe/scythe-context-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Lianye-Scythe/scythe-context-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/scythe-context-mcp.svg)](https://www.npmjs.com/package/scythe-context-mcp)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 [![Node.js >=24.11](https://img.shields.io/badge/Node.js-%3E%3D24.11-339933.svg)](package.json)
 
@@ -8,47 +9,28 @@
 
 Scythe Context MCP 是給 Codex App / Codex CLI 使用的本機程式碼上下文引擎。它在 repo 內建立 SQLite/sqlite-vec 索引，結合語義搜尋、關鍵字搜尋、符號/依賴關係與 context packing，讓 Codex 更快拿到可操作的檔案、行號、片段與相關路徑。
 
-## 為什麼用它
+## 核心特性
 
-- **本機優先**：metadata、FTS 與向量索引都存在 repo 內的 `.scythe-context/`。
-- **混合搜尋**：結合 Gemini embeddings、SQLite FTS5、path/symbol ranking，避免只靠單一召回方式。
-- **Codex 友善輸出**：回傳 line ranges、snippets、match reasons、grep keywords、related files 與 suggested paths。
-- **可接自己的 provider**：支援官方 Gemini API，也支援第三方 Gemini-compatible v1beta proxy。
-- **可診斷**：內建 provider probe、index freshness、embedding coverage 與可修復建議。
+- 本機優先：metadata、FTS 與向量索引都存在 repo 內的 `.scythe-context/`。
+- 混合搜尋：結合 Gemini embeddings、SQLite FTS5、path/symbol ranking，避免只靠單一召回方式。
+- Codex 友善輸出：回傳 line ranges、snippets、match reasons、grep keywords、related files 與 suggested paths。
+- Gemini-compatible：支援官方 Gemini API，也支援第三方 v1beta proxy。
+- 可診斷：內建 provider probe、index freshness、embedding coverage 與可修復建議。
 
 隱私提醒：只有在執行 embedding 相關功能時，query 或 chunk text 才會送到你設定的 Gemini-compatible endpoint。第三方 proxy 應視為可看到這些文字。
 
-## 功能狀態
-
-已完成：
-
-- repo 掃描、binary/large-file skip、chunking
-- SQLite metadata、SQLite FTS5、sqlite-vec 向量索引
-- Gemini Embedding 2 provider 與 batch fallback
-- semantic / keyword / hybrid search
-- 輕量 symbol/dependency graph
-- related-file lookup、bounded multi-hop traversal
-- `repo_context_pack` context budgeting 與 related snippet packing
-- provider diagnostics 與 index freshness diagnostics
-
-下一步：
-
-- provider capability cache
-- 更完整的安裝/原生依賴 doctor
-- embedding 失敗時的 keyword-only fallback
-- 必要時加入 tree-sitter symbol extraction
-
-## 安裝
+## 快速開始
 
-### 從 npm 安裝
-
-使用 npm 安裝全域指令：
+Codex MCP 設定可以直接用 `npx -y scythe-context-mcp`，不一定要先全域安裝。全域安裝主要適合先確認 CLI 可執行，或在 Codex 設定中使用短命令。
 
 ```bash
 npm install -g scythe-context-mcp
+scythe-context-mcp --version
 ```
 
-### 從原始碼安裝
+Runtime 目標是 Node.js 24 LTS。Node 26 可能可用，但在進入 LTS 前不作為主要驗收基準。
+
+從原始碼執行：
 
 ```bash
 git clone https://github.com/Lianye-Scythe/scythe-context-mcp.git
@@ -58,72 +40,162 @@ cp .env.example .env
 npm run build
 ```
 
-Runtime 目標是 Node.js 24 LTS。Node 26 可能可用，但在進入 LTS 前不作為主要驗收基準。
-
 舊專案名 `repo-beacon-mcp` 已改為 `scythe-context-mcp`。舊的 `REPO_BEACON_*` 環境變數仍作為 fallback 相容，但新設定應改用 `SCYTHE_CONTEXT_*`。
 
 ## Codex 設定
 
-### npm binary
+Codex MCP 設定使用 `command`、`args`、`cwd`、`env` 與 `env_vars` 等欄位；可參考官方文件：[Model Context Protocol](https://developers.openai.com/codex/mcp) 與 [Configuration Reference](https://developers.openai.com/codex/config-reference)。
 
-如果已用 npm 全域安裝：
+### 先選執行環境
+
+| 情境 | 建議 |
+| --- | --- |
+| 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。 |
+
+### Native Windows
+
+請先用 `where node` 和 `npm root -g` 確認你自己的 Windows Node/npm 路徑；下面是 nvm4w 安裝位置的範例。
+
+最小設定：
 
 ```toml
 [mcp_servers.scythe_context]
-command = "scythe-context-mcp"
-enabled = true
-required = false
-startup_timeout_sec = 20
-tool_timeout_sec = 120
+command = 'C:\nvm4w\nodejs\node.exe'
+args = ['C:\nvm4w\nodejs\node_modules\npm\bin\npx-cli.js', '-y', 'scythe-context-mcp']
 env_vars = ["GEMINI_API_KEY"]
-enabled_tools = [
-  "repo_index_status",
-  "repo_reindex",
-  "repo_context_pack",
-  "repo_semantic_search",
-  "repo_related_files",
-  "gemini_embedding_probe"
-]
+```
 
-[mcp_servers.scythe_context.env]
-GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+如果 `scythe-context-mcp` 已全域安裝且 Codex 啟動時的 PATH 能找到它，可以更短：
+
+```toml
+[mcp_servers.scythe_context]
+command = "scythe-context-mcp"
+env_vars = ["GEMINI_API_KEY"]
 ```
 
-### 本機 checkout
+### WSL/Linux/macOS
 
-如果從原始碼執行：
+Codex 和 MCP server 都在同一個 Unix-like 環境中執行時，最小設定是：
+
+```toml
+[mcp_servers.scythe_context]
+command = "npx"
+args = ["-y", "scythe-context-mcp"]
+env_vars = ["GEMINI_API_KEY"]
+```
+
+從原始碼執行時：
 
 ```toml
 [mcp_servers.scythe_context]
 command = "node"
 args = ["/path/to/scythe-context-mcp/dist/index.js"]
-cwd = "/path/to/scythe-context-mcp"
-enabled = true
-required = false
-startup_timeout_sec = 20
-tool_timeout_sec = 120
 env_vars = ["GEMINI_API_KEY"]
+```
+
+這裡 `args` 指向 Scythe Context MCP 的 build 入口；全域設定不要把 `cwd` 固定到某個 repo。Scythe 會優先使用工具呼叫的 `project_path`，再使用 Codex 啟動 MCP 時的 workspace `PWD` / process `cwd`。只有在專案 scoped `.codex/config.toml`、或你真的想 pin 某個 repo 時，才需要設定 `cwd` 或 `SCYTHE_CONTEXT_DEFAULT_PROJECT`。
+
+### 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。
+
+最小設定：
 
+```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"
+```
+
+注意：
+
+- `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`：
+
+```toml
 [mcp_servers.scythe_context.env]
+WSLENV = "PWD/p"
+GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
+GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
-### 第三方 v1beta proxy
+### 可選強化設定
+
+以下設定不是最小啟動必需，但在大型 repo、首次 `npx` 下載或想固定工具面時有用：
+
+```toml
+[mcp_servers.scythe_context]
+startup_timeout_sec = 40
+tool_timeout_sec = 120
+enabled_tools = [
+  "repo_index_status",
+  "repo_reindex",
+  "repo_context_pack",
+  "repo_semantic_search",
+  "repo_related_files",
+  "gemini_embedding_probe"
+]
+```
+
+`enabled = true` 和 `required = false` 通常是預設行為，不需要特別寫。
+
+如果你真的想固定某一個預設專案，可以在 `[mcp_servers.scythe_context.env]` 設 `SCYTHE_CONTEXT_DEFAULT_PROJECT`。一般多 repo 使用不需要這樣做；Scythe 會優先使用工具呼叫的 `project_path`，再使用 `PWD`，最後才使用 MCP process 的 `cwd`。
+
+### Gemini / v1beta proxy
+
+如果不填 URL/model/auth，預設會使用官方 Gemini 相容設定：
+
+- `GEMINI_BASE_URL`: `https://generativelanguage.googleapis.com/v1beta`
+- `GEMINI_MODEL`: `gemini-embedding-2`
+- `GEMINI_AUTH_MODE`: `x-goog-api-key`
+- `GEMINI_OUTPUT_DIMENSIONALITY`: `1536`
+
+因此官方 Gemini 使用者通常只需要提供 `GEMINI_API_KEY`。第三方中轉站或自訂模型才需要覆蓋下面這些非秘密設定：
+
+模型與 REST endpoint 可對照 Google 官方 [Gemini embeddings 文件](https://ai.google.dev/gemini-api/docs/embeddings)。
 
 ```toml
 [mcp_servers.scythe_context.env]
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+`GEMINI_API_KEY` 建議放在 Codex 啟動環境或系統環境變數，並用 `env_vars = ["GEMINI_API_KEY"]` 轉發給 MCP server。除非只做本機臨時測試，否則不要把 key 寫進可同步或可提交的 config。
+
 支援的 auth mode：
 
 - `x-goog-api-key`
 - `bearer`
 - `query`
 
-啟動 Codex 前在 shell 或系統環境中設定 `GEMINI_API_KEY`，避免把 key 寫進可同步或可提交的設定檔。
+官方 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`：
+
+```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"
+GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
+GEMINI_AUTH_MODE = "bearer"
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
 
 ## 常用工作流
 
@@ -168,6 +240,12 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | 查看單一檔案的 symbols、imports、importedBy。 |
 | `gemini_embedding_probe` | 測試 Gemini 或 proxy 相容性，回傳 endpoint、latency、錯誤分類與可修復建議。 |
 
+## 功能狀態
+
+已完成：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。
+
+下一步：provider capability cache、安裝/原生依賴 doctor、embedding 失敗時的 keyword-only fallback、必要時加入 tree-sitter symbol extraction。
+
 ## 隱私與本機檔案
 
 - `.scythe-context/`: 預設索引目錄，不提交。

package/README.zh-CN.md

@@ -1,6 +1,7 @@
 # Scythe Context MCP
 
 [![CI](https://github.com/Lianye-Scythe/scythe-context-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Lianye-Scythe/scythe-context-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/scythe-context-mcp.svg)](https://www.npmjs.com/package/scythe-context-mcp)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 [![Node.js >=24.11](https://img.shields.io/badge/Node.js-%3E%3D24.11-339933.svg)](package.json)
 
@@ -8,47 +9,28 @@
 
 Scythe Context MCP 是给 Codex App / Codex CLI 使用的本地代码上下文引擎。它在 repo 内建立 SQLite/sqlite-vec 索引，结合语义搜索、关键字搜索、符号/依赖关系与 context packing，让 Codex 更快拿到可操作的文件、行号、片段与相关路径。
 
-## 为什么用它
+## 核心特性
 
-- **本地优先**：metadata、FTS 与向量索引都存在 repo 内的 `.scythe-context/`。
-- **混合搜索**：结合 Gemini embeddings、SQLite FTS5、path/symbol ranking，避免只靠单一召回方式。
-- **Codex 友好输出**：返回 line ranges、snippets、match reasons、grep keywords、related files 与 suggested paths。
-- **可接自己的 provider**：支持官方 Gemini API，也支持第三方 Gemini-compatible v1beta proxy。
-- **可诊断**：内置 provider probe、index freshness、embedding coverage 与可修复建议。
+- 本地优先：metadata、FTS 与向量索引都存在 repo 内的 `.scythe-context/`。
+- 混合搜索：结合 Gemini embeddings、SQLite FTS5、path/symbol ranking，避免只靠单一召回方式。
+- Codex 友好输出：返回 line ranges、snippets、match reasons、grep keywords、related files 与 suggested paths。
+- Gemini-compatible：支持官方 Gemini API，也支持第三方 v1beta proxy。
+- 可诊断：内置 provider probe、index freshness、embedding coverage 与可修复建议。
 
 隐私提醒：只有在执行 embedding 相关功能时，query 或 chunk text 才会发送到你配置的 Gemini-compatible endpoint。第三方 proxy 应视为可以看到这些文字。
 
-## 功能状态
-
-已完成：
-
-- repo 扫描、binary/large-file skip、chunking
-- SQLite metadata、SQLite FTS5、sqlite-vec 向量索引
-- Gemini Embedding 2 provider 与 batch fallback
-- semantic / keyword / hybrid search
-- 轻量 symbol/dependency graph
-- related-file lookup、bounded multi-hop traversal
-- `repo_context_pack` context budgeting 与 related snippet packing
-- provider diagnostics 与 index freshness diagnostics
-
-下一步：
-
-- provider capability cache
-- 更完整的安装/原生依赖 doctor
-- embedding 失败时的 keyword-only fallback
-- 必要时加入 tree-sitter symbol extraction
-
-## 安装
+## 快速开始
 
-### 从 npm 安装
-
-使用 npm 安装全局命令：
+Codex MCP 配置可以直接用 `npx -y scythe-context-mcp`，不一定要先全局安装。全局安装主要适合先确认 CLI 可执行，或在 Codex 配置中使用短命令。
 
 ```bash
 npm install -g scythe-context-mcp
+scythe-context-mcp --version
 ```
 
-### 从源码安装
+Runtime 目标是 Node.js 24 LTS。Node 26 可能可用，但在进入 LTS 前不作为主要验收基准。
+
+从源码执行：
 
 ```bash
 git clone https://github.com/Lianye-Scythe/scythe-context-mcp.git
@@ -58,72 +40,162 @@ cp .env.example .env
 npm run build
 ```
 
-Runtime 目标是 Node.js 24 LTS。Node 26 可能可用，但在进入 LTS 前不作为主要验收基准。
-
 旧项目名 `repo-beacon-mcp` 已改为 `scythe-context-mcp`。旧的 `REPO_BEACON_*` 环境变量仍作为 fallback 兼容，但新配置应改用 `SCYTHE_CONTEXT_*`。
 
 ## Codex 配置
 
-### npm binary
+Codex MCP 配置使用 `command`、`args`、`cwd`、`env` 与 `env_vars` 等字段；可参考官方文档：[Model Context Protocol](https://developers.openai.com/codex/mcp) 与 [Configuration Reference](https://developers.openai.com/codex/config-reference)。
 
-如果已用 npm 全局安装：
+### 先选运行环境
+
+| 情境 | 建议 |
+| --- | --- |
+| 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。 |
+
+### Native Windows
+
+请先用 `where node` 和 `npm root -g` 确认你自己的 Windows Node/npm 路径；下面是 nvm4w 安装位置的示例。
+
+最小配置：
 
 ```toml
 [mcp_servers.scythe_context]
-command = "scythe-context-mcp"
-enabled = true
-required = false
-startup_timeout_sec = 20
-tool_timeout_sec = 120
+command = 'C:\nvm4w\nodejs\node.exe'
+args = ['C:\nvm4w\nodejs\node_modules\npm\bin\npx-cli.js', '-y', 'scythe-context-mcp']
 env_vars = ["GEMINI_API_KEY"]
-enabled_tools = [
-  "repo_index_status",
-  "repo_reindex",
-  "repo_context_pack",
-  "repo_semantic_search",
-  "repo_related_files",
-  "gemini_embedding_probe"
-]
+```
 
-[mcp_servers.scythe_context.env]
-GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+如果 `scythe-context-mcp` 已全局安装且 Codex 启动时的 PATH 能找到它，可以更短：
+
+```toml
+[mcp_servers.scythe_context]
+command = "scythe-context-mcp"
+env_vars = ["GEMINI_API_KEY"]
 ```
 
-### 本地 checkout
+### WSL/Linux/macOS
 
-如果从源码执行：
+Codex 和 MCP server 都在同一个 Unix-like 环境中运行时，最小配置是：
+
+```toml
+[mcp_servers.scythe_context]
+command = "npx"
+args = ["-y", "scythe-context-mcp"]
+env_vars = ["GEMINI_API_KEY"]
+```
+
+从源码执行时：
 
 ```toml
 [mcp_servers.scythe_context]
 command = "node"
 args = ["/path/to/scythe-context-mcp/dist/index.js"]
-cwd = "/path/to/scythe-context-mcp"
-enabled = true
-required = false
-startup_timeout_sec = 20
-tool_timeout_sec = 120
 env_vars = ["GEMINI_API_KEY"]
+```
+
+这里 `args` 指向 Scythe Context MCP 的 build 入口；全局配置不要把 `cwd` 固定到某个 repo。Scythe 会优先使用工具调用的 `project_path`，再使用 Codex 启动 MCP 时的 workspace `PWD` / process `cwd`。只有在项目 scoped `.codex/config.toml`，或你真的想 pin 某个 repo 时，才需要设置 `cwd` 或 `SCYTHE_CONTEXT_DEFAULT_PROJECT`。
+
+### 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。
+
+最小配置：
 
+```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"
+```
+
+注意：
+
+- `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`：
+
+```toml
 [mcp_servers.scythe_context.env]
+WSLENV = "PWD/p"
+GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
+GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
-### 第三方 v1beta proxy
+### 可选强化配置
+
+以下配置不是最小启动必需，但在大型 repo、首次 `npx` 下载或想固定工具面时有用：
+
+```toml
+[mcp_servers.scythe_context]
+startup_timeout_sec = 40
+tool_timeout_sec = 120
+enabled_tools = [
+  "repo_index_status",
+  "repo_reindex",
+  "repo_context_pack",
+  "repo_semantic_search",
+  "repo_related_files",
+  "gemini_embedding_probe"
+]
+```
+
+`enabled = true` 和 `required = false` 通常是默认行为，不需要特别写。
+
+如果你真的想固定某一个默认项目，可以在 `[mcp_servers.scythe_context.env]` 设置 `SCYTHE_CONTEXT_DEFAULT_PROJECT`。一般多 repo 使用不需要这样做；Scythe 会优先使用工具调用的 `project_path`，再使用 `PWD`，最后才使用 MCP process 的 `cwd`。
+
+### Gemini / v1beta proxy
+
+如果不填 URL/model/auth，默认会使用官方 Gemini 兼容配置：
+
+- `GEMINI_BASE_URL`: `https://generativelanguage.googleapis.com/v1beta`
+- `GEMINI_MODEL`: `gemini-embedding-2`
+- `GEMINI_AUTH_MODE`: `x-goog-api-key`
+- `GEMINI_OUTPUT_DIMENSIONALITY`: `1536`
+
+因此官方 Gemini 用户通常只需要提供 `GEMINI_API_KEY`。第三方中转站或自定义模型才需要覆盖下面这些非秘密配置：
+
+模型与 REST endpoint 可对照 Google 官方 [Gemini embeddings 文档](https://ai.google.dev/gemini-api/docs/embeddings)。
 
 ```toml
 [mcp_servers.scythe_context.env]
 GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
 GEMINI_AUTH_MODE = "bearer"
 GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 ```
 
+`GEMINI_API_KEY` 建议放在 Codex 启动环境或系统环境变量，并用 `env_vars = ["GEMINI_API_KEY"]` 转发给 MCP server。除非只做本机临时测试，否则不要把 key 写进会同步或会提交的 config。
+
 支持的 auth mode：
 
 - `x-goog-api-key`
 - `bearer`
 - `query`
 
-启动 Codex 前在 shell 或系统环境中设置 `GEMINI_API_KEY`，避免把 key 写进会同步或会提交的配置文件。
+官方 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`：
+
+```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"
+GEMINI_BASE_URL = "https://your-proxy.example.com/v1beta"
+GEMINI_MODEL = "gemini-embedding-2"
+GEMINI_AUTH_MODE = "bearer"
+GEMINI_OUTPUT_DIMENSIONALITY = "1536"
+```
 
 ## 常用工作流
 
@@ -168,6 +240,12 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | 查看单一文件的 symbols、imports、importedBy。 |
 | `gemini_embedding_probe` | 测试 Gemini 或 proxy 兼容性，返回 endpoint、latency、错误分类与可修复建议。 |
 
+## 功能状态
+
+已完成：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。
+
+下一步：provider capability cache、安装/原生依赖 doctor、embedding 失败时的 keyword-only fallback、必要时加入 tree-sitter symbol extraction。
+
 ## 隐私与本地文件
 
 - `.scythe-context/`: 默认索引目录，不提交。

package/dist/cli.js

@@ -0,0 +1,35 @@
+export const PACKAGE_VERSION = "0.1.2";
+export function parseCliArgs(args) {
+    if (args.length === 0)
+        return { kind: "serve" };
+    const [first] = args;
+    if (first === "--help" || first === "-h")
+        return { kind: "help" };
+    if (first === "--version" || first === "-v")
+        return { kind: "version" };
+    return { kind: "error", message: `Unknown option: ${first}` };
+}
+export function renderHelp() {
+    return `Scythe Context MCP ${PACKAGE_VERSION}
+
+Local code-context MCP server for Codex App / CLI.
+
+Usage:
+  scythe-context-mcp          Start the MCP stdio server
+  scythe-context-mcp --help   Show this help
+  scythe-context-mcp --version
+
+Common Codex MCP config:
+  [mcp_servers.scythe_context]
+  command = "npx"
+  args = ["-y", "scythe-context-mcp"]
+  env_vars = ["GEMINI_API_KEY"]
+
+Environment:
+  PWD                             Workspace path used when no explicit project is configured
+  SCYTHE_CONTEXT_DEFAULT_PROJECT  Optional fixed default project override
+  GEMINI_API_KEY                  Gemini or Gemini-compatible API key
+  GEMINI_BASE_URL                 Gemini-compatible base URL, default https://generativelanguage.googleapis.com/v1beta
+  GEMINI_OUTPUT_DIMENSIONALITY    Embedding dimensions, default 1536
+`;
+}

package/dist/config.js

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { DEFAULT_INDEXING_LIMITS } from "./indexing/defaults.js";
@@ -32,9 +33,21 @@ function authModeFromEnv(value) {
     }
     throw new Error("GEMINI_AUTH_MODE must be one of: x-goog-api-key, bearer, query");
 }
+function defaultProjectPathFromEnv() {
+    const explicitProject = envValue("SCYTHE_CONTEXT_DEFAULT_PROJECT", "REPO_BEACON_DEFAULT_PROJECT");
+    if (explicitProject)
+        return explicitProject;
+    // Codex App on Windows may launch this server through Windows Node while the
+    // active workspace is in WSL. In that setup, cwd often has to stay on a
+    // Windows directory for npm/npx, while PWD can still carry the workspace path.
+    if (process.env.PWD && fs.existsSync(process.env.PWD)) {
+        return process.env.PWD;
+    }
+    return process.cwd();
+}
 export function loadConfig() {
     return {
-        defaultProjectPath: path.resolve(envValue("SCYTHE_CONTEXT_DEFAULT_PROJECT", "REPO_BEACON_DEFAULT_PROJECT") || process.cwd()),
+        defaultProjectPath: path.resolve(defaultProjectPathFromEnv()),
         indexDirName: envValue("SCYTHE_CONTEXT_INDEX_DIR", "REPO_BEACON_INDEX_DIR") || ".scythe-context",
         indexing: {
             maxFileBytes: numberFromEnvAlias("SCYTHE_CONTEXT_MAX_FILE_BYTES", "REPO_BEACON_MAX_FILE_BYTES", DEFAULT_INDEXING_LIMITS.maxFileBytes) ??

package/dist/index.js

@@ -2,12 +2,27 @@
 import "dotenv/config";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { PACKAGE_VERSION, parseCliArgs, renderHelp } from "./cli.js";
 import { loadConfig } from "./config.js";
 import { registerTools } from "./tools/registerTools.js";
+const cliCommand = parseCliArgs(process.argv.slice(2));
+if (cliCommand.kind === "help") {
+    console.log(renderHelp());
+    process.exit(0);
+}
+if (cliCommand.kind === "version") {
+    console.log(PACKAGE_VERSION);
+    process.exit(0);
+}
+if (cliCommand.kind === "error") {
+    console.error(cliCommand.message);
+    console.error("Run `scythe-context-mcp --help` for usage.");
+    process.exit(1);
+}
 const config = loadConfig();
 const server = new McpServer({
     name: "scythe-context-mcp",
-    version: "0.1.0",
+    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.",
 });

package/docs/codex-integration.md

@@ -36,6 +36,29 @@ Scythe Context's server instructions now put the key workflow first:
 
 Codex CLI and the IDE extension share MCP configuration through `config.toml`. The Codex app also exposes plugins/MCP-related extension points, but local setup behavior can vary by App settings and installed plugins. For direct reproducible setup, document CLI/IDE `config.toml` first and keep App usage phrased as "Codex local MCP compatible" rather than assuming every App install auto-loads a project config.
 
+### Platform setup paths
+
+Codex's official MCP configuration model is platform-neutral: a stdio server has `command`, optional `args`, optional `cwd`, `env`, and `env_vars`. The practical launch command should still match the OS that runs Node:
+
+- 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.
+
+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`:
+
+- 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.
+- 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.
+
 ### AGENTS.md
 
 Codex reads `AGENTS.md` before work and layers global plus project guidance. Scythe Context's `AGENTS.md` is intentionally short enough to fit comfortably under the default project instruction limit and focuses on:
@@ -67,6 +90,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`.
 - `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.
@@ -88,6 +112,15 @@ Recommended config should expose all tools by default during development, but `e
 4. Check that `command`, `args`, and `cwd` point to the built repo and that `npm run build` has produced `dist/index.js`.
 5. If startup is slow on WSL or a cold Node install, raise `startup_timeout_sec`.
 
+### 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.
+
 ### Tool starts but embedding fails
 
 1. Run `gemini_embedding_probe` with a short test string.

package/docs/gemini-compatibility.md

@@ -136,13 +136,14 @@ POST /v1beta/models/gemini-embedding-2:batchEmbedContents
 
 ## Codex MCP 設定範例
 
+以下範例只示範 Gemini provider 參數。全域 MCP config 不要把 `cwd` 固定到某個 repo；只有 project-scoped `.codex/config.toml` 或刻意 pin 單一 repo 時才需要設定 `cwd` 或 `SCYTHE_CONTEXT_DEFAULT_PROJECT`。
+
 官方 Gemini：
 
 ```toml
 [mcp_servers.scythe_context]
 command = "node"
 args = ["/path/to/scythe-context-mcp/dist/index.js"]
-cwd = "/path/to/scythe-context-mcp"
 env_vars = ["GEMINI_API_KEY"]
 
 [mcp_servers.scythe_context.env]
@@ -157,7 +158,6 @@ Bearer 中轉站：
 [mcp_servers.scythe_context]
 command = "node"
 args = ["/path/to/scythe-context-mcp/dist/index.js"]
-cwd = "/path/to/scythe-context-mcp"
 env_vars = ["GEMINI_API_KEY"]
 
 [mcp_servers.scythe_context.env]
@@ -172,7 +172,6 @@ Query key 中轉站：
 [mcp_servers.scythe_context]
 command = "node"
 args = ["/path/to/scythe-context-mcp/dist/index.js"]
-cwd = "/path/to/scythe-context-mcp"
 env_vars = ["GEMINI_API_KEY"]
 
 [mcp_servers.scythe_context.env]

package/package.json

@@ -1,9 +1,13 @@
 {
   "name": "scythe-context-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Local MCP context engine for Codex with Gemini Embedding 2 support.",
   "type": "module",
   "license": "Apache-2.0",
+  "homepage": "https://github.com/Lianye-Scythe/scythe-context-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Lianye-Scythe/scythe-context-mcp/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Lianye-Scythe/scythe-context-mcp.git"
@@ -30,11 +34,13 @@
     ".env.example"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && node scripts/bin-mode.mjs ensure",
     "dev": "tsx src/index.ts",
     "prepack": "npm run build",
+    "smoke": "node dist/index.js --version && node dist/index.js --help",
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "verify": "npm test && npm run build && node scripts/bin-mode.mjs check && npm run smoke && npm audit --omit=dev && npm pack --dry-run"
   },
   "engines": {
     "node": ">=24.11.0 <27"