deepseek-web-retrieval 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to this project are documented here, one sentence per item.
 
+## 0.10.0
+
+- Add `need_content` as an optional per-call boolean on the MCP and Pi search tools: `true` attaches each result's page body as Markdown (structure-preserving, indented into the result list) in place of its summary, and a missing body falls back to the summary; OpenCode's fixed provider input keeps that path summary-only.
+- Add the `searchContentMaxChars` (1,500 characters) and `searchContentTimeoutMs` (60,000 ms) deployment knobs — the content envelope every `need_content` call runs inside, never tool parameters, recorded in ADR-0003 and the search content design note.
+- State the `need_content` facts — excerpt length, latency, price, and the fetch alternative — in the tool and parameter descriptions, with both full-page routes named side by side, and no usage policy: when content is worth it stays the model's per-call judgment.
+- Extend the inline-content research note with the vendor reading that no surveyed architecture couples a content flag to another parameter's value range: budgets are static-range, conditional-effect.
+- Add a keyless `pi-mock` e2e leg that drives a real Pi session search with `need_content: true` against the mock upstream and asserts the flag reached the wire and the page body reached the model, with the digest legs now also asserting `need_content: false` by default.
+
 ## 0.9.0
 
 - Accept an optional per-call `count` (1–50) on the MCP and Pi search tools and an optional per-call `maxChars` (0–1,000,000) on every adapter's fetch, each overriding the configured value for that one call.
@@ -13,7 +21,7 @@ All notable changes to this project are documented here, one sentence per item.
 
 ## 0.8.0
 
