deepseek-web-retrieval 0.8.0 → 0.10.0

package/docs/adr/0001-refuse-drift-between-plan-and-apply.md

@@ -1,8 +1,10 @@
 # Refuse drift between plan and apply
 
+Status: Accepted — shipped in 0.3.0 (see [CHANGELOG](../../CHANGELOG.md)).
+
 The installer's plan previews the previous value each `set` op replaces, and the
 install record must snapshot exactly that value for uninstall to restore. We
-decided that apply re-verifies the current value at every `set` path still
+decided that apply re-verifies that the current value at every `set` path still
 equals the plan-time `previous`, refuses with guidance when it does not
 ("config changed since the plan was rendered — re-run"), and records the
 plan-time snapshot — so the preview, the secret guard, and the record all
@@ -12,9 +14,11 @@ describe one snapshot taken once, at plan time.
 
 - **Inherit the plan-time snapshot silently.** Single source, but apply would
   overwrite an edit made between plan review and `--apply` without the user's
-  knowledge — violating the installer's first principle.
+  knowledge — violating the [installer's first
+  principle](../design/installer-design.md#principles).
 - **Keep re-deriving `previous` at write time** (previous status quo). The
-  preview and the record can disagree, and the secret guard, which checks the
+  preview and the record can disagree, and the secret guard (the
+  `withSecretGuard` wrapper in `src/installer/hosts/index.ts`), which checks the
   plan-time value, no longer covers what is actually recorded.
 
 ## Consequences

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

@@ -1,6 +1,10 @@
 # Share one config base layer across hosts
 
-The option pipeline was single-sourced, but the channels feeding it were per
+Status: Accepted — shipped in 0.7.0 (see [CHANGELOG](../../CHANGELOG.md)).
+
+The option pipeline was single-sourced — names, defaults, and clamping resolved through
+one chain (`src/core/constants.ts` → `src/core/env.ts` → `src/core/options.ts`) — 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

package/docs/adr/0003-need-content-per-call-boolean.md

@@ -0,0 +1,49 @@
+# Expose need_content as the agent's per-call boolean
+
+Status: Accepted — shipped in 0.10.0 (see [CHANGELOG](../../CHANGELOG.md)).
+
+DeepSeek's Search API accepts a `need_content` boolean — return each result's page body —
+that this repo had hardcoded `false` since the first release: the wire field arrived, the
+pipeline dropped it, and no search result ever carried a page body
+([search-inline-content.md](../research/search-inline-content.md)). The same research
+pinned why the value cannot travel alone: DeepSeek documents no size bound for the
+returned content, host output caps run as tight as Pi's 20 KB MCP-path truncation, and
+the 30 s default search timeout does not budget for a server-side page crawl. We decided
+that the boolean itself becomes a per-call tool parameter on the model-facing surfaces
+(the MCP server and the Pi extension), defaulting to `false`, while the deployment owns
+two envelope-only knobs that apply whenever content flows: `searchContentMaxChars` (the
+per-result body budget, default 1,500) and `searchContentTimeoutMs` (the timeout a
+content call runs on, default 60 s). Neither knob is ever a tool parameter — the model
+cannot see which host caps its output, so it cannot own a budget.
+
+## Considered Options
+
+- **A tristate `searchContent: off | on | auto` config mode** gating whether the
+  parameter is exposed. The wire value is a boolean; `auto` is invented vocabulary, and
+  no per-call parameter in this repo (`count`, fetch `maxChars`) is mode-gated. The
+  `on` state's only real beneficiary is OpenCode, whose `websearch` provider input the
+  host fixes to `query` — the same upstream gap that already blocks per-call `count`
+  ([opencode-v2.md](../agents/opencode-v2.md)).
+- **Default-on inline content** (Jina's architecture). DeepSeek documents no size bound
+  for `content`; a default `count=10` response at typical page sizes runs 30–110 KB
+  against host caps that truncate near 20 KB, and per-request billing makes the call
+  free, not the context bloat.
+- **The previous status quo** (hardcoded `false`). An agent that needs page bodies must
+  guess from summaries which URLs to fetch; a wrong guess is a silent miss.
+
+## Consequences
+
+The model decides per call whether a search carries page bodies — one round-trip
+replaces search-plus-fetch when recall matters, and summaries stay the default when
+they suffice. A page body replaces its result's digest, clamped to
+`searchContentMaxChars` with an ellipsis marker, so a response's content volume is
+bounded by budget × count and can never blow a host cap by an undocumented server-side
+size. The text channel renders bodies as indented Markdown that keeps heading and list
+structure; digests stay one-line. `searchContentMaxChars: 0` drops bodies entirely (the
+digest renders) — a deployment kill switch that still pays the slower call, so leaving
+the parameter false is the better tool for the model. A result whose content comes back
+empty — the API documents per-result absence — falls back to its summary, so a content
+call degrades to today's output rather than to nothing. OpenCode stays summary-only
+until its provider input widens upstream. Design detail (budget arithmetic, rendering,
+per-adapter composition) lives in the
+[search content design note](../design/search-content-design.md).

package/docs/agents/claude-code.md

@@ -38,20 +38,23 @@ The quickest option is the installer CLI:
 
 ```bash
 npx deepseek-web-retrieval init --host claude-code --scope project \
-  --search <tier> --fetch <tier>
+  --search <optional|preferred|forced|off> --fetch <optional|preferred|forced|off>
 ```
 
 It prints the full plan — every file, old value → new value, and notes about existing MCP
 servers — and writes nothing until you pass `--apply`. Add `--pin` to register the exact
 version of the CLI you are running instead of the always-latest package name. `uninstall`
 removes recorded additions and restores snapshotted values that have not since been edited.
+
 `--scope project` registers the server in `./.mcp.json` (shareable via VCS) and writes tier
 artifacts to `./.claude/settings.json` and `./CLAUDE.md`; `--scope global` uses
 `~/.claude.json`, `~/.claude/settings.json`, and `~/.claude/CLAUDE.md` instead — the two
 scopes use disjoint files, so both can coexist. An `off` capability is written as the
 tool's full id in the `permissions.deny` array — Claude Code's own mechanism, which removes
 the tool from the model's context while the server keeps running — merging with any entries
-you put there yourself. When `claude` is on PATH, `init` also probes `claude --version` and
+you put there yourself.
+
+When `claude` is on PATH, `init` also probes `claude --version` and
 adds a plan note when the installed release differs from the tested lock (see
 [hosts.jsonc](../hosts.jsonc)) — version-anchored behavior such as the deny rules may have
 drifted between the two.
@@ -168,9 +171,16 @@ The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek
 
 The search tool accepts an optional `original_question` argument — the user's question in
 their own words — forwarded as DeepSeek's `ori_question` to sharpen search intent; omit it
-when the query already stands alone.
-
-Tool output is capped at 25k tokens by default (`MAX_MCP_OUTPUT_TOKENS`), and successful
+when the query already stands alone. It also takes an optional `count` (1–50) for the call,
+and the fetch tool takes an optional `maxChars` (0–1,000,000) per-call output budget; each
+overrides the configured default for that call, so the model can widen a truncated fetch or
+ask for more results without rephrasing the query. When configured domain or language
+operators change the query actually sent, the result text opens with
+`Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
+
+Tool output is capped at 25k tokens by default (`MAX_MCP_OUTPUT_TOKENS`, a Claude Code
+environment setting), and successful
 text results longer than 50,000 characters are saved to a file and referenced — not
 dropped silently.
 
@@ -249,7 +259,7 @@ one vocabulary pair, one pipeline. `—` marks host-integration entries the file
 | Claude Code | locked in [`docs/hosts.jsonc`](../hosts.jsonc) |
 | MCP revision | `2026-07-28` negotiated; server accepts `2024-11-05`–`2026-07-28` |
 | MCP SDK | `@modelcontextprotocol/server` 2.3.1 |
-| Runtime | Node.js 20+ (stdio) |
+| Runtime | Node.js 20 or newer (stdio) |
 | DeepSeek API | `/v1/tools/search`, `/v1/tools/fetch` |
 
 Tested with Claude Code at the `docs/hosts.jsonc` lock on Linux over stdio: the keyless

package/docs/agents/codex.md

@@ -17,10 +17,10 @@ The tools appear in Codex as `mcp__deepseek__deepseek_web_search` and
 [Control tiers](#control-tiers) for routing it away.
 
 The server recognizes Codex's MCP client identity (`codex-mcp-client`, declared in the
-initialize handshake) and returns text-only tool results: Codex replaces the content
-blocks with the serialized `structuredContent` JSON when it is present, so for Codex the
-structured mirror is omitted and the model reads clean Markdown. Other clients receive
-both the text and `structuredContent`.
+initialize handshake) and returns text-only tool results for it. Codex replaces the
+content blocks with the serialized `structuredContent` JSON when it is present, so for
+Codex the structured mirror is omitted and the model reads clean Markdown. Other
+clients receive both the text and `structuredContent`.
 
 For shared search/fetch limits, retries, and privacy behavior, see
 [General behavior](../../README.md#general-behavior).
@@ -42,7 +42,7 @@ The quickest option is the installer CLI:
 
 ```bash
 npx deepseek-web-retrieval init --host codex --scope global \
-  --search <tier> --fetch <tier>
+  --search <optional|preferred|forced|off> --fetch <optional|preferred|forced|off>
 ```
 
 It prints the full plan — every file, old value → new value, and notes about existing
@@ -117,7 +117,7 @@ built-in fetch tool, so the tiers differ per capability:
 
 | Capability | Optional | Preferred | Forced |
 | --- | --- | --- | --- |
-| Search | Tools registered; the built-in `web_search` stays available | Plus an AGENTS.md rules block steering the model to `mcp__deepseek__deepseek_web_search` | Exclusion: `web_search = "disabled"` at the top level of config.toml |
+| Search | Tools registered; the built-in `web_search` stays available | Plus an AGENTS.md rules block steering the model to `mcp__deepseek__deepseek_web_search` | Exclusion: `web_search = "disabled"` at the top level of `config.toml` |
 | Fetch | Tools registered | Plus the rules block | De-facto: no built-in fetch tool exists |
 
 The installer maps each tier to these artifacts. `AGENTS.md` rules land in
@@ -148,7 +148,13 @@ The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek
 
 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.
+when the query already stands alone. It also takes an optional `count` (1–50) for the call,
+and the fetch tool takes an optional `maxChars` (0–1,000,000) per-call output budget; each
+overrides the configured default for that call, so the model can widen a truncated fetch or
+ask for more results without rephrasing the query. When configured domain or language
+operators change the query actually sent, the result text opens with
+`Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
 
 ## Configuration
 
@@ -225,7 +231,7 @@ one vocabulary pair, one pipeline. `—` marks host-integration entries the file
 | Codex | locked in [`docs/hosts.jsonc`](../hosts.jsonc) |
 | MCP revision | `2025-06-18` negotiated (`mcp_2026_07_28` behind a flag); server accepts `2024-11-05`–`2026-07-28` |
 | MCP SDK | `@modelcontextprotocol/server` 2.3.1 |
-| Runtime | Node.js 20+ (stdio) |
+| Runtime | Node.js 20 or newer (stdio) |
 | DeepSeek API | `/v1/tools/search`, `/v1/tools/fetch` |
 
 Tested with Codex 0.163.0 on Linux over stdio.

package/docs/agents/domain.md

@@ -14,7 +14,7 @@ If any of these files don't exist, **proceed silently**. Don't flag their absenc
 
 Single-context repo (most repos):
 
-```
+```text
 /
 ├── CONTEXT.md
 ├── docs/adr/
@@ -25,7 +25,7 @@ Single-context repo (most repos):
 
 Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
 
-```
+```text
 /
 ├── CONTEXT-MAP.md
 ├── docs/adr/                          ← system-wide decisions

package/docs/agents/issue-tracker.md

@@ -5,7 +5,7 @@ Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all o
 ## Conventions
 
 - **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
-- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **Read an issue**: `gh issue view <number> --comments` for reading; add `--json body,labels,comments` (with `--jq` to project fields) when scripting.
 - **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
 - **Comment on an issue**: `gh issue comment <number> --body "..."`
 - **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
@@ -15,7 +15,7 @@ Infer the repo from `git remote -v`; `gh` does this automatically when run insid
 
 ## Pull requests as a triage surface
 
-**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+**PRs as a request surface: no.** _(Maintainers only: set to `yes` if this repo treats external PRs as feature requests; the `/triage` skill reads this flag.)_
 
 When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
 
@@ -39,7 +39,7 @@ Used by `/wayfinder`. The **map** is a single issue with **child** issues as tic
 
 - **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
 - **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
-- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
-- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). Read the resulting block count from the issue's REST representation — `gh api repos/<owner>/<repo>/issues/<n> --jq .issue_dependencies_summary.blocked_by` (open blockers only, the live gate; `gh issue view --json` does not expose this field). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0` read as above, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
 - **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
-- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer to the map's Decisions-so-far (link the resolved child; include the gist URL if the resolving session created one).

package/docs/agents/opencode-v2.md

@@ -22,7 +22,7 @@ For configuration layers, the full knob mapping, and defaults, see the
 
 - 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
+- Node.js 20 or newer 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`
@@ -41,11 +41,14 @@ 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`. 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
-model choice); the CLI rejects it.
+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.
+
+> [!NOTE]
+> Search has no `preferred` tier on OpenCode: the provider is host-level config, never
+> a model choice, so the CLI rejects it.
 
 ### OpenCode CLI install
 
