deepseek-web-retrieval 0.5.1 → 0.7.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/codex.md

@@ -27,7 +27,8 @@ For shared search/fetch limits, retries, and privacy behavior, see
 
 ## Requirements
 
-- Codex 0.163.0 or newer
+- Codex 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
@@ -43,9 +44,11 @@ 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` restores exactly
-what the plan applied (snapshots, merged entries, created files). Codex's config lives in
-`~/.codex/config.toml` at the user level only, so the server registration and kill switch
+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`
 capability is written as the tool's name in the server entry's `disabled_tools` array —
 Codex's own mechanism — merging with any entries you put there yourself. When `codex` is
@@ -54,6 +57,10 @@ release differs from the tested lock (see
 [hosts.jsonc](../hosts.jsonc)) — version-anchored behavior such as the kill switch 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 `~/.codex/config.toml`:
@@ -137,45 +144,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. DeepSeek scores are 0–3. |
-| `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` 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
 
@@ -208,7 +234,9 @@ Tested with Codex 0.163.0 on Linux over stdio.
 npx deepseek-web-retrieval uninstall --host codex --scope global
 ```
 
-This restores the previous `web_search` value, removes the `mcp_servers.deepseek` table
-and the rules block, and deletes files the installer created. Manually, remove the
+This restores snapshotted `web_search` and `mcp_servers.deepseek` values 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
 `[mcp_servers.deepseek]` table, any `deepseek-web-retrieval` rules block in your
 `AGENTS.md`, and the top-level `web_search` key if it was only set for the forced tier.

package/docs/agents/opencode-v2.md

@@ -2,7 +2,7 @@
 
 OpenCode v2 adapter for [DeepSeek Web Retrieval](../../README.md).
 
-Integration mechanism: OpenCode's native plugin API (`@opencode/plugin` 2.0.32+), not MCP.
+Integration mechanism: OpenCode's native plugin API (`@opencode/plugin`), not MCP.
 
 When loaded, it adds:
 
@@ -18,7 +18,9 @@ For shared search/fetch limits, retries, and privacy behavior, see
 
 ## Requirements
 
-- OpenCode v2 with `@opencode/plugin` 2.0.32 or newer
+- OpenCode v2 with `@opencode/plugin` in the `^2.0.32` peer range; the tested version
+  is recorded in [`docs/hosts.jsonc`](../hosts.jsonc)
+- Node.js 20+ and npm when using the installer CLI
 - 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
 - A DeepSeek credential stored in OpenCode, or `DEEPSEEK_API_KEY`
@@ -36,10 +38,12 @@ 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 everything. Search has no `preferred` tier on
-OpenCode (the provider is host-level config, never a model choice); the CLI rejects it.
+`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
+model choice); the CLI rejects it.
 
 ### OpenCode CLI install
 
@@ -100,17 +104,23 @@ A complete global config:
 Use the bare package name (optionally pinned) as the `package` value:
 
 ```jsonc
-"plugins": [{ "package": "deepseek-web-retrieval@0.4.0" }]
+"plugins": [{ "package": "deepseek-web-retrieval" }]
 ```
 
+Append `@X.Y.Z` to pin a published version. For an existing installer-managed setup,
+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**
 
@@ -125,7 +135,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.
 
@@ -163,47 +174,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
 
@@ -234,7 +264,7 @@ using both an OpenCode-stored DeepSeek credential and `DEEPSEEK_API_KEY`.
 ## Uninstall
 
 With the installer CLI (restores the snapshotted `websearch.provider`, removes only the
-appended permissions, and deletes files it created):
+appended permissions, and deletes installer-created files only when they are left empty):
 
 ```bash
 npx deepseek-web-retrieval uninstall --host opencode --scope <project|global>

package/docs/agents/pi.md

@@ -25,7 +25,9 @@ shared search/fetch limits, retries, and privacy behavior, see
 
 ## Requirements
 
-- Pi 1.3.0 or newer
+- Pi with host SDKs in the `^1.3.0` peer range (`>=1.3.0 <2.0.0`); the tested
+  version is recorded in [`docs/hosts.jsonc`](../hosts.jsonc)
+- Node.js 20+ and npm when using the installer CLI or MCP fallback
 - 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 Pi
@@ -40,14 +42,20 @@ npx deepseek-web-retrieval init --host pi --scope <project|global> \
 ```
 
 It prints the full plan — every file, old value → new value, and notes about existing
