deepseek-web-retrieval 0.6.0 → 0.8.0

package/docs/adr/0002-shared-config-base-layer.md

@@ -0,0 +1,43 @@
+# Share one config base layer across hosts
+
+The option pipeline was single-sourced, but the channels feeding it were per
+host: `DEEPSEEK_*` shell variables on Pi, only `ctx.options` on OpenCode, and
+on Codex only the names the installer's `env_vars` entry forwards — just
+`DEEPSEEK_API_KEY`, so every other knob set in the shell silently never
+reached the server. One intent ("20 results, block pinterest.com") took up to
+three configuration acts in two vocabularies. We decided that a shared config
+file becomes the base layer under every existing channel, with the precedence
+`built-in defaults < shared config file < DEEPSEEK_* environment < host-native
+config`, a three-class parameter taxonomy that isolates host integration in
+the host-native layer and rejects it from the file, and no API key in the
+file — auth keeps its existing channels.
+
+## Considered Options
+
+- **Unify on the file alone** (retire the environment and host-option
+  vocabularies so there is one configuration act). But host integration —
+  `searchEnabled`/`fetchEnabled`, `setDefaultWebsearch`,
+  `fetchOverrideWebfetch`, `fetchRegisterTool`, `apiKeySource` — describes the
+  host's tool landscape, not the user↔DeepSeek relationship, so the host layer
+  must keep owning it, and retiring `DEEPSEEK_*` would break every existing
+  shell profile.
+- **Keep the per-host channels as the only surface** (previous status quo).
+  The Codex `env_vars` trap stays — knobs set in the shell reach the server
+  only by hand-editing `config.toml` — and the same knob keeps two
+  vocabularies across hosts.
+
+## Consequences
+
+One file — `$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json`, default
+`~/.config/deepseek-web-retrieval/config.json`, camelCase keys — configures
+every host, and host layers keep winning: installer-written intent and
+explicit per-host overrides always outrank the base, bounding the blast
+radius of a bad shared value. Unknown keys and host-integration keys in the
+file draw a one-line stderr warning and are otherwise ignored. Because a bad
+shared value now fails everywhere at once, every adapter prints a
+deviations-from-defaults summary of its effective configuration.
+
+The installer's Codex `env_vars` entry forwards every `DEEPSEEK_*` name, so
+environment overrides work on Codex without hand-editing `config.toml`.
+Design detail (per-adapter composition, validation, visibility, rollout)
+lives in the [layering design note](../design/config-layering-design.md).

package/docs/agents/claude-code.md