-- Add Claude Code as a supported host: an MCP-only integration registered in `.mcp.json` (project scope) or `~/.claude.json` (user scope), with a full installer host module (plan/apply/uninstall, both scopes), a `docs/agents/claude-code.md` guide, a version probe with drift note, and managed-policy detection that reports a `managed-settings.json` layer outranking the install.
+- Add Claude Code as a supported host: an MCP-only integration registered in `.mcp.json` (project scope) or `~/.claude.json` (Claude Code's user scope — global scope in this repo's vocabulary), with a full installer host module (plan/apply/uninstall, both scopes), a `docs/agents/claude-code.md` guide, a version probe with drift note, and managed-policy detection that reports a `managed-settings.json` layer outranking the install.
 - Route Claude Code tiers through its own settings files: forced capabilities deny the built-in `WebSearch`/`WebFetch` via `permissions.deny` in `.claude/settings.json` or `~/.claude/settings.json` (merged with the user's entries), off capabilities deny the full `mcp__deepseek__*` tool ids, and preferred writes a rules block into `CLAUDE.md`; web-capable competitor servers are excluded under forced via server-level `mcp__<server>` deny rules instead of refusing the tier.
 - Add a billed `claude-code` Docker e2e scenario that runs headless `claude -p` prompts with DeepSeek as the LLM over its Anthropic-compatible endpoint (single key for both legs) and asserts the deny-based kill switch keeps the built-in tools out of the session, plus installer/reinit coverage of the new host in the keyless scenarios.
 - Guard Pi's global config files with the shared-file ownership sidecar, and release claims before deleting the install record on uninstall, so two installs under different config homes can no longer claim the same `~/.pi/agent` file.

package/README.md

@@ -4,8 +4,9 @@
 
 Search the web and fetch pages as Markdown through
 [DeepSeek's APIs](https://api-docs.deepseek.com/guides/search), using a **native OpenCode
-plugin**, a **native Pi extension**, or **MCP for Codex and Claude Code**. All four share
-the same retrieval core, with results formatted for each host.
+plugin**, a **native [Pi](https://pi.dev/) extension** (Pi, the open-source coding agent),
+or **MCP for Codex and Claude Code**. All four share the same retrieval core, with results
+formatted for each host.
 
 This is an unofficial community project, not affiliated with DeepSeek or the supported
 host projects.
@@ -16,8 +17,9 @@ Jump to: [Features](#features) · [Quickstart](#quickstart) · [Usage](#usage)
 
 ## Features
 
-- **One package, four hosts** — a native OpenCode v2 plugin, a native Pi extension,
-  and a stdio MCP server for Codex and Claude Code, all sharing one retrieval core
+- **One package, four hosts** — a native plugin for OpenCode v2 (the 2.x series), a
+  native Pi extension, and a stdio MCP server for Codex and Claude Code, all sharing one
+  retrieval core
 - **Routing control per tool** — search and fetch are set independently to optional,
   preferred, forced, or off; the tier table in Usage explains each
 - **Review before anything is written** — `init` prints the full plan and writes only
@@ -59,8 +61,9 @@ Choose your host:
 | Claude Code | MCP server over stdio in `.mcp.json` or `~/.claude.json` | [Claude Code guide](docs/agents/claude-code.md) |
 
 Set `DEEPSEEK_API_KEY` in the environment that launches your host; OpenCode can also
-use its stored DeepSeek key. Run `init` for your host to preview a configuration — the
-command shape is the quickstart's; each host guide shows its recommended tiers.
+use its stored DeepSeek key. Run `init` for your host to preview a configuration — take
+the quickstart command and swap `--host` and `--scope` for your host's values; each host
+guide shows its recommended tiers.
 
 `--search` and `--fetch` each pick a tier — how strongly the host steers toward the
 DeepSeek tool, chosen independently per capability:
@@ -87,7 +90,8 @@ Files:
     upsert marked rules block
 
 Notes:
-  - Codex stdio children do not inherit the parent environment, so the entry forwards DEEPSEEK_API_KEY and every DEEPSEEK_* option variable explicitly via env_vars; shell-set knobs reach the server without hand-editing config.toml (the shared config file works without any forwarding).
+  - Codex stdio children do not inherit the parent environment, so the entry forwards DEEPSEEK_API_KEY and every DEEPSEEK_* option variable explicitly via env_vars; shell-set knobs reach the server without hand-editing config.toml.
+  - The shared config file needs no forwarding at all: the server reads it itself.
   - Rules block upserted in ~/.codex/AGENTS.md; Codex reads ~/.codex/AGENTS.md plus every AGENTS.md from the project root to the cwd.
   - Shared config ownership is recorded in ~/.codex/.config.toml.deepseek-web-retrieval.codex.owner.json; uninstall releases it. Keep this local metadata with the config.
 
@@ -116,19 +120,21 @@ What this adapter layer adds on top of the
 own capabilities (Markdown-only output, no JavaScript rendering, no private networks or
 binary files, per-request billing) are documented there.
 
-| Default | Value | Knob |
+| Setting | Default | Knob |
 | --- | --- | --- |
 | Results per search | 10 | `count` |
 | Fetch output cap | 16,000 characters | `fetchMaxChars` |
 | Search summary cap | 1,200 characters | `maxSummaryChars` |
-| Request timeout, body read included | 30 s | `searchTimeoutMs` / `fetchTimeoutMs` |
+| Inline content cap, per result (when requested) | 1,500 characters | `searchContentMaxChars` |
+| Request timeout, body read included | 30 s (60 s for `need_content` calls) | `searchTimeoutMs` / `fetchTimeoutMs` / `searchContentTimeoutMs` |
 | Transient retries | 2 (range 0–5) | `maxRetries` |
 
 ### Search
 
-- Requests summaries only (`need_content: false`, falling back from `summary` to
-  `snippet`); full page content never enters the results. A summary the cap shortens ends
-  with an ellipsis.
+- Requests summaries by default (`need_content: false`, falling back from `summary` to
+  `snippet`); a summary the cap shortens ends with an ellipsis. When a call sets
+  `need_content: true`, each result instead carries its page body as Markdown, clamped
+  to `searchContentMaxChars` per result — a missing body falls back to the summary.
 - Deduplicates URLs; an empty result set is normal, not an error.
 - Builds `blockedDomains`, `includeDomains`, and `language` into query operators (part of
   DeepSeek's documented search syntax). A combined query over the API's 128-character limit
@@ -144,8 +150,11 @@ binary files, per-request billing) are documented there.
   the Pi extension), the tool accepts an optional `original_question`: the user's
   question in their own words. It is forwarded as DeepSeek's `ori_question`, trimmed
   and truncated to 128 characters; on the Pi extension, a blank input falls back to the
-  most recent user message in the session. Those paths also take an optional per-call
-  `count` (1–50) overriding the configured result count for that call.
+  most recent user message in the session.
+- The same paths also take an optional per-call `count` (1–50), overriding the
+  configured result count for that one call, and an optional per-call `need_content`
+  boolean requesting page bodies in the results (see
+  [search content design](docs/design/search-content-design.md)).
 
 ### Fetch
 
@@ -228,8 +237,8 @@ bun run check
 ```
 
 Use `bun run lint:fix` to apply Biome's safe lint fixes and formatting. See
-[CONTRIBUTING.md](CONTRIBUTING.md) for development checks, e2e scenarios, and
-[automated tag releases](CONTRIBUTING.md#automated-releases).
+[CONTRIBUTING.md](CONTRIBUTING.md) for development checks and e2e scenarios, and
+[automated tag releases](CONTRIBUTING.md#automated-releases-maintainers).
 
 The test suite mocks the DeepSeek API and the OpenCode and Pi host APIs; real API calls
 require a funded DeepSeek account. Shared retrieval logic lives in `src/core/`; adapters

package/dist/cli.js

@@ -16,7 +16,7 @@ var __export = (target, all) => {
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 
 // src/core/constants.ts
-var DEFAULT_API_BASE_URL = "https://api.deepseek.com", SEARCH_ENDPOINT_PATH = "/v1/tools/search", FETCH_ENDPOINT_PATH = "/v1/tools/fetch", SEARCH_ENDPOINT, FETCH_ENDPOINT, DEFAULT_SEARCH_COUNT = 10, DEFAULT_MAX_RESULTS = 10, DEFAULT_MIN_RERANK = 0, DEFAULT_MIN_AUTHORITY = 0, DEFAULT_MAX_SUMMARY_CHARS = 1200, DEFAULT_FETCH_MAX_CHARS = 16000, MAX_FETCH_CHARS = 1e6, MAX_SEARCH_COUNT = 50, DEFAULT_TIMEOUT_MS = 30000, MIN_TIMEOUT_MS = 1000, MAX_TIMEOUT_MS = 120000, MAX_QUERY_CHARS = 128, MAX_ORI_QUESTION_CHARS = 128, MAX_URL_CHARS = 8192, MAX_ERROR_BODY_CHARS = 2000, MAX_RESPONSE_BYTES, FETCH_TRUNCATION_MARKER = `
+var DEFAULT_API_BASE_URL = "https://api.deepseek.com", SEARCH_ENDPOINT_PATH = "/v1/tools/search", FETCH_ENDPOINT_PATH = "/v1/tools/fetch", SEARCH_ENDPOINT, FETCH_ENDPOINT, DEFAULT_SEARCH_COUNT = 10, DEFAULT_MAX_RESULTS = 10, DEFAULT_MIN_RERANK = 0, DEFAULT_MIN_AUTHORITY = 0, DEFAULT_MAX_SUMMARY_CHARS = 1200, DEFAULT_SEARCH_CONTENT_MAX_CHARS = 1500, DEFAULT_SEARCH_CONTENT_TIMEOUT_MS = 60000, DEFAULT_FETCH_MAX_CHARS = 16000, MAX_FETCH_CHARS = 1e6, MAX_SEARCH_COUNT = 50, DEFAULT_TIMEOUT_MS = 30000, MIN_TIMEOUT_MS = 1000, MAX_TIMEOUT_MS = 120000, MAX_QUERY_CHARS = 128, MAX_ORI_QUESTION_CHARS = 128, MAX_URL_CHARS = 8192, MAX_ERROR_BODY_CHARS = 2000, MAX_RESPONSE_BYTES, FETCH_TRUNCATION_MARKER = `
 
 [content truncated]`, DEFAULT_API_KEY_SOURCE = "auto", DEFAULT_MAX_RETRIES = 2, MAX_RETRIES = 5, DEFAULT_RETRY_BASE_DELAY_MS = 250, MAX_RETRY_DELAY_MS = 1e4, API_KEY_ENV = "DEEPSEEK_API_KEY", BASE_URL_ENV = "DEEPSEEK_BASE_URL", ENABLE_SEARCH_ENV = "DEEPSEEK_ENABLE_SEARCH", ENABLE_FETCH_ENV = "DEEPSEEK_ENABLE_FETCH", SEARCH_LOCALIZATION_ENV = "DEEPSEEK_SEARCH_LOCALIZATION";
 var init_constants = __esm(() => {
@@ -162,6 +162,8 @@ function resolveSearchOptions(input) {
     language: optionalText(input?.language),
     localization: localizationValue(input?.searchLocalization),
     maxSummaryChars: clampInt(input?.maxSummaryChars, DEFAULT_MAX_SUMMARY_CHARS, 0, 1e6),
+    contentMaxChars: clampInt(input?.searchContentMaxChars, DEFAULT_SEARCH_CONTENT_MAX_CHARS, 0, 1e6),
+    contentTimeoutMs: clampInt(input?.searchContentTimeoutMs, DEFAULT_SEARCH_CONTENT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
     timeoutMs: clampInt(input?.searchTimeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
     enabled: input?.searchEnabled !== false
   };
@@ -279,6 +281,8 @@ var init_config_summary = __esm(() => {
     { key: "language", read: (o) => o.search.language },
     { key: "searchLocalization", read: (o) => o.search.localization },
     { key: "maxSummaryChars", read: (o) => o.search.maxSummaryChars },
+    { key: "searchContentMaxChars", read: (o) => o.search.contentMaxChars },
+    { key: "searchContentTimeoutMs", read: (o) => o.search.contentTimeoutMs },
     { key: "searchTimeoutMs", read: (o) => o.search.timeoutMs },
     { key: "fetchMaxChars", read: (o) => o.fetch.maxChars },
     { key: "fetchAllowedDomains", read: (o) => o.fetch.allowedDomains },
@@ -4170,7 +4174,9 @@ No results found.` : "No results found.";
     const marker = formatQualityMarker(result);
     const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})${marker ? ` ${marker}` : ""}`];
     if (result.content) {
-      lines.push(`   ${result.content.replaceAll(`
+      lines.push(result.contentKind === "page" ? result.content.split(`
+`).map((line) => `   ${line}`).join(`
+`) : `   ${result.content.replaceAll(`
 `, " ")}`);
     }
     if (result.published !== undefined) {
@@ -4354,9 +4360,14 @@ function processResults(raw, options) {
       continue;
     }
     seen.add(url);
-    const rawContent = optionalText2(item.summary) ?? optionalText2(item.snippet) ?? "";
-    const cutContent = truncate(rawContent, options.maxSummaryChars);
-    const content = cutContent && charCount(rawContent) > options.maxSummaryChars ? `${cutContent}…` : cutContent;
+    const body = optionalText2(item.content);
+    const digest = optionalText2(item.summary) ?? optionalText2(item.snippet) ?? "";
+    const fromPage = body !== undefined && options.contentMaxChars > 0;
+    const rawContent = fromPage && body !== undefined ? body : digest;
+    const contentBudget = fromPage ? options.contentMaxChars : options.maxSummaryChars;
+    const cutContent = truncate(rawContent, contentBudget);
+    const content = cutContent && charCount(rawContent) > contentBudget ? `${cutContent}…` : cutContent;
+    const contentKind = fromPage ? "page" : "digest";
     const published = parsePublished(item.date);
     const title = optionalText2(item.title);
     const rerankScore = typeof rerank === "number" && Number.isFinite(rerank) ? rerank : undefined;
@@ -4365,7 +4376,7 @@ function processResults(raw, options) {
     results.push({
       url,
       ...title ? { title } : {},
-      ...content ? { content } : {},
+      ...content ? { content, contentKind } : {},
       ...published !== undefined ? { published } : {},
       ...rerankScore !== undefined ? { rerankScore } : {},
       ...authorityScore !== undefined ? { authority: authorityScore } : {},
@@ -4620,12 +4631,13 @@ async function searchWeb(query, options, request) {
   }
   const composed = composeSearchQuery(trimmed, options);
   const builtQuery = composed.query;
-  const timeout = effectiveTimeout(options.timeoutMs, request.timeoutMs);
+  const needContent = request.needContent === true;
+  const timeout = effectiveTimeout(needContent ? options.contentTimeoutMs : options.timeoutMs, request.timeoutMs);
   const oriQuestion = oriQuestionValue(request.oriQuestion);
   const payload = await postJson(apiUrl(request.baseUrl, SEARCH_ENDPOINT_PATH), {
     query: builtQuery,
     count: options.count,
-    need_content: false,
+    need_content: needContent,
     ...oriQuestion === undefined ? {} : { ori_question: oriQuestion },
     ...options.localization === undefined ? {} : { localization: options.localization }
   }, "DeepSeek Search", { ...request, timeoutMs: timeout });
@@ -4705,6 +4717,8 @@ function envOptionsReport(env = process.env) {
   putText(options, "searchLocalization", env);
   putNumber(options, "maxSummaryChars", env, warnings);
   putNumber(options, "searchTimeoutMs", env, warnings);
+  putNumber(options, "searchContentMaxChars", env, warnings);
+  putNumber(options, "searchContentTimeoutMs", env, warnings);
   putNumber(options, "fetchMaxChars", env, warnings);
   putDomains(options, "fetchAllowedDomains", env, warnings);
   putDomains(options, "fetchBlockedDomains", env, warnings);
@@ -4792,6 +4806,8 @@ var init_env = __esm(() => {
     minAuthority: "DEEPSEEK_SEARCH_MIN_AUTHORITY",
     maxSummaryChars: "DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS",
     searchTimeoutMs: "DEEPSEEK_SEARCH_TIMEOUT_MS",
+    searchContentMaxChars: "DEEPSEEK_SEARCH_CONTENT_MAX_CHARS",
+    searchContentTimeoutMs: "DEEPSEEK_SEARCH_CONTENT_TIMEOUT_MS",
     fetchMaxChars: "DEEPSEEK_FETCH_MAX_CHARS",
     fetchTimeoutMs: "DEEPSEEK_FETCH_TIMEOUT_MS",
     maxRetries: "DEEPSEEK_MAX_RETRIES",
@@ -6222,7 +6238,7 @@ var init_package = __esm(() => {
   package_default = {
     $schema: "https://json.schemastore.org/package.json",
     name: "deepseek-web-retrieval",
-    version: "0.9.0",
+    version: "0.10.0",
     description: "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
     type: "module",
     license: "MIT",
@@ -6326,13 +6342,14 @@ var init_package = __esm(() => {
 });
 
 // src/core/descriptions.ts
-var FETCH_SERVICE_LIMITS = "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported.", FETCH_OUTPUT_TRUNCATED = "Output is truncated to the configured size; the optional maxChars parameter raises or lowers that size for one call.", SEARCH_RANKED_FILTERED = "Results are ranked by relevance and source authority, deduplicated by URL, and capped at the configured maximum.", SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error.", SEARCH_QUERY_OPERATORS = "Use site:/-site: operators in the query to include or exclude domains, and after:/before: with a year or date (e.g. after:2025-06-01) to filter by publish time; the full query must stay within 128 characters.", SEARCH_TOOL_DESCRIPTION, FETCH_TOOL_DESCRIPTION, SEARCH_QUERY_PARAMETER = "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:, after:, before:).", SEARCH_ORI_QUESTION_PARAMETER, FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.", FETCH_MAX_CHARS_PARAMETER, SEARCH_COUNT_PARAMETER;
+var FETCH_SERVICE_LIMITS = "DeepSeek does not render JavaScript and cannot reach private networks; PDFs, images, and other binary files are unsupported.", FETCH_OUTPUT_TRUNCATED = "Output is truncated to the configured size; the optional maxChars parameter raises or lowers that size for one call.", SEARCH_RANKED_FILTERED = "Results are ranked by relevance and source authority, deduplicated by URL, and capped at the configured maximum.", SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error.", SEARCH_QUERY_OPERATORS = "Use site:/-site: operators in the query to include or exclude domains, and after:/before: with a year or date (e.g. after:2025-06-01) to filter by publish time; the full query must stay within 128 characters.", SEARCH_TOOL_DESCRIPTION, FETCH_TOOL_DESCRIPTION, SEARCH_QUERY_PARAMETER = "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:, after:, before:).", SEARCH_ORI_QUESTION_PARAMETER, FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.", FETCH_MAX_CHARS_PARAMETER, SEARCH_COUNT_PARAMETER, SEARCH_NEED_CONTENT_PARAMETER;
 var init_descriptions = __esm(() => {
-  SEARCH_TOOL_DESCRIPTION = "Search the web with DeepSeek's in-house search engine and return a short, filtered result " + "list (title, URL, summary). " + `${SEARCH_RANKED_FILTERED} ` + `${SEARCH_EMPTY_IS_NORMAL} ` + `${SEARCH_QUERY_OPERATORS} ` + "To read a full page, pass a result URL to the deepseek_fetch tool.";
+  SEARCH_TOOL_DESCRIPTION = "Search the web with DeepSeek's in-house search engine and return a short, filtered result " + "list (title, URL, summary). " + `${SEARCH_RANKED_FILTERED} ` + `${SEARCH_EMPTY_IS_NORMAL} ` + `${SEARCH_QUERY_OPERATORS} ` + "To read one full page in depth, pass a result URL to the deepseek_fetch tool; to carry each result's " + "page body in this response, set need_content to true.";
   FETCH_TOOL_DESCRIPTION = "Fetch one web page as clean Markdown through DeepSeek's Fetch API. " + `${FETCH_SERVICE_LIMITS} ` + `${FETCH_OUTPUT_TRUNCATED}`;
   SEARCH_ORI_QUESTION_PARAMETER = "The user's original question or task that triggered this search, in the user's own words rather than a " + "reformulated query. Optional; 1-128 characters, and longer values are truncated.";
   FETCH_MAX_CHARS_PARAMETER = "Optional per-call character budget for this fetch, 0-1,000,000, title included. Overrides the configured cap " + "for this call; a [content truncated] marker is appended when the output is cut.";
   SEARCH_COUNT_PARAMETER = "Optional number of results for this call, 1-50. Overrides the configured count and result cap for this call; " + "billing is per request, not per result.";
+  SEARCH_NEED_CONTENT_PARAMETER = "Optional; set true to attach each result's page body as Markdown — an excerpt clamped to a configured per-result " + "budget, not a full page — in place of its short summary. Slower per call (DeepSeek fetches the result pages) and " + "priced the same per request; for a full page, call deepseek_fetch.";
 });
 
 // src/mcp/server.ts
@@ -6346,12 +6363,13 @@ function createDeepSeekServer(config, env = process.env, client = retrievalClien
       description: SEARCH_TOOL_DESCRIPTION,
       inputSchema: SEARCH_INPUT,
       annotations: { readOnlyHint: true }
-    }, async ({ query, original_question, count }, ctx) => {
+    }, async ({ query, original_question, count, need_content }, ctx) => {
       try {
         const request = requestContext(config, requireApiKey(env), ctx.mcpReq.signal);
         const outcome = await client.searchWeb(query, withPerCallCount(config.search, count), {
           ...request,
-          oriQuestion: original_question
+          oriQuestion: original_question,
+          needContent: need_content === true
         });
         return callResult(server, ctx, formatSearchResults(outcome.results, outcome), {
           results: outcome.results.map(toStructuredResult)
@@ -6409,7 +6427,8 @@ var init_server = __esm(() => {
   SEARCH_INPUT = z2.object({
     query: z2.string().min(1).describe(SEARCH_QUERY_PARAMETER),
     original_question: z2.string().optional().describe(SEARCH_ORI_QUESTION_PARAMETER),
-    count: z2.number().int().min(1).max(MAX_SEARCH_COUNT).optional().describe(SEARCH_COUNT_PARAMETER)
+    count: z2.number().int().min(1).max(MAX_SEARCH_COUNT).optional().describe(SEARCH_COUNT_PARAMETER),
+    need_content: z2.boolean().optional().describe(SEARCH_NEED_CONTENT_PARAMETER)
   });
   FETCH_INPUT = z2.object({
     url: z2.string().min(1).describe(FETCH_URL_PARAMETER),

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.
@@ -176,7 +179,8 @@ 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`), and successful
+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.
 
@@ -255,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
@@ -231,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
 
@@ -177,8 +180,10 @@ 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, and the model cannot request a
-per-call result count: OpenCode's `websearch` tool input is fixed to `query` (verified unchanged
-at 2.1.4), so the provider has no channel for either. Upstream requests:
+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:
@@ -186,7 +191,8 @@ they accept an optional per-call `maxChars` (0–1,000,000) that overrides the c
 `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 failures that cannot degrade surface as errors.
+and a query that exceeds the length limit and cannot be degraded further surfaces as an
+error.
 
 ## Configuration
 
@@ -210,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. |
@@ -233,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