deepseek-web-retrieval 0.9.0 → 0.10.0

package/docs/agents/pi.md

@@ -8,7 +8,9 @@ start. The same build also ships an MCP server over stdio as the fallback path
 ([below](#the-mcp-fallback-path)); the extension is the recommended one:
 
 - The tools are declared to the model like built-ins (`exposure: "direct"` is Pi's own
-  default for extension tools — the MCP path's codemode trap does not exist here).
+  default for extension tools — the MCP path defaults its tools to
+  `exposure: "codemode"`, which hides them from the model unless the entry opts into
+  `direct`; that trap does not exist here).
 - Results bypass Pi's MCP layer entirely: no 20 KB middle truncation and no 60 s
   per-request timeout; the adapter's own output cap is the only limit.
 - The key is read from the Pi process environment — no `env` forwarding, no `${VAR}`
@@ -19,7 +21,8 @@ When loaded, it adds:
 - A `deepseek_web_search` tool backed by DeepSeek Search
 - A `deepseek_fetch` tool backed by DeepSeek Fetch
 
-Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path. For
+Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path (see
+[Control tiers](#control-tiers)). 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
@@ -29,7 +32,7 @@ For configuration layers, the full knob mapping, and defaults, see the
 
 - 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
+- Node.js 20 or newer 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
@@ -55,7 +58,8 @@ source at the next session start (the first launch fetches the package from npm;
 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
+For upgrades from a 0.4.x or earlier install (MCP was Pi's default path before 0.5.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).
 
@@ -86,6 +90,27 @@ pi install /absolute/path/to/deepseek-web-retrieval
 The extension entry imports only host-supplied modules (`@earendil-works/pi-coding-agent`,
 `@earendil-works/pi-ai`) and the package's own `src/core/`, so a plain clone works.
 
+## Control tiers
+
+Pi 1.3.0 ships no built-in web tool, so the registered tools are the only web path at
+every tier — forced is de-facto rather than exclusion:
+
+| Capability | Optional | Preferred | Forced |
+| --- | --- | --- | --- |
+| Search | Tools registered — already the only web search | Plus an AGENTS.md rules block steering the model to the search tool | De-facto: no built-in competitor; web-capable MCP servers in `mcp.json` are disabled |
+| Fetch | Tools registered — already the only web fetch | Plus the rules block | De-facto: same |
+
+The installer maps each tier to these artifacts. The rules block lands in
+`~/.pi/agent/AGENTS.md` (global) or `./AGENTS.md` (project), naming the path's tool
+ids (`deepseek_web_search` for the extension, `mcp__deepseek__deepseek_web_search` for
+the MCP fallback). Under a forced tier, web-capable MCP servers detected in
+`~/.pi/agent/mcp.json` or `.pi/mcp.json` get `enabled: false` (each prior value
+snapshotted for uninstall); a web-capable `packages` or `extensions` source in
+settings.json cannot be excluded — Pi has no per-package kill switch — so `init`
+refuses the tier instead of promising routing it cannot deliver. The `off` tier is the
+`deepseekWebRetrieval` settings namespace described under
+[Configuration](#configuration).
+
 ## Authentication
 
 `DEEPSEEK_API_KEY` is the only source: the extension runs inside the Pi process and reads
@@ -122,7 +147,8 @@ opens with `Searched for: <effective query>` (plus any degradation applied to fi
 The runtime config surface is the same `DEEPSEEK_*` environment the MCP server reads
 (identical defaults and clamping), set in the shell that launches Pi, plus the
 `deepseekWebRetrieval` settings namespace for the off switches (written by the installer;
-it outranks the environment and is preserved by Pi's own settings rewrites).
+it outranks the environment and is preserved by Pi's own settings rewrites). Invalid
+`DEEPSEEK_*` values are dropped at startup and the shared default applies.
 
 The shared config file (`~/.config/deepseek-web-retrieval/config.json`, camelCase keys —
 on Windows, `%APPDATA%\deepseek-web-retrieval\config.json`)
@@ -162,7 +188,7 @@ one vocabulary pair, one pipeline. `—` marks host-integration entries the file
 | `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. |
+| `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `fetchBlockPrivateHosts` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. Set `false`/`0`/`no`/`off` to disable. |
 
 ### Credentials and retries
 
@@ -172,8 +198,6 @@ one vocabulary pair, one pipeline. `—` marks host-integration entries the file
 | `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.
-
 ## Troubleshooting
 
 | Error or symptom | What to do |
@@ -197,9 +221,9 @@ Invalid values fall back to the shared default.
 | Runtime | Inside the Pi process (Node, host-provided) |
 | DeepSeek API | `/v1/tools/search`, `/v1/tools/fetch` |
 
-Tested with Pi 1.3.0 on Linux. The extension API is version-locked research surface: the
-`ToolDefinition` shape and the settings `packages` key are verified at the locked version
-(see [the per-host reference](../research/control-matrix.md#pi)).
+Tested with Pi 1.3.0 on Linux. The extension API surface this package relies on — the
+`ToolDefinition` shape and the settings `packages` key — is verified at the locked
+version (see [the per-host reference](../research/control-matrix.md#pi)).
 
 ## Uninstall
 

package/docs/configuration.md

@@ -13,7 +13,7 @@ guides: [Codex](agents/codex.md), [Claude Code](agents/claude-code.md),
 
 Every knob resolves through one chain, low → high, identically on every host:
 
-```
+```text
 built-in defaults  <  shared config file  <  DEEPSEEK_* environment  <  host-native config
 ```
 
@@ -26,7 +26,7 @@ variable arrives, not a fifth layer).
 ## The shared config file
 
 `$XDG_CONFIG_HOME/deepseek-web-retrieval/config.json` when `XDG_CONFIG_HOME` is
-set (this wins on every platform, Windows included); otherwise
+set to a non-empty value (this wins on every platform, Windows included); otherwise
 `~/.config/deepseek-web-retrieval/config.json` on Linux and macOS and
 `%APPDATA%\deepseek-web-retrieval\config.json` on Windows. camelCase keys:
 
@@ -49,7 +49,7 @@ environment, or OpenCode's stored credential).
 | Knob class | Shared file | Examples |
 | --- | --- | --- |
 | API behavior — the user↔DeepSeek relationship | yes — that is the point of the file | `count`, `blockedDomains`, `language`, `maxRetries` |
-| Host-sensitive — interacts with host output caps and deadlines | carries the safe defaults; a host layer is the recommended override point | `searchTimeoutMs`, `fetchTimeoutMs`, `fetchMaxChars`, `maxSummaryChars` |
+| Host-sensitive — interacts with host output caps and deadlines | carries the safe defaults; a host layer is the recommended override point | `searchTimeoutMs`, `fetchTimeoutMs`, `fetchMaxChars`, `maxSummaryChars`, `searchContentMaxChars`, `searchContentTimeoutMs` |
 | Host integration — the host's tool landscape | rejected — warned about and ignored | `searchEnabled`, `setDefaultWebsearch`, `apiKeySource` |
 
 Keep host-independent intent in the shared file; prefer a host layer when a
@@ -58,8 +58,8 @@ host-sensitive knob would cross its host's cap or deadline.
 ## The knob vocabulary
 
 One knob, two names: the camelCase key for the shared file and OpenCode's
-options, the `DEEPSEEK_*` variable for the environment. The table generates
-from the same config vocabulary the adapters resolve through, so it cannot
+options, the `DEEPSEEK_*` variable for the environment. The table is
+generated from the same config vocabulary the adapters resolve through, so it cannot
 drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
 
 <!-- generated: knob-table — edit src/core/config-summary.ts or env.ts, then run `bun run docs:matrix` -->
@@ -76,6 +76,8 @@ drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
 | `language` | `DEEPSEEK_SEARCH_LANGUAGE` | unset |
 | `searchLocalization` | `DEEPSEEK_SEARCH_LOCALIZATION` | unset |
 | `maxSummaryChars` | `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | 1200 |
+| `searchContentMaxChars` | `DEEPSEEK_SEARCH_CONTENT_MAX_CHARS` | 1500 |
+| `searchContentTimeoutMs` | `DEEPSEEK_SEARCH_CONTENT_TIMEOUT_MS` | 60000 |
 | `searchTimeoutMs` | `DEEPSEEK_SEARCH_TIMEOUT_MS` | 30000 |
 | `fetchMaxChars` | `DEEPSEEK_FETCH_MAX_CHARS` | 16000 |
 | `fetchAllowedDomains` | `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset |
@@ -97,8 +99,9 @@ drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
   `fetchBlockPrivateHosts`, `searchEnabled`, and `fetchEnabled` are on by
   default; the environment can only turn them off (`false`, `0`, `no`, or
   `off`). The last two have no file key — they are host-integration keys — so
-  they exist only as `DEEPSEEK_ENABLE_SEARCH` and `DEEPSEEK_ENABLE_FETCH`. A
-  value like `=true` changes nothing.
+  they exist only as `DEEPSEEK_ENABLE_SEARCH` and `DEEPSEEK_ENABLE_FETCH`.
+  Setting any of them to `true` explicitly changes nothing: the default is
+  already on.
 - **Invalid environment values are dropped** at startup and the default
   applies. `npx deepseek-web-retrieval config` reports every dropped or
   unknown `DEEPSEEK_*` variable as a warning and exits 1, alongside file
@@ -106,10 +109,17 @@ drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
 - **`searchLocalization` must be a valid IPv4 or IPv6 address**; anything else
   is dropped at option resolution. It is deployment-level configuration, never
   a per-call tool parameter.
+- **The content envelope is deployment-level too.** `searchContentMaxChars` and
+  `searchContentTimeoutMs` apply only when a call asks for inline page content
+  (`need_content: true`, a per-call tool parameter on the MCP server and the Pi
+  extension; OpenCode's provider input has no channel for it, so search stays
+  summary-only there). They are never tool parameters — the model cannot see
+  which host caps its output. `searchContentMaxChars: 0` drops page bodies
+  entirely and the summary digest renders.
 - **`baseUrl` routes the retrieval API** (`/v1/tools/search` and
   `/v1/tools/fetch` are composed from it). It is infrastructure routing for
-  proxies, gateways, and mock upstreams — not a provider switch, so nothing
-  falls back to another search service. Only an http(s) URL survives
+  proxies, gateways, and mock upstreams — not a provider switch, and the package
+  never falls back to another search service. Only an http(s) URL survives
   resolution (trailing slashes are stripped); anything else drops back to
   `https://api.deepseek.com`.
 - **Domains** in the environment are comma-separated; entries that are not

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

@@ -46,7 +46,7 @@ shared base strengthens rather than weakens them (one policy instead of three dr
 
 Precedence, low → high, identical semantics in every adapter:
 
-```
+```text
 built-in defaults  <  shared config file  <  DEEPSEEK_* environment  <  host-native config
 ```
 
@@ -133,9 +133,13 @@ A bad shared value now fails everywhere at once, so effective configuration must
 
 ## 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.
+- `need_content` is no longer hardcoded `false` — it became a per-call tool parameter
+  with a deployment-owned envelope
+  ([search-content-design.md](search-content-design.md),
+  [ADR-0003](../adr/0003-need-content-per-call-boolean.md)).
+- `ori_question` remains per-call-only — supplied through the tool input named
+  `original_question` (with the Pi session fallback) and sent to the API as `ori_question`;
+  it is not configurable.
 - Auth surfaces, capability tiers, and the installer's plan/confirm flow.
 
 ## Testing
@@ -154,7 +158,8 @@ existing layers changes. Documentation updates ship with the code: README gains
 "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.
+`DEEPSEEK_*` environment") is updated to name the file as part of that surface. All of
+these updates are shipped and in place.
 
 **Amendment, 2026-10-23** — two changes approved after this design was confirmed alter
 the effective behavior of *untouched* configurations, superseding the "no existing

package/docs/design/installer-design.md

@@ -43,8 +43,9 @@ already exists, and the installer uses three phases:
 1. **Detect.** Read the host config, the rules files, and the registered MCP servers.
    Report the conflict surface: existing rules steering toward another web tool; other
    web-capable MCP servers already on the field; array-valued keys the plan must merge
-   into rather than replace (`disabledTools`, `permissions.deny`, permissions
-   `exclude`, `disabled_tools`); and higher layers (Claude Code managed policy — its
+   into rather than replace (Cline's `disabledTools`, Claude Code's `permissions.deny`,
+   permissions `exclude` arrays, Codex's and Devin's `disabled_tools`); and higher
+   layers (Claude Code managed policy — its
    existence is checked by the claude-code module; Devin enterprise team settings) that
    would outrank what the installer writes.
 2. **Merge or snapshot.** Array keys merge with existing entries, recording exactly
@@ -69,22 +70,24 @@ already exists, and the installer uses three phases:
   conditions; it does not resolve them.
 - **Forced is conditional**: the exclusion kill switches remove the built-in
   competitor, not third-party web MCP servers — those must be excluded too (the
-  per-host keys cover them), or routing is not actually forced. Concretely: Pi's
-  per-server `enabled` key lets the plan disable detected web-capable competitors
-  (each prior value snapshotted for uninstall); Claude Code excludes them the same way
-  via server-level `mcp__<server>` deny rules appended to `permissions.deny`; Codex has
-  no per-server kill switch,
-  so a detected web-capable competitor makes the plan refuse the tier instead of
-  promising non-exclusive routing; OpenCode's forced is replacement, which no
-  third-party server overrides. Detection classifies a server web-capable from its
-  name plus its command/args/url — a heuristic the plan notes never hide. Forced also
-  overrides
-  explicit user choices (OpenCode's `websearch.provider`), and its deny rules affect
-  workflows beyond this project (a Claude Code deny cannot be carved out by allow
-  rules), so the plan must state the blast radius before the user approves it.
+  per-host keys cover them), or routing is not actually forced.
+  - Per-host exclusion of detected web-capable MCP servers: Pi's per-server
+    `enabled` key lets the plan disable them (each prior value snapshotted for
+    uninstall); Claude Code excludes them the same way via server-level
+    `mcp__<server>` deny rules appended to `permissions.deny`; Codex has no
+    per-server kill switch, so a detected web-capable competitor makes the plan
+    refuse the tier instead of promising non-exclusive routing; OpenCode's forced
+    is replacement, which no third-party server overrides.
+  - Detection classifies a server web-capable from its name plus its
+    command/args/url — a heuristic the plan always discloses.
+  - Blast radius: forced also overrides explicit user choices (OpenCode's
+    `websearch.provider`), and its deny rules affect workflows beyond this
+    project (a Claude Code deny cannot be carved out by allow rules), so the plan
+    must state the blast radius before the user approves it.
 - **Forced is not universally available**: where hosts.jsonc records `forced: "none"`
   (Cursor's search today), the wizard does not offer the tier — the tier-level analogue
-  of the scope rule: honor or report, never offer what cannot be delivered. Some kill
+  of the scope rule below (honor or report, never silently downgrade: never offer what
+  cannot be delivered). Some kill
   switches are session-scoped (Copilot fetch's `--deny-tool`/`--excluded-tools` flags);
   an installer cannot persist them, so the plan reports that the exclusion evaporates on
   restart and offers what persistence exists.
@@ -158,9 +161,33 @@ the artifacts below name the path where they differ.
 | Optional | Host config registering the integration: Pi's extension path appends an `npm:<package>` source to `packages` in settings.json; the MCP paths register the server (Pi's MCP entry needs `"exposure": "direct"`; the extension path needs nothing — extension tools are `direct` by Pi's own default) |
 | Preferred | The above plus a rules file for the host (file names per host in the [per-host reference](../research/control-matrix.md#per-host-reference)); the rules name the path's tool ids (`deepseek_web_search` for the extension, `mcp__deepseek__deepseek_web_search` for MCP) |
 | Forced (replacement) | OpenCode plugin options (`setDefaultWebsearch` / `fetchOverrideWebfetch`) |
-| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus the exclusion of any other web-capable MCP servers the detect phase found — Pi sets their `enabled` key to `false`; Claude Code appends server-level `mcp__<server>` deny rules to `permissions.deny` (merging with the user's own entries); Codex, lacking a per-server kill switch, refuses the tier instead; Pi's extension path additionally refuses when a web-capable `packages`/`extensions` source is listed in settings.json (no per-package kill switch exists) |
+| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus exclusion of any other web-capable MCP servers the detect phase found — host by host below |
 | Forced (de-facto) | Nothing beyond the Optional artifacts — no competitor exists |
-| Off | Codex writes the capability's raw tool name into the server entry's `disabled_tools` (host-native: the tool leaves the model's context; the user's own entries in that array are kept); Claude Code appends the capability's full tool id (`mcp__deepseek__*`) to `permissions.deny`, the same host-native removal; the other MCP entry writes the capability's false-only server-side switch instead (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); Pi's extension path writes the same switches into the `deepseekWebRetrieval` settings namespace the extension reads at load; both capabilities off refuses to install |
+| Off | A host-native removal of the capability's tool — host by host below |
+
+Forced (exclusion), host by host:
+
+- **Pi** sets each detected web-capable server's `enabled` key to `false`.
+- **Claude Code** appends server-level `mcp__<server>` deny rules to
+  `permissions.deny`, merging with the user's own entries.
+- **Codex**, lacking a per-server kill switch, refuses the tier instead.
+- **Pi's extension path** additionally refuses when a web-capable
+  `packages`/`extensions` source is listed in settings.json (no per-package kill
+  switch exists).
+
+Off, host by host:
+
+- **Codex** writes the capability's raw tool name into the server entry's
+  `disabled_tools` (host-native: the tool leaves the model's context; the user's
+  own entries in that array are kept).
+- **Claude Code** appends the capability's full tool id (`mcp__deepseek__*`) to
+  `permissions.deny` — the same host-native removal.
+- **The remaining MCP entry** (Pi's fallback) writes the capability's false-only
+  server-side switch instead (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`).
+- **Pi's extension path** writes the same switches into the
+  `deepseekWebRetrieval` settings namespace the extension reads at load.
+
+Both capabilities off refuses to install.
 
 OpenCode additionally appends `permissions` allow entries for exactly the tools it
 registers (`websearch`, `deepseek_fetch`, and `webfetch` when fetch is forced), merged
@@ -256,8 +283,13 @@ edits append arrays. Preview generation is read-only and does not reserve locks.
 
 Operation locks are directories ending in `.deepseek-web-retrieval.lock`, with
 owner PID and start time inside. Ordinary success or failure releases them. A
-killed process may leave a lock: after confirming no installer is running, inspect
-config, install record, and persistent ownership claims, restore any inconsistent
-state, then remove the reported lock directory and generate a new plan. Locks are
+killed process may leave a lock; to recover from one:
+
+1. Confirm no installer is currently running.
+2. Inspect the config, install record, and persistent ownership claims.
+3. Restore any inconsistent state.
+4. Remove the reported lock directory and generate a new plan.
+
+Locks are
 never stolen based only on age or PID. Persistent `.owner.json` claims remain a
 separate safeguard against two installations owning one shared config.

package/docs/design/search-content-design.md

@@ -0,0 +1,133 @@
+# Search content design
+
+Design note for `need_content` — DeepSeek's inline-content search flag — across the two
+model-facing adapters (the MCP server and the Pi extension). It records the parameter
+split (who decides what), the envelope arithmetic that sets the defaults, the rendering
+contract, and the per-adapter composition, so the design survives between conversations.
+The facts it builds on are in [search-inline-content.md](../research/search-inline-content.md)
+(baseline 2026-10-23); the decision record is
+[ADR-0003](../adr/0003-need-content-per-call-boolean.md). This note was verified against
+the code on 2026-10-24.
+
+## Problem
+
+The wire parameter is a boolean the repo hardcoded `false`: search results carried a
+summary digest (`summary` falling back to `snippet`) and never a page body. An agent
+needing bodies had to guess which URLs to fetch from the digests — a wrong guess is a
+silent miss. Turning the flag on naively is not safe either: DeepSeek documents **no**
+size bound for the returned `content`, host output caps run as tight as Pi's 20 KB
+MCP-path truncation (middle truncation — whole results vanish), and the 30 s default
+search timeout does not budget for the server-side page crawl the flag triggers.
+
+## The parameter split
+
+Two axes, two owners:
+
+- **The agent owns the boolean.** `need_content` is a per-call, optional tool parameter
+  on every surface where this package defines the search tool's inputs (the MCP server
+  and the Pi extension), defaulting to `false`. It rides `SearchRequest.needContent`
+  (the `oriQuestion` pattern), not the resolved options — it changes nothing in option
+  state, only what that one call sends. Task type is the biggest determinant of whether
+  content helps, and only the model knows the task; the repo's other per-call parameters
+  (`count`, fetch `maxChars`) are the precedent: always exposed, never mode-gated.
+- **The deployment owns the envelope.** Two deployment-level knobs — never tool
+  parameters — apply whenever content flows: `searchContentMaxChars` (per-result body
+  budget) and `searchContentTimeoutMs` (the timeout a content call runs on, replacing
+  `searchTimeoutMs` for that call; the per-call `timeoutMs` cap still wins if shorter).
+  The model cannot see which host caps its output, so it cannot own a budget.
+
+## The envelope
+
+Defaults from the host-cap arithmetic in the research note:
+
+- `searchContentMaxChars` defaults to **1,500**. At the default `count=10`, bodies plus
+  the ~1k chars of per-result metadata land near 16 KB — under the tightest published
+  cap (Pi's 20 KB MCP-path truncation) for Latin-script pages. CJK-heavy responses
+  measure 3 bytes per character toward that cap, so a CJK-focused deployment on a
+  20 KB host should lower the budget or the count (at 1,500 chars/result, count ≈ 13 is
+  the 20 KB ceiling even for Latin text). The native Pi extension bypasses the MCP
+  layer entirely — neither its 20 KB truncation nor its 60 s timeout applies — so that
+  deployment can afford a larger budget.
+- `searchContentTimeoutMs` defaults to **60,000** — between the 30 s search default the
+  digest path keeps and the 300 s ceiling Codex allows, because the API must fetch
+  every result page server-side before responding and documents no latency statement.
+
+The total a response can carry is budget × count plus metadata. That product is the
+deployment's arithmetic to run when tuning either knob; the core does not narrow any
+parameter's range at runtime (see Decisions).
+
+## Per-adapter composition
+
+- **MCP server**: `need_content` in the zod input schema, forwarded as
+  `needContent: need_content === true`.
+- **Pi extension**: the same parameter in the TypeBox schema (`SEARCH_PARAMETERS` stays
+  a module-level constant on both surfaces — the schema is unconditional), forwarded the
+  same way.
+- **OpenCode**: no change. The host fixes the `websearch` provider input to `query`
+  (the upstream gap that already blocks per-call `count`), so the provider stays
+  summary-only; the envelope knobs resolve through the shared pipeline and are dormant
+  there. Documented next to the count gap in
+  [opencode-v2.md](../agents/opencode-v2.md).
+- **Installer**: no artifacts change. The knob defaults are global and the deviation
+  lines on every adapter already report non-default values through the config
+  vocabulary.
+
+## Processing and rendering
+
+`processResults` is mode-agnostic: a present, non-empty `content` **replaces** the
+digest (the summary is a proxy for the body it compresses), clamped to
+`searchContentMaxChars` with an ellipsis marker when shortened; an empty, whitespace,
+or missing body — the API documents per-result absence, and `need_content: false`
+responses carry an empty string — falls back to the digest path. `searchContentMaxChars:
+0` treats the body as absent. Each result carries `contentKind: "page" | "digest"` so
+the renderer knows the source: page bodies render as Markdown indented into the list
+item (heading and list structure survive); digests stay compacted to one line, as
+summaries always were. The `structuredContent` mirror carries the same `content`
+string on hosts that read it.
+
+## What this design does not change
+
+- Billing behavior: Search bills per successful request; `need_content` is not a price
+  modifier, so a content call costs the same as a digest call (and can replace fetch
+  calls at the same per-request price).
+- The fetch tool, its `maxChars` parameter, and the two-tool architecture — a content
+  call replaces *some* fetches, not the deep-read path.
+- `maxSummaryChars`, thresholds, dedup, query composition, and degradation.
+- `MAX_RESPONSE_BYTES` (5 MiB) — still the outer guard, still erroring rather than
+  truncating; the per-result budget keeps responses far below it.
+
+## Testing
+
+Wire assertions on both model-facing adapters (`need_content: true` reaching the wire;
+`false` by default), client tests for the flag and the timeout selection
+(`contentTimeoutMs` used only when the call asks for content), `processResults` tests
+for the body-over-digest precedence, the budget clamp and marker, the empty-body
+fallback, and the zero-budget drop, and format tests for the two rendering shapes.
+
+## Rollout
+
+Shipped behind default-`false` behavior: with no configuration and no parameter use,
+every surface behaves exactly as before (the wire still says `need_content: false`).
+Deployments opt in per call by the model, per host by the two envelope knobs. No
+installer or shared-file migration; the knobs join the config vocabulary and the
+generated knob table.
+
+## Decisions (confirmed 2026-10-24)
+
+1. The boolean is a per-call tool parameter, always exposed on the MCP server and the
+   Pi extension; no config mode gates it.
+2. The envelope is deployment-only: `searchContentMaxChars` (1,500) and
+   `searchContentTimeoutMs` (60,000), never tool parameters.
+3. A page body replaces the digest; empty bodies fall back to it.
+4. `need_content` does not control other parameters — neither their availability nor
+   their value ranges. Effects may be conditional (the envelope knobs apply only when
+   content flows); domains are static. No surveyed vendor couples a content flag to
+   another parameter's range ([search-inline-content.md](../research/search-inline-content.md)),
+   and a silent runtime narrowing (say, of `count`) would be a decision the model
+   cannot see. The budget × count arithmetic is the deployment's to run.
+5. OpenCode stays summary-only until the upstream provider input widens.
+6. The descriptions state facts — mechanics, latency, price, magnitude, the fetch
+   alternative — and no usage policy. When content is worth it is the model's per-call
+   judgment (or a user's rules file per deployment), not the tool author's; if usage
+   data later shows the parameter systematically ignored or overused, that is the point
+   to add minimal steering, decided by evidence.

package/docs/integration.md

@@ -7,7 +7,8 @@ use it depends on that agent's extension points.
 CLI/terminal agents only; IDE and editor extension surfaces are out of scope. Versions are
 the latest stable CLI release checked at that baseline unless noted otherwise. `No` means no
 documented native provider or override was found in the checked version; several hosts still
-ship built-in web tools. MCP tools can add equivalent tools, but do not replace built-ins.
+ship built-in web tools. MCP (Model Context Protocol) tools can add equivalent tools, but
+do not replace built-ins.
 
 ## Mechanisms
 
@@ -20,8 +21,12 @@ ship built-in web tools. MCP tools can add equivalent tools, but do not replace
 | MCP server | Yes | Yes | Host MCP client | Shipped (`src/mcp/`; Pi, Codex, and Claude Code guides) |
 | CLI/HTTP wrapper | Yes | Yes | Host can call external tools | Not shipped |
 
-MCP is a protocol, not an agent. It is one possible transport for hosts that support MCP
-tools. `Custom tool plugin` means adding tools; it does not replace a host's built-in tools.
+Why the mechanism distinction matters: some agents expose a native websearch provider,
+some only let you add tools, and some only support MCP. A "yes" for one mechanism does
+not mean the others are supported — the adapter code and docs need to match the
+mechanism the host actually provides. MCP is a protocol, not an agent: one possible
+transport for hosts that support MCP tools, never a host itself. `Custom tool plugin`
+means adding tools; it does not replace a host's built-ins.
 
 ## Host support
 
@@ -96,12 +101,13 @@ 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`. 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.
+   guide (for Pi's extension path, `pi update --extensions`).
+
+Two init flags change what gets registered. `--pin` pins the host's package to the exact
+version being run (`deepseek-web-retrieval@X.Y.Z` in the registration); upgrading a
+pinned install therefore means re-running init with the newer CLI, since updating the
+CLI alone does not move an independently pinned host package. `--package` 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
@@ -109,12 +115,15 @@ shows the old path's removals and retains the original uninstall snapshots. Open
 native plugin and Codex's MCP path remain the same. Standalone MCP installs no longer
 require OpenCode or Pi SDKs; native adapters use the SDKs provided by their hosts.
 
-Keep install records and ownership sidecars: deleting them loses recovery information
+Keep install records and ownership sidecars (the `.owner.json` claim files the installer
+writes beside shared config files): deleting them loses recovery information
 and can cause a later init to refuse an existing registration. If an operation was
 interrupted, follow the [recovery guidance](design/installer-design.md#persistence-and-concurrent-operations)
 before retrying. For manual installations, update the package reference or checkout and
 follow the host guide rather than adopting the config through init.
 
+### Breaking changes for library consumers
+
 Code importing the core's removed `formatFetchContent` helper must migrate to
 `formatFetchedContent`, which returns both `content` and `truncated`.
 
@@ -178,12 +187,6 @@ the README Usage section only after the adapter ships. To request evaluation for
 host, [open an issue](https://github.com/gwokhou/deepseek-web-retrieval/issues) with links
 to its plugin, tool, or MCP documentation.
 
-## Why the distinction matters
-
-Some agents expose a native websearch provider, some only let you add tools, and some only
-support MCP. A "yes" for one mechanism does not mean the others are supported. The adapter
-code and docs need to match the mechanism the host actually provides.
-
 ## Adding an adapter
 
 - Register the host and its version lock in [hosts.jsonc](hosts.jsonc), then regenerate