-packages and MCP servers — and writes nothing until you pass `--apply`. The default path is
+packages and 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. The default path is
 the extension: the plan appends `npm:deepseek-web-retrieval` to the `packages` array in
 `~/.pi/agent/settings.json` (global) or `.pi/settings.json` (project), and Pi resolves the
 source at the next session start (the first launch fetches the package from npm;
 `pi update --extensions` refreshes it later). An off capability is written into the
 `deepseekWebRetrieval` settings namespace the extension reads at load. Pass `--path mcp`
-to install the [MCP fallback path](#the-mcp-fallback-path) instead. `uninstall` restores
-exactly what the plan applied.
+to install the [MCP fallback path](#the-mcp-fallback-path) instead. `uninstall` removes
+recorded additions and restores unchanged configuration values from their snapshots.
+
+For upgrades from 0.4.0, select `--path mcp` explicitly to retain the old path, or use
+the extension default to migrate; follow the shared
+[upgrade instructions](../integration.md#upgrading-existing-installs).
 
 ### Manual install
 
@@ -96,6 +104,12 @@ Fetch https://pi.dev/docs/latest/extensions and summarize the extension lifecycl
 The model calls `deepseek_web_search` or `deepseek_fetch` — the same names over both paths;
 only the MCP fallback prefixes them with `mcp__deepseek__`.
 
+The search tool accepts an optional `original_question` input — the user's question in their
+own words — forwarded as DeepSeek's `ori_question` to sharpen search intent. When the model
+leaves it blank, the extension falls back to the most recent user message in the session
+(best-effort; truncated to the API's 128-character limit). The MCP fallback path has no
+session access, so there a blank input simply omits the parameter.
+
 ## Configuration
 
 The runtime config surface is the same `DEEPSEEK_*` environment the MCP server reads
@@ -103,40 +117,53 @@ The runtime config surface is the same `DEEPSEEK_*` environment the MCP server r
 `deepseekWebRetrieval` settings namespace for the off switches (written by the installer;
 it outranks the environment and is preserved by Pi's own settings rewrites).
 
+The shared config file (`~/.config/deepseek-web-retrieval/config.json`, camelCase keys —
+on Windows, `%APPDATA%\deepseek-web-retrieval\config.json`)
+also sits in this surface, layered under the environment, and needs no forwarding on any
+path — the extension and the MCP server both read the file themselves. One file therefore
+configures every host running this package, with this host's environment and settings
+still outranking it. `npx deepseek-web-retrieval config` prints what actually resolves —
+each knob's value and source, with file warnings surfaced and `--search "<query>"` running
+one billed search through it all.
+
 ### 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. DeepSeek scores are 0–3. |
-| `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` 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. No host-side cap applies on the extension path. |
+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. No host-side cap applies on the extension path. |
 
 ### 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. The only output cap on this path. |
-| `DEEPSEEK_FETCH_TIMEOUT_MS` | `30000` | Fetch timeout, 1,000–120,000 ms. No host-side cap applies on the extension path. |
-| `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. Set `false`/`0` to disable. |
+| 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. The only output cap on this path. |
+| `DEEPSEEK_FETCH_TIMEOUT_MS` | `fetchTimeoutMs` | `30000` | Fetch timeout, 1,000–120,000 ms. No host-side cap applies on the extension path. |
+| `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. Set `false`/`0` to disable. |
 
 ### Credentials and retries
 
-| Env variable | Default | Description |
-| --- | --- | --- |
-| `DEEPSEEK_API_KEY` | required | DeepSeek API key, read from the Pi process environment. |
-| `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, read from the Pi process environment. |
+| `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. |
 
 Invalid values fall back to the shared default.
 
@@ -175,7 +202,9 @@ With the installer CLI:
 npx deepseek-web-retrieval uninstall --host pi --scope <project|global>
 ```
 
-Or remove the source with Pi itself:
+For a manual installation, remove the source with Pi itself; use `--local` for a
+project-local install. Installer-managed installs should use `uninstall` above so
+rules, snapshots, and install records are cleaned up as well:
 
 ```bash
 pi remove npm:deepseek-web-retrieval