@@ -0,0 +1,273 @@
+# Claude Code
+
+Claude Code adapter for [DeepSeek Web Retrieval](../../README.md).
+
+Integration mechanism: MCP server over stdio, registered in Claude Code's own MCP config
+files — `.mcp.json` at the project root (project scope) or the top-level `mcpServers` key
+of `~/.claude.json` (user scope, where `claude mcp add --scope user` writes). Claude Code
+negotiates MCP revision `2026-07-28`; the server accepts clients from `2024-11-05` through
+`2026-07-28`, so the same build works for other MCP hosts (see
+[the compatibility research](../research/mcp-compatibility.md)).
+
+When registered, it adds:
+
+- A `deepseek_web_search` tool backed by DeepSeek Search
+- A `deepseek_fetch` tool backed by DeepSeek Fetch
+
+The tools appear in Claude Code as `mcp__deepseek__deepseek_web_search` and
+`mcp__deepseek__deepseek_fetch`. Claude Code's built-in `WebSearch` and `WebFetch` tools
+are not replaced; see [Control tiers](#control-tiers) for routing them away.
+
+For shared search/fetch limits, retries, and privacy behavior, see
+[General behavior](../../README.md#general-behavior).
+For configuration layers, the full knob mapping, and defaults, see the
+[configuration guide](../configuration.md).
+
+## Requirements
+
+- Claude Code at the tested version in [`docs/hosts.jsonc`](../hosts.jsonc); init reports
+  version drift, and newer versions may require rechecking routing behavior
+- Node.js 20 or newer (`npx` runs the server)
+- A DeepSeek account with access to `/v1/tools/search` and `/v1/tools/fetch`
+- A funded DeepSeek account; Search and Fetch are billed per successful request
+- `DEEPSEEK_API_KEY` set in the shell that launches Claude Code
+
+## Install
+
+The quickest option is the installer CLI:
+
+```bash
+npx deepseek-web-retrieval init --host claude-code --scope project \
+  --search <tier> --fetch <tier>
+```
+
+It prints the full plan — every file, old value → new value, and notes about existing MCP
+servers — and writes nothing until you pass `--apply`. Add `--pin` to register the exact
+version of the CLI you are running instead of the always-latest package name. `uninstall`
+removes recorded additions and restores snapshotted values that have not since been edited.
+`--scope project` registers the server in `./.mcp.json` (shareable via VCS) and writes tier
+artifacts to `./.claude/settings.json` and `./CLAUDE.md`; `--scope global` uses
+`~/.claude.json`, `~/.claude/settings.json`, and `~/.claude/CLAUDE.md` instead — the two
+scopes use disjoint files, so both can coexist. An `off` capability is written as the
+tool's full id in the `permissions.deny` array — Claude Code's own mechanism, which removes
+the tool from the model's context while the server keeps running — merging with any entries
+you put there yourself. When `claude` is on PATH, `init` also probes `claude --version` and
+adds a plan note when the installed release differs from the tested lock (see
+[hosts.jsonc](../hosts.jsonc)) — version-anchored behavior such as the deny rules may have
+drifted between the two.
+
+For an existing installer-managed setup, follow the
+[upgrade instructions](../integration.md#upgrading-existing-installs) from the original
+project directory and scope.
+
+### Manual install
+
+Add the server to `.mcp.json` at the project root:
+
+```json
+{
+  "mcpServers": {
+    "deepseek": {
+      "command": "npx",
+      "args": ["-y", "deepseek-web-retrieval"],
+      "env": { "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}" }
+    }
+  }
+}
+```
+
+> [!NOTE]
+> `"${DEEPSEEK_API_KEY}"` is Claude Code's own `${VAR}` expansion: the key is read from
+> the environment that launches Claude Code and never sits in the file. A literal value
+> works too if you prefer it in the file. For a user-scope install, the same entry goes
+> under the top-level `mcpServers` key of `~/.claude.json`, or use
+> `claude mcp add --scope user --env 'DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}' deepseek -- npx -y deepseek-web-retrieval`.
+
+Claude Code asks once per project whether to use servers from `.mcp.json`; approve the
+`deepseek` server when prompted (or via the `/mcp` menu), or its tools will not load in
+that project.
+
+To disable one capability, add the tool's full id to `permissions.deny` in
+`.claude/settings.json` — Claude Code removes the tool from the model's context while the
+server keeps running:
+
+```json
+{
+  "permissions": {
+    "deny": ["mcp__deepseek__deepseek_web_search"]
+  }
+}
+```
+
+The ids match the tool names verbatim (`mcp__deepseek__deepseek_web_search`,
+`mcp__deepseek__deepseek_fetch`). The server also honors
+`DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH` in the server's `env` block if you prefer
+switching the tools off at the source; the installer uses `permissions.deny`.
+
+### Local checkout
+
+```bash
+git clone https://github.com/gwokhou/deepseek-web-retrieval.git
+cd deepseek-web-retrieval && bun install && bun run build
+```
+
+```json
+{
+  "mcpServers": {
+    "deepseek": {
+      "command": "node",
+      "args": ["/absolute/path/to/deepseek-web-retrieval/dist/cli.js"],
+      "env": { "DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}" }
+    }
+  }
+}
+```
+
+## Control tiers
+
+Claude Code ships built-in `WebSearch` and `WebFetch` tools; neither is replaceable, so
+both capabilities use exclusion for the forced tier:
+
+| Capability | Optional | Preferred | Forced |
+| --- | --- | --- | --- |
+| Search | Tools registered; the built-in `WebSearch` stays available | Plus a CLAUDE.md rules block steering the model to `mcp__deepseek__deepseek_web_search` | Exclusion: `permissions.deny: ["WebSearch"]` |
+| Fetch | Tools registered; the built-in `WebFetch` stays available | Plus the rules block | Exclusion: `permissions.deny: ["WebFetch"]` |
+
+The installer maps each tier to these artifacts. Deny entries land in
+`~/.claude/settings.json` (user) or `./.claude/settings.json` (project) and merge with
+your existing `permissions.deny` entries. The CLAUDE.md rules block lands in
+`~/.claude/CLAUDE.md` (user) or `./CLAUDE.md` (project); Claude Code loads the user file
+plus every CLAUDE.md from the cwd up the directory tree, concatenating the levels — so
+the block steers wherever it is installed. Under a forced tier, other web-capable MCP
+servers detected in the config are denied by server-level rules (`mcp__<server>` denies
+every tool of that server), so routing stays exclusive.
+
+> [!WARNING]
+> Deny rules outrank allow rules at every settings level and **cannot be carved out** —
+> denying `WebSearch` or `WebFetch` removes the tool for every workflow in the install's
+> scope (every project on the machine for `--scope global`). A managed policy layer
+> (`managed-settings.json`) outranks both files; the installer reports when one exists.
+
+## Authentication
+
+`DEEPSEEK_API_KEY` is the only source; MCP has no host credential store. It is forwarded
+through the server's `env` block as `${DEEPSEEK_API_KEY}` and read per request, sent only
+to `api.deepseek.com` as a Bearer token. Without it the server exits at startup with a
+message on stderr.
+
+## Usage
+
+Ask naturally:
+
+```text
+Search the web for the latest Claude Code MCP config changes and cite the sources.
+Fetch https://code.claude.com/docs/en/mcp and summarize the config keys.
+```
+
+The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek_fetch`.
+
+The search tool accepts an optional `original_question` argument — the user's question in
+their own words — forwarded as DeepSeek's `ori_question` to sharpen search intent; omit it
+when the query already stands alone.
+
+Tool output is capped at 25k tokens by default (`MAX_MCP_OUTPUT_TOKENS`), and successful
+text results longer than 50,000 characters are saved to a file and referenced — not
+dropped silently.
+
+## Configuration
+
+Set these in the server's `env` block in `.mcp.json` (or `~/.claude.json`). Values map onto
+the shared option pipeline, so defaults and clamping match the other adapters.
+`DEEPSEEK_API_KEY` goes in the same block as the `${VAR}` expansion.
+
+> [!NOTE]
+> A shared config file — `~/.config/deepseek-web-retrieval/config.json`
+> (Windows: `%APPDATA%\deepseek-web-retrieval\config.json`), camelCase keys —
+> sits under the environment layer and works with no env forwarding at all: the server
+> reads the file itself, making it the way to set knobs without editing the MCP entry. The
+> file carries neither the API key nor the host-integration switches. Run
+> `npx deepseek-web-retrieval config` to see every knob's effective value and source
+> (it replays file warnings visibly and exits 1 on file problems); `config --search "<query>"`
+> verifies key, config, and network with one billed search.
+
+### Search
+
+The "Config file" column names each key's camelCase twin in the shared config file —
+one vocabulary pair, one pipeline. `—` marks host-integration entries the file rejects.
+
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_ENABLE_SEARCH` | — | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
+| `DEEPSEEK_SEARCH_COUNT` | `count` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
+| `DEEPSEEK_SEARCH_MAX_RESULTS` | `maxResults` | `10` | Results returned to the model after filtering, 0–50; defaults to `DEEPSEEK_SEARCH_COUNT` when unset. `0` returns no results. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `minRerank` | `0` | Drop results below this relevance score (0–3); results without a finite score pass at zero and are dropped at a positive threshold. |
+| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `minAuthority` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `allowUnknownAuthority` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0`/`no`/`off` to drop them. |
+| `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | `blockedDomains` | unset | Comma-separated; adds `-site:` operators to the query. |
+| `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | `includeDomains` | unset | Comma-separated; restricts results with `site:` operators. |
+| `DEEPSEEK_SEARCH_LANGUAGE` | `language` | unset | Adds a `lang:` operator, for example `zh,en`. |
+| `DEEPSEEK_SEARCH_LOCALIZATION` | `searchLocalization` | unset | Valid IPv4 or IPv6 address sent as DeepSeek's `localization` to prefer geo-localized results; invalid values are ignored. Deployment-level only, never a per-call parameter. |
+| `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `maxSummaryChars` | `1200` | Per-result summary cap, 0–1,000,000. |
+| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `searchTimeoutMs` | `30000` | Search timeout, 1,000–120,000 ms. |
+
+### Fetch
+
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_ENABLE_FETCH` | — | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
+| `DEEPSEEK_FETCH_MAX_CHARS` | `fetchMaxChars` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
+| `DEEPSEEK_FETCH_TIMEOUT_MS` | `fetchTimeoutMs` | `30000` | Fetch timeout, 1,000–120,000 ms. |
+| `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | `fetchAllowedDomains` | unset | If set, only these hosts and subdomains may be fetched. |
+| `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | `fetchBlockedDomains` | unset | Always block these hosts and subdomains. Blocked wins over allowed. |
+| `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `fetchBlockPrivateHosts` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. |
+
+### Credentials and retries
+
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_API_KEY` | — | required | DeepSeek API key, expanded from the launching environment via `${DEEPSEEK_API_KEY}`. The server refuses to start without it. |
+| `DEEPSEEK_MAX_RETRIES` | `maxRetries` | `2` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
+| `DEEPSEEK_RETRY_BASE_DELAY_MS` | `retryBaseDelayMs` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
+
+## Troubleshooting
+
+| Error or symptom | What to do |
+| --- | --- |
+| Server fails to start or `HTTP 401` from the tools | `DEEPSEEK_API_KEY` must be set in the environment that launches Claude Code; the `${DEEPSEEK_API_KEY}` expansion in the server's `env` block reads it at launch. |
+| Project tools missing after install | Claude Code asks once per project whether to use `.mcp.json` servers; approve the `deepseek` server when prompted or via the `/mcp` menu. |
+| Both tools missing after startup | At least one of `DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH` must stay enabled; the server exits when both are false. |
+| Forced tier still shows the built-in tool | The kill switch is the bare deny rule in `permissions.deny` at the install's scope; a managed policy layer (`managed-settings.json`) outranks it — the plan reports when one exists. |
+| Routing not exclusive | Other MCP servers stay registered and are noted in the plan. Under a forced tier, web-capable servers detected in the config (and the other scope's file) are denied by server-level `mcp__<server>` rules; a server added after install is not covered — re-run init. |
+| Fetch results appear as a file reference instead of content | Tool output is capped at 25k tokens by default; raise `MAX_MCP_OUTPUT_TOKENS` or lower `DEEPSEEK_FETCH_MAX_CHARS`. |
+| `HTTP 402`, `HTTP 429` | Top up the DeepSeek account; wait, reduce concurrency, or set `DEEPSEEK_MAX_RETRIES`. |
+| Fetch fails on localhost or an internal URL | Use a local fetch tool; DeepSeek cannot reach private networks. |
+
+## Compatibility
+
+| Component | Version |
+| --- | --- |
+| Claude Code | locked in [`docs/hosts.jsonc`](../hosts.jsonc) |
+| MCP revision | `2026-07-28` negotiated; server accepts `2024-11-05`–`2026-07-28` |
+| MCP SDK | `@modelcontextprotocol/server` 2.3.1 |
+| Runtime | Node.js 20+ (stdio) |
+| DeepSeek API | `/v1/tools/search`, `/v1/tools/fetch` |
+
+Tested with Claude Code at the `docs/hosts.jsonc` lock on Linux over stdio: the keyless
+Docker e2e verifies the installer's registration, tiers, and uninstall with a real
+`claude mcp list` handshake, and the billed scenario (`bun run test:e2e claude-code`,
+requires `DEEPSEEK_API_KEY`) runs headless prompts end to end with the deny kill switch
+asserted for both capabilities.
+
+## Uninstall
+
+```bash
+npx deepseek-web-retrieval uninstall --host claude-code --scope project
+```
+
+This removes the recorded `mcpServers.deepseek` entry and the installer-appended
+`permissions.deny` entries only when their current values still match what the installer
+wrote, removes the managed rules block, and deletes installer-created config files only
+when left empty. Later user edits to configuration values are kept and reported. For a
+manual installation, remove the `deepseek` entry from `.mcp.json` (or `~/.claude.json`),
+any `deepseek-web-retrieval` rules block in your `CLAUDE.md`, and the deny entries the
+setup added to `settings.json` if they were only for this integration.

package/docs/agents/codex.md

@@ -24,6 +24,8 @@ both the text and `structuredContent`.
 
 For shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
+For configuration layers, the full knob mapping, and defaults, see the
+[configuration guide](../configuration.md).
 
 ## Requirements
 
@@ -44,7 +46,9 @@ npx deepseek-web-retrieval init --host codex --scope global \
 ```
 
 It prints the full plan — every file, old value → new value, and notes about existing
-MCP servers — and writes nothing until you pass `--apply`. `uninstall` removes recorded
+MCP servers — and writes nothing until you pass `--apply`. Add `--pin` to register the
+exact version of the CLI you are running instead of the always-latest package name.
+`uninstall` removes recorded
 additions and restores snapshotted values that have not since been edited. Codex's config
 lives in `~/.codex/config.toml` at the user level only, so the server registration and kill switch
 are written there even for `--scope project`; the rules file follows the scope. An `off`
@@ -142,45 +146,64 @@ Fetch https://learn.chatgpt.com/docs/extend/mcp and summarize the config keys.
 
 The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek_fetch`.
 
+The search tool accepts an optional `original_question` argument — the user's question in
+their own words — forwarded as DeepSeek's `ori_question` to sharpen search intent; omit it
+when the query already stands alone.
+
 ## Configuration
 
 Set these in the server's `env` table. Values map onto the shared option pipeline, so
 defaults and clamping match the other adapters. `DEEPSEEK_API_KEY` goes in `env_vars`.
 
+> [!NOTE]
+> A shared config file — `~/.config/deepseek-web-retrieval/config.json`
+> (Windows: `%APPDATA%\deepseek-web-retrieval\config.json`), camelCase keys —
+> sits under the environment layer and works with no env forwarding at all: the server
+> reads the file itself, making it the way to set knobs without editing `env_vars` (the
+> installer's `env_vars` entry also forwards every `DEEPSEEK_*` name). The file carries
+> neither the API key nor the host-integration switches. Run
+> `npx deepseek-web-retrieval config` to see every knob's effective value and source
+> (it replays file warnings visibly and exits 1 on file problems); `config --search "<query>"`
+> verifies key, config, and network with one billed search.
+
 ### Search
 
-| Env variable | Default | Description |
-| --- | --- | --- |
-| `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
-| `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score (0–3); results without a finite score pass at zero and are dropped at a positive threshold. |
-| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0`/`no`/`off` to drop them. |
-| `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Comma-separated; adds `-site:` operators to the query. |
-| `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | Comma-separated; restricts results with `site:` operators. |
-| `DEEPSEEK_SEARCH_LANGUAGE` | unset | Adds a `lang:` operator, for example `zh,en`. |
-| `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `1200` | Per-result summary cap, 0–1,000,000. |
-| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `30000` | Search timeout, 1,000–120,000 ms. |
+The "Config file" column names each key's camelCase twin in the shared config file —
+one vocabulary pair, one pipeline. `—` marks host-integration entries the file rejects.
+
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_ENABLE_SEARCH` | — | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
+| `DEEPSEEK_SEARCH_COUNT` | `count` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
+| `DEEPSEEK_SEARCH_MAX_RESULTS` | `maxResults` | `10` | Results returned to the model after filtering, 0–50; defaults to `DEEPSEEK_SEARCH_COUNT` when unset. `0` returns no results. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `minRerank` | `0` | Drop results below this relevance score (0–3); results without a finite score pass at zero and are dropped at a positive threshold. |
+| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `minAuthority` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `allowUnknownAuthority` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0`/`no`/`off` to drop them. |
+| `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | `blockedDomains` | unset | Comma-separated; adds `-site:` operators to the query. |
+| `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | `includeDomains` | unset | Comma-separated; restricts results with `site:` operators. |
+| `DEEPSEEK_SEARCH_LANGUAGE` | `language` | unset | Adds a `lang:` operator, for example `zh,en`. |
+| `DEEPSEEK_SEARCH_LOCALIZATION` | `searchLocalization` | unset | Valid IPv4 or IPv6 address sent as DeepSeek's `localization` to prefer geo-localized results; invalid values are ignored. Deployment-level only, never a per-call parameter. |
+| `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `maxSummaryChars` | `1200` | Per-result summary cap, 0–1,000,000. |
+| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `searchTimeoutMs` | `30000` | Search timeout, 1,000–120,000 ms. |
 
 ### Fetch
 
-| Env variable | Default | Description |
-| --- | --- | --- |
-| `DEEPSEEK_ENABLE_FETCH` | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
-| `DEEPSEEK_FETCH_MAX_CHARS` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
-| `DEEPSEEK_FETCH_TIMEOUT_MS` | `30000` | Fetch timeout, 1,000–120,000 ms. |
-| `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset | If set, only these hosts and subdomains may be fetched. |
-| `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | unset | Always block these hosts and subdomains. Blocked wins over allowed. |
-| `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. |
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_ENABLE_FETCH` | — | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
+| `DEEPSEEK_FETCH_MAX_CHARS` | `fetchMaxChars` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
+| `DEEPSEEK_FETCH_TIMEOUT_MS` | `fetchTimeoutMs` | `30000` | Fetch timeout, 1,000–120,000 ms. |
+| `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | `fetchAllowedDomains` | unset | If set, only these hosts and subdomains may be fetched. |
+| `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | `fetchBlockedDomains` | unset | Always block these hosts and subdomains. Blocked wins over allowed. |
+| `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `fetchBlockPrivateHosts` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. |
 
 ### Credentials and retries
 
-| Env variable | Default | Description |
-| --- | --- | --- |
-| `DEEPSEEK_API_KEY` | required | DeepSeek API key, forwarded via `env_vars`. The server refuses to start without it. |
-| `DEEPSEEK_MAX_RETRIES` | `0` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
-| `DEEPSEEK_RETRY_BASE_DELAY_MS` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
+| Env variable | Config file | Default | Description |
+| --- | --- | --- | --- |
+| `DEEPSEEK_API_KEY` | — | required | DeepSeek API key, forwarded via `env_vars`. The server refuses to start without it. |
+| `DEEPSEEK_MAX_RETRIES` | `maxRetries` | `2` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
+| `DEEPSEEK_RETRY_BASE_DELAY_MS` | `retryBaseDelayMs` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
 
 ## Troubleshooting
 

package/docs/agents/opencode-v2.md

@@ -15,6 +15,8 @@ if you want all Markdown fetches to go through DeepSeek.
 
 For shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
+For configuration layers, the full knob mapping, and defaults, see the
+[configuration guide](../configuration.md).
 
 ## Requirements
 
@@ -38,7 +40,8 @@ npx deepseek-web-retrieval init --host opencode --scope <project|global> \
 ```
 
 It prints the full plan — every file, old value → new value — and writes nothing until
-you pass `--apply`. It snapshots the current `websearch.provider` before the forced tier
+you pass `--apply`. Add `--pin` to register the exact version of the CLI you are running
+instead of the always-latest package name. It snapshots the current `websearch.provider` before the forced tier
 replaces it, merges `permissions` without touching yours, preserves comments in
 `opencode.jsonc`, and `uninstall` restores recorded values that have not since been edited.
 Search has no `preferred` tier on OpenCode (the provider is host-level config, never a
@@ -112,11 +115,14 @@ follow the [upgrade instructions](../integration.md#upgrading-existing-installs)
 **Global checkout**
 
 ```bash
-git clone https://github.com/gwokhou/deepseek-web-retrieval.git \
+git clone https://github.com/guokhou/deepseek-web-retrieval.git \
   ~/.config/opencode/vendor/deepseek-web-retrieval
 ```
 
-Use `"package": "./vendor/deepseek-web-retrieval"`.
+Use `"package": "./vendor/deepseek-web-retrieval"`. On Windows the global config root is
+`%APPDATA%\opencode\` (unless `XDG_CONFIG_HOME` is explicitly set), so clone into
+`%APPDATA%\opencode\vendor\deepseek-web-retrieval` there — the same root the installer
+writes to.
 
 **Project checkout**
 
@@ -131,7 +137,8 @@ Use `"package": "./.opencode/vendor/deepseek-web-retrieval"`.
 **Auto-discovery**
 
 Clone or copy the repository into `~/.config/opencode/plugins/deepseek-web-retrieval` or
-`.opencode/plugins/deepseek-web-retrieval`. Auto-discovered plugins do not receive options,
+`.opencode/plugins/deepseek-web-retrieval` (on Windows, `%APPDATA%\opencode\plugins\…`).
+Auto-discovered plugins do not receive options,
 so `webfetch` stays in place; the `deepseek` search provider and `deepseek_fetch` are still
 added.
 
@@ -169,47 +176,66 @@ Fetch https://opencode.ai/v2/docs/build/plugins and summarize the plugin lifecyc
 The model calls `websearch` (provider `deepseek`) or `deepseek_fetch`. When
 `fetchOverrideWebfetch` is enabled, Markdown fetches go through `webfetch` instead.
 
+DeepSeek's optional `ori_question` is not sent on this path: OpenCode's `websearch` tool
+input is fixed to `query` at 2.0.32, so the provider has no channel for it (see the
+[research note](../research/ori-question-sourcing.md)).
+
 ## Configuration
 
 Set these in the plugin's `options` object.
 
+> [!NOTE]
+> These options use the same camelCase vocabulary as the shared config file
+> (`~/.config/deepseek-web-retrieval/config.json`; on Windows,
+> `%APPDATA%\deepseek-web-retrieval\config.json`), with the `DEEPSEEK_*` environment in
+> between: `shared file < environment < options`. Configure once in the file — it works on
+> every host — and override per host here in `options`; existing `options` keep winning
+> exactly as before. `npx deepseek-web-retrieval config` shows the file/env/defaults view
+> of every knob (these `options` sit above it, so check them here when it differs).
+
 ### Search
 
-| Option | Default | Description |
-| --- | --- | --- |
-| `searchEnabled` | `true` | Register the DeepSeek search provider at all. Only an explicit `false` disables it. |
-| `count` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `maxResults` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `minRerank` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. A result without a finite score passes while the threshold is `0` and is dropped once it is positive. |
-| `minAuthority` | `0` | Drop known authorities below this tier. Authority is 0–4. |
-| `allowUnknownAuthority` | `true` | Keep results whose authority is missing or unknown. Only an explicit `false` disables it. |
-| `blockedDomains` | `[]` | Add `-site:` operators to the search query. |
-| `includeDomains` | `[]` | Restrict results with `site:` operators. |
-| `language` | unset | Add a `lang:` operator, for example `zh,en`. |
-| `maxSummaryChars` | `1200` | Per-result summary cap, 0–1,000,000. |
-| `searchTimeoutMs` | `30000` | Search timeout, 1,000–120,000 ms. |
-| `setDefaultWebsearch` | `false` | Make `deepseek` the default websearch provider when the plugin loads. |
+The "Environment" column names each option's `DEEPSEEK_*` twin — the plugin reads the
+environment as the layer beneath these options, and the same camelCase keys also work
+in the shared config file beneath both. `—` marks host-integration options with no
+environment or file channel.
+
+| Option | Environment | Default | Description |
+| --- | --- | --- | --- |
+| `searchEnabled` | `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the DeepSeek search provider at all. Only an explicit `false` disables it. |
+| `count` | `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
+| `maxResults` | `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50; defaults to `count` when unset. `0` returns no results. |
+| `minRerank` | `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. A result without a finite score passes while the threshold is `0` and is dropped once it is positive. |
+| `minAuthority` | `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `allowUnknownAuthority` | `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Only an explicit `false` disables it. |
+| `blockedDomains` | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | `[]` | Add `-site:` operators to the search query. |
+| `includeDomains` | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | `[]` | Restrict results with `site:` operators. |
+| `language` | `DEEPSEEK_SEARCH_LANGUAGE` | unset | Add a `lang:` operator, for example `zh,en`. |
+| `searchLocalization` | `DEEPSEEK_SEARCH_LOCALIZATION` | unset | Valid IPv4 or IPv6 address sent as DeepSeek's `localization` to prefer geo-localized results; invalid values are ignored. Deployment-level only, never a per-call parameter. |
+| `maxSummaryChars` | `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `1200` | Per-result summary cap, 0–1,000,000. |
+| `searchTimeoutMs` | `DEEPSEEK_SEARCH_TIMEOUT_MS` | `30000` | Search timeout, 1,000–120,000 ms. |
+| `setDefaultWebsearch` | — | `false` | Make `deepseek` the default websearch provider when the plugin loads. |
 
 ### Fetch
 
-| Option | Default | Description |
-| --- | --- | --- |
-| `fetchEnabled` | `true` | Register any DeepSeek fetch tooling (the separate tool and the webfetch override). |
-| `fetchMaxChars` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
-| `fetchTimeoutMs` | `30000` | Fetch timeout, 1,000–120,000 ms. |
-| `fetchOverrideWebfetch` | `false` | Replace the built-in `webfetch`. |
-| `fetchRegisterTool` | `true` | Register the separate `deepseek_fetch` tool. |
-| `fetchAllowedDomains` | `[]` | If non-empty, only these hosts and subdomains may be fetched. |
-| `fetchBlockedDomains` | `[]` | Always block these hosts and subdomains. Blocked wins over allowed. |
-| `fetchBlockPrivateHosts` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. |
+| Option | Environment | Default | Description |
+| --- | --- | --- | --- |
+| `fetchEnabled` | `DEEPSEEK_ENABLE_FETCH` | `true` | Register any DeepSeek fetch tooling (the separate tool and the webfetch override). |
+| `fetchMaxChars` | `DEEPSEEK_FETCH_MAX_CHARS` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
+| `fetchTimeoutMs` | `DEEPSEEK_FETCH_TIMEOUT_MS` | `30000` | Fetch timeout, 1,000–120,000 ms. |
+| `fetchOverrideWebfetch` | — | `false` | Replace the built-in `webfetch`. |
+| `fetchRegisterTool` | — | `true` | Register the separate `deepseek_fetch` tool. |
+| `fetchAllowedDomains` | `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | `[]` | If non-empty, only these hosts and subdomains may be fetched. |
+| `fetchBlockedDomains` | `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | `[]` | Always block these hosts and subdomains. Blocked wins over allowed. |
+| `fetchBlockPrivateHosts` | `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. |
 
 ### Credentials and retries
 
-| Option | Default | Description |
-| --- | --- | --- |
-| `apiKeySource` | `"auto"` | Credential strategy: `"auto"`, `"opencode"`, or `"env"`. |
-| `maxRetries` | `0` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
-| `retryBaseDelayMs` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
+| Option | Environment | Default | Description |
+| --- | --- | --- | --- |
+| `apiKeySource` | — | `"auto"` | Credential strategy: `"auto"`, `"opencode"`, or `"env"`. |
+| `maxRetries` | `DEEPSEEK_MAX_RETRIES` | `2` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
+| `retryBaseDelayMs` | `DEEPSEEK_RETRY_BASE_DELAY_MS` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
 
 ## Troubleshooting