@@ -176,9 +179,20 @@ 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)).
+DeepSeek's optional `ori_question` is not sent on this path, and the model cannot request a
+per-call result count or inline page content (`need_content`): OpenCode's `websearch` tool
+input is fixed to `query` (verified unchanged at `@opencode/schema` 2.1.4, the drift check
+above the 2.0.32 lock), so the provider has no channel for either — search stays
+summary-only here while the MCP server and the Pi extension expose both parameters. Upstream requests:
+[anomalyco/opencode#58635](https://github.com/anomalyco/opencode/issues/58635) (session linkage)
+and [#58636](https://github.com/anomalyco/opencode/issues/58636) (per-call `count`); see the
+[research note](../research/ori-question-sourcing.md). The fetch tools are not constrained:
+they accept an optional per-call `maxChars` (0–1,000,000) that overrides the configured
+`fetchMaxChars` for one call, so the model can widen the budget after seeing a
+`[content truncated]` marker. The effective-query header and query degradation notes have no
+channel on this path either — OpenCode's result shape is closed — but degradation still runs,
+and a query that exceeds the length limit and cannot be degraded further surfaces as an
+error.
 
 ## Configuration
 
@@ -202,14 +216,14 @@ 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. |
+| `searchEnabled` | `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the DeepSeek search provider at all. In `options`, only an explicit `false` disables it; the environment twin also accepts `0`/`no`/`off`. |
 | `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. |
+| `allowUnknownAuthority` | `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. In `options`, only an explicit `false` disables it; the environment twin also accepts `0`/`no`/`off`. |
+| `blockedDomains` | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Add `-site:` operators to the search query. |
+| `includeDomains` | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | 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. |
@@ -225,8 +239,8 @@ environment or file channel.
 | `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. |
+| `fetchAllowedDomains` | `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset | If non-empty, only these hosts and subdomains may be fetched. |
+| `fetchBlockedDomains` | `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | unset | 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

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
@@ -110,14 +135,20 @@ The search tool accepts an optional `original_question` input — the user's que
 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.
+session access, so there a blank input simply omits the parameter. The search tool also
+takes an optional `count` (1–50) for the call, and the fetch tool an optional `maxChars`
+(0–1,000,000) per-call output budget; each overrides the configured default for that call.
+When configured domain or language operators change the query actually sent, the result text
+opens with `Searched for: <effective query>` (plus any degradation applied to fit the API's
+128-character limit), so the model can attribute results to the configuration in effect.
 
 ## Configuration
 
 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`)
@@ -157,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
 
@@ -167,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 |
@@ -192,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 |
@@ -84,6 +86,7 @@ drift from the code (`bun run docs:matrix` regenerates it; CI checks it).
 | `fetchBlockPrivateHosts` | `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | true |
 | `maxRetries` | `DEEPSEEK_MAX_RETRIES` | 2 |
 | `retryBaseDelayMs` | `DEEPSEEK_RETRY_BASE_DELAY_MS` | 250 |
+| `baseUrl` | `DEEPSEEK_BASE_URL` | https://api.deepseek.com |
 
 <!-- /generated: knob-table -->
 
@@ -96,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
@@ -105,5 +109,18 @@ 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, 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
   domains are dropped (and reported by `config`).

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