deepseek-web-retrieval 0.6.0 → 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

@@ -44,7 +44,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 +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 (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

@@ -38,7 +38,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 +113,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 +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.
 
@@ -169,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
 

package/docs/agents/pi.md

@@ -42,7 +42,9 @@ 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;
@@ -102,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
@@ -109,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 (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. 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.
 

package/docs/design/config-layering-design.md

@@ -0,0 +1,180 @@
+# Configuration layering design
+
+Design note for the shared configuration base layer across the three shipped adapters (MCP
+server, OpenCode plugin, Pi extension). It records the parameter taxonomy, the precedence
+model, and the per-adapter composition so the design survives between conversations. Host
+capability facts live in [control-matrix.md](../research/control-matrix.md); the config
+surface inventory was verified against the code on 2026-10-23.
+
+## Problem
+
+The state this design replaced — recorded here as history, not as the present. The option
+pipeline was already single-sourced (names, defaults, clamping in
+`src/core/constants.ts` → `src/core/env.ts` → `src/core/options.ts`), but the *channels*
+that fed it were fragmented per host, and a multi-host user configured the same intent in
+up to three ways:
+
+- **Pi** — extension runs in-process; `DEEPSEEK_*` shell variables just worked.
+- **Codex** — stdio children do not inherit the parent environment, and the installer's
+  `env_vars` entry forwarded **only** `DEEPSEEK_API_KEY`; every other knob set in the
+  shell never reached the server unless the user hand-edited `config.toml` to add each
+  variable name. (The entry now forwards every `DEEPSEEK_*` name — see the Codex
+  consequence in [ADR-0002](../adr/0002-shared-config-base-layer.md).)
+- **OpenCode** — the plugin resolved **only** `ctx.options` (opencode.json plugin
+  options, camelCase); `DEEPSEEK_*` variables configured nothing there, so the same
+  knob had a second, differently-named vocabulary. (The plugin now composes
+  file < environment < `ctx.options` — see the per-adapter composition below.)
+
+One intent ("20 results, block pinterest.com"), three configuration acts, two
+vocabularies, one silent-failure trap. The isolation was accidental, not chosen.
+
+## Parameter taxonomy
+
+Isolation versus unification is decided per class, not globally:
+
+| Class | Parameters | Policy |
+| --- | --- | --- |
+| **API behavior** — describes the user↔DeepSeek relationship, host-independent | `count`, `maxResults`, `minRerank`, `minAuthority`, `allowUnknownAuthority`, `blockedDomains`, `includeDomains`, `language`, `searchLocalization`, `maxRetries`, `retryBaseDelayMs` | Shared base; identical everywhere unless a host layer overrides |
+| **Host-sensitive** — interacts with host output caps / deadlines (OpenCode 2,000 lines / 50 KiB; Pi MCP 20 KB + 60 s; Pi extension uncapped; Claude Code 25k tokens) | `searchTimeoutMs`, `fetchTimeoutMs`, `fetchMaxChars`, `maxSummaryChars` | Shared base gives the safe default; **per-host override in the host-native layer is the recommended place** to raise them |
+| **Host integration** — describes the host's tool landscape, not the API | `searchEnabled`, `fetchEnabled`, `setDefaultWebsearch`, `fetchOverrideWebfetch`, `fetchRegisterTool`, `apiKeySource` | **Deliberately isolated.** Installer-written, host-native config only; the shared file rejects them |
+
+Security-shaped knobs (`fetchAllowedDomains`, `fetchBlockedDomains`, `fetchBlockPrivateHosts`)
+are classed as API behavior: they are deployment policy about the DeepSeek call itself, and a
+shared base strengthens rather than weakens them (one policy instead of three drifting ones).
+
+## The layering model
+
+Precedence, low → high, identical semantics in every adapter:
+
+```
+built-in defaults  <  shared config file  <  DEEPSEEK_* environment  <  host-native config
+```
+
+- **Host-native config** means: OpenCode `ctx.options` (opencode.json plugin entry), Pi's
+  `deepseekWebRetrieval` settings namespace (the two switches), and — for MCP hosts — the
+  per-server `env` block in the host's MCP registration (that block is *how* an environment
+  variable arrives, not a fifth layer).
+- Host-native layers keep outranking the base: installer-written intent (capability tiers)
+  and explicit per-host overrides always win, so the blast radius of a bad shared value is
+  bounded by whatever the host layer pins.
+- The two vocabularies stay as they are — `DEEPSEEK_*` snake-case names for the environment,
+  camelCase `PluginOptions` keys for the file and OpenCode options — both generated from the
+  same single source and documented side by side.
+
+## The shared config file
+
+- **Path:** `$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json`, defaulting to
+  `~/.config/deepseek-web-retrieval/config.json`. On win32 an explicit, non-empty
+  `XDG_CONFIG_HOME` still wins; otherwise the conventional Roaming root applies —
+  `%APPDATA%\deepseek-web-retrieval\config.json`, falling back to
+  `<home>\AppData\Roaming\deepseek-web-retrieval\config.json` when `%APPDATA%` is
+  unset. User scope, one file. A project-scope file
+  is a confirmed non-goal for this iteration (open question below).
+- **Format:** JSON object; keys are the camelCase `PluginOptions` vocabulary (class 1 and 2
+  only). Example:
+
+  ```json
+  {
+    "count": 20,
+    "blockedDomains": ["pinterest.com"],
+    "language": "zh",
+    "searchLocalization": "203.0.113.7"
+  }
+  ```
+
+- **Validation:** the file's parsed object feeds the existing `resolvePluginOptions` —
+  clamps, IP validation, and domain normalization all come along for free. Unknown keys and
+  class-3 (host-integration) keys are **rejected with a one-line stderr warning** and
+  otherwise ignored; a missing or unparseable file contributes nothing (a warning line for
+  the unparseable case), mirroring the Pi settings reader's conventions.
+- **The API key is deliberately absent.** Auth keeps its existing channels
+  (`DEEPSEEK_API_KEY`, OpenCode's auth store, Pi's env) — a config file is liable to end up
+  synced through dotfiles, and widening key storage is a security-surface decision this
+  design does not make.
+
+## Per-adapter composition
+
+- **MCP server** (`src/mcp/serve.ts`): `resolveEnvOptions(env)` becomes
+  `resolveEnvOptions(env, readFileOptions())` — file keys under environment keys. The server
+  reads the file itself, so **the Codex `env_vars` trap disappears** regardless of what the
+  host forwards.
+- **Pi extension** (`src/pi/extension.ts`): `resolveExtensionOptions` inserts the file
+  between defaults and the environment; the settings namespace stays on top, unchanged.
+- **OpenCode plugin** (`src/opencode/plugin.ts`): `resolvePluginOptions(ctx.options)` becomes
+  `resolvePluginOptions({ ...fileOptions(), ...pluginOptionsFromEnv(process.env), ...ctx.options })`
+  — file, then environment, then the host layer. Additive only: existing opencode.json
+  options keep winning exactly as before; the change is that the file and environment now
+  work on this host too.
+
+## Installer changes
+
+- **Codex `env_vars`:** enumerate **every** `DEEPSEEK_*` name (generated from
+  `src/core/constants.ts`, the single source) instead of only `DEEPSEEK_API_KEY`, so
+  environment overrides work on Codex without hand-editing `config.toml`. The note the
+  installer prints is updated to match.
+- No other host artifacts change: the installer never writes the shared file (it is a user
+  authoring surface, like a shell profile), and capability tiers stay where they are.
+
+## Visibility
+
+A bad shared value now fails everywhere at once, so effective configuration must be visible:
+
+- The MCP server's startup stderr line (already printing the client identity and enabled
+  tools) additionally prints **deviations from defaults only** — e.g.
+  `config: count=20 blockedDomains=1 language=zh` — keeping the line short while showing
+  every non-default knob a multi-layer resolution produced.
+- The OpenCode plugin and Pi extension print the same deviation summary once, at
+  registration time, through their host's logging channel (implementer picks the least
+  noisy channel per host; the content contract is "non-default effective values").
+- `deepseek-web-retrieval config` is the user-facing arm: it prints every knob with its
+  value and source, replays the file's warnings where a human actually looks, and its
+  `--search` variant verifies the whole chain (key, config, network) with one billed
+  request.
+
+## What this design does not change
+
+- `need_content` stays hardcoded `false` ([search-inline-content.md](../research/search-inline-content.md)).
+- `ori_question` remains per-call-only (`original_question` input / Pi session fallback); it
+  is not configurable.
+- Auth surfaces, capability tiers, and the installer's plan/confirm flow.
+
+## Testing
+
+- Unit: file reader (missing / unparseable / unknown-key / class-3-key rejection with
+  warning), precedence matrix per adapter (defaults < file < env < host) asserted through
+  each adapter's existing resolution entry points.
+- The installer's Codex plan snapshot gains the full `env_vars` list.
+- Existing suites stay green; e2e scenarios unaffected (the file is absent in CI, which is
+  itself the empty-layer case).
+
+## Rollout
+
+Additive and non-breaking: no existing configuration loses effect, no precedence between
+existing layers changes. Documentation updates ship with the code: README gains a
+"Configuration" section with the precedence table and the two-vocabulary table; the host
+guides' option tables gain a shared-file column; the control-matrix note's Pi sentence
+("There is no per-extension options channel: the runtime config surface is the
+`DEEPSEEK_*` environment") is updated to name the file as part of that surface.
+
+**Amendment, 2026-10-23** — two changes approved after this design was confirmed alter
+the effective behavior of *untouched* configurations, superseding the "no existing
+configuration loses effect" sentence for those two knobs:
+
+1. `maxResults` now follows the effective `count` when unset, so `count`-only
+   configurations return `count` results instead of silently truncating to the old
+   default of 10 (the one-directional asymmetry is documented at the resolution site in
+   `src/core/options.ts`).
+2. Transient failures (408/425/429/5xx) retry twice by default instead of zero
+   (rationale and the dated vendor-survey correction live in
+   `docs/research/search-api-defaults.md`).
+
+## Decisions (confirmed 2026-10-23)
+
+1. **Project-scope file:** not in this iteration — hosts already own project-scope
+   semantics, and the extra precedence row is not yet earned by demand.
+2. **Invalid-key warnings:** one stderr line per bad key at first resolution — the noise
+   buys typo detection (`"retries"` vs `"maxRetries"`) in a hand-edited file.
+3. **File naming:** `config.json` inside the `~/.config/deepseek-web-retrieval/`
+   directory (win32: `%APPDATA%\deepseek-web-retrieval\`) — room for future siblings.
+4. **ADR:** the layering decision is recorded as
+   [ADR 0002](../adr/0002-shared-config-base-layer.md) alongside this design note.

package/docs/design/installer-design.md

@@ -198,6 +198,14 @@ into any existing `permissions` array rather than replacing it.
   documents a layer above user config, so there is nothing to check there yet.
 - Only a bare `--apply` enables writes; assigning a value such as `--apply=false`
   is a usage error and writes nothing.
+- `--pin` is opt-in version pinning: the ref written into host config gets the
+  running CLI's version appended (`name` becomes `name@<version>`; a ref already
+  ending in a version keeps it), so a host resolves that exact release instead of
+  the latest publish. Without the flag the ref stays unpinned, byte-identical to
+  before; re-running `init --pin` from a newer CLI moves the pin. Ref identity —
+  orphan, upgrade, and unexcludable-competitor detection — compares package names
+  with the `@version` suffix stripped (`samePackageName` in ownership.ts), so a
+  pinned ref still matches the lineage an earlier init registered.
 - File verification precedes the install-record commit. A write or verification
   failure restores the pre-apply files and record and checks the restored values.
   `ApplyError.status` is `rolled_back` only after recovery and new-claim cleanup

package/docs/integration.md

@@ -94,9 +94,12 @@ For an installation managed by `init`:
    needed for uninstall. A global install can still claim shared configuration from a
    particular project, so keep the original working directory for upgrades.
 3. Refresh the package in the host and start or reload a session as described in its
-   guide. For Pi's extension path, use `pi update --extensions`. If you pin the host's
-   package version, pass the desired `--package deepseek-web-retrieval@X.Y.Z` to init;
-   updating the CLI alone does not update an independently pinned host package.
+   guide. For Pi's extension path, use `pi update --extensions`. To pin the host's
+   package to the exact version being run, pass `--pin` to init (it writes
+   `deepseek-web-retrieval@X.Y.Z` into the registration); upgrading a pinned install
+   means re-running init with the newer CLI, since updating the CLI alone does not
+   move an independently pinned host package. `--package` still overrides the ref
+   entirely.
 
 When upgrading from 0.4.0, Pi's default changes from MCP to the native extension.
 Pass `--path mcp` explicitly to retain MCP, or `--path extension` to migrate; the plan