deepseek-web-retrieval 0.5.1 → 0.7.0

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

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

package/docs/design/installer-design.md

@@ -6,6 +6,8 @@ Design note for the install-time flow, shipped as the `deepseek-web-retrieval in
 the design survives between conversations. Research backing lives in
 [control-matrix.md](../research/control-matrix.md); host facts in [hosts.jsonc](../hosts.jsonc).
 Remaining hosts get host modules here as their guides ship.
+Examples involving other hosts describe design requirements for future modules;
+the current CLI accepts only the three shipped hosts above.
 
 ## Principles
 
@@ -27,17 +29,16 @@ of the whole install.
 - **Optional** — registered, the model picks freely.
 - **Preferred** — registered plus rules steering the model toward them.
 - **Forced** — deterministic routing (replacement, exclusion, or de-facto).
-- **Off** — the capability's tool is not registered at all. When the other capability
-  stays on, the MCP entry still lands and carries that capability's server-side
-  false-only switch (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); both off
-  refuses to install anything.
+- **Off** — the DeepSeek capability is hidden from the model through the adapter's
+  registration switch or Codex's host-side `disabled_tools` filter; the mapping below
+  describes each path. Both off refuses to install anything.
 - **Scope** — project-level (this checkout, shareable via VCS) or global (every project
   for that host on the machine).
 
 ## Stock configuration
 
 The tier definitions assume a clean host. Real installs land on configuration that
-already exists, and the installer runs three phases before anything is written:
+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
@@ -50,14 +51,15 @@ already exists, and the installer runs three phases before anything is written:
    which entries the installer appended; single-value keys (`websearch.provider`, Pi's
    `exposure`) snapshot the prior value before overwriting; files the installer creates
    are tracked as created. Nothing is written until the user approves the full plan.
-3. **Verify.** After applying, confirm the chosen tier actually holds: the deny rules
-   take effect, no higher layer overrides them, and the model sees exactly the intended
-   tools.
+3. **Verify.** After applying, re-read the files and confirm the planned values and rules
+   were written. Runtime tool visibility and model routing are checked by host-specific
+   end-to-end scenarios, not by the installer itself.
 
 ## Tier semantics against stock configuration
 
-- **Optional is inherently stock-safe**: purely additive — it appends new entries
-  without altering existing keys or values, and removes nothing. It is the safe default.
+- **Optional keeps built-in routing unchanged**: it registers the DeepSeek capability
+  without preference rules or competitor exclusion. An existing DeepSeek registration
+  may still need replacement, which the plan shows and snapshots; inspect the preview.
 - **Preferred** can conflict without any config being touched: existing rules pointing
   at another web tool produce contradictory instructions whose outcome depends on each
   host's load order (Claude Code concatenates every level; Devin ranks team above
@@ -101,16 +103,17 @@ settings hierarchy, OpenCode's global versus project config) under three rules:
   alternative — the global fallback for a kill switch, or a different tier that works
   at project scope — instead of quietly writing to the other scope.
 - **Blast radius is part of the plan.** Global scope changes every project the user
-  opens with that host; project scope is confined to one checkout but is often
-  committed, which shares the config and rules with the whole team — including the
+  opens with that host; project scope normally writes into one checkout, while shared
+  config fallbacks such as Codex's retain user-wide effects. Project-local artifacts are
+  often committed, which shares the config and rules with the whole team — including the
   `${DEEPSEEK_API_KEY}` expansion that relies on each member's environment. The impact
   report states which applies.
 - **Layers above the user still outrank the choice.** Managed, enterprise, and system
   layers override anything the installer writes at either scope; the detect phase
   reports them instead of failing silently.
 
-Uninstall is scope-aware: removing a project-scope install never touches user-scope
-entries and vice versa, and a list mode shows what is installed where. The invariant is
+Uninstall follows the files recorded for the chosen scope, including Codex's user-level
+config even for a project-scope install; list shows those actual paths. The invariant is
 guarded, not just assumed: two records for one host never claim the same file. When a
 scope choice would overlap the other scope's record — Codex's project-scope fallback
 onto `~/.codex/config.toml` beside a global install — the plan refuses with guidance,
@@ -133,10 +136,13 @@ Do not delete an ownership sidecar while its install is still active.
 
 ## Rollback
 
-Uninstall reverses exactly what the plan applied: overwritten values restore their
-snapshots, merged arrays remove only the entries the installer appended, appended rules
-content is removed, and files the installer created are deleted — nothing more, nothing
-less. The [OpenCode v2 guide](../agents/opencode-v2.md) documents the failure mode this
+Uninstall restores overwritten values from their snapshots only while the current value
+still matches what the installer wrote; later user edits are kept and reported. Merged
+arrays lose only matching entries the installer appended, and managed rules blocks are
+removed while surrounding user content is retained. Installer-created config files are
+deleted only when left empty; an empty rules file is also removed. TOML comments are not
+restored because the codec reserializes the document. The
+[OpenCode v2 guide](../agents/opencode-v2.md) documents the failure mode this
 avoids: `plugin remove` deletes the plugin entry but leaves `websearch.provider`
 pointing at the removed plugin, and the user must clean up by hand.
 
@@ -192,6 +198,14 @@ into any existing `permissions` array rather than replacing it.
   documents a layer above user config, so there is nothing to check there yet.
 - Only a bare `--apply` enables writes; assigning a value such as `--apply=false`
   is a usage error and writes nothing.
+- `--pin` is opt-in version pinning: the ref written into host config gets the
+  running CLI's version appended (`name` becomes `name@<version>`; a ref already
+  ending in a version keeps it), so a host resolves that exact release instead of
+  the latest publish. Without the flag the ref stays unpinned, byte-identical to
+  before; re-running `init --pin` from a newer CLI moves the pin. Ref identity —
+  orphan, upgrade, and unexcludable-competitor detection — compares package names
+  with the `@version` suffix stripped (`samePackageName` in ownership.ts), so a
+  pinned ref still matches the lineage an earlier init registered.
 - File verification precedes the install-record commit. A write or verification
   failure restores the pre-apply files and record and checks the restored values.
   `ApplyError.status` is `rolled_back` only after recovery and new-claim cleanup
@@ -215,8 +229,7 @@ host module; their artifacts (from the tier-to-artifact mapping) remain hand-edi
 config until a module lands here. OpenCode's `opencode plugin add` remains available but
 cannot pass options or manage snapshots; `init` supersedes it for tiered installs.
 
-
-### Persistence and concurrent operations
+## Persistence and concurrent operations
 
 Install records distinguish absent files from invalid or unreadable files. The
 reader validates version, host/scope identity, tiers, file metadata, and recorded

package/docs/integration.md

@@ -48,11 +48,11 @@ Codex are Apache-2.0; OpenCode and Pi are MIT. Claude Code and
 Cursor are proprietary. GitHub Copilot CLI and Devin CLI publish installers and docs, not
 source code, under proprietary terms.
 
-Support for the other popular CLI agents is in progress through the MCP server, which is
-shipped in `src/mcp/` and works with any host that supports MCP tools over stdio. A host is
-listed as supported only after an adapter and guide exist; for the remaining hosts,
-`No adapter yet` means the shipped MCP server already provides the path, but no guide for
-that host exists yet. All version locks live in [hosts.jsonc](hosts.jsonc), the single
+OpenCode, Pi, and Codex have supported setup guides and installer host modules. The
+MCP server in `src/mcp/` provides a possible stdio path for the remaining hosts, but
+protocol compatibility alone does not establish a tested host setup. For those rows,
+`No adapter yet` means no supported host-specific adapter or setup guide is shipped.
+All version locks live in [hosts.jsonc](hosts.jsonc), the single
 source of truth for this table; OpenCode is pinned to the adapter's tested target, not
 necessarily the latest OpenCode release. Control tiers per host and capability — optional,
 preferred, or forced routing — are researched in [control-matrix.md](research/control-matrix.md),
@@ -63,7 +63,7 @@ whose per-host reference also carries MCP registration and rules files.
 One line per host. The [per-host reference](research/control-matrix.md#per-host-reference) carries
 the details: built-in web tools and their kill switches, MCP registration, and rules files.
 
-- **OpenCode v2** — The only shipped adapter. It uses OpenCode's native plugin API and
+- **OpenCode v2** — Uses OpenCode's native plugin API and
   exposes both a websearch provider and a fetch tool/override. See
   [OpenCode v2](agents/opencode-v2.md).
 - **Claude Code** — Ships built-in `WebSearch` and `WebFetch` tools. See
@@ -82,7 +82,41 @@ the details: built-in web tools and their kill switches, MCP registration, and r
   the native extension adapter (the recommended path), with the MCP server as the fallback;
   see [Pi](agents/pi.md) and [Pi in the per-host reference](research/control-matrix.md#pi).
 
-## Roadmap
+## Upgrading existing installs
+
+For an installation managed by `init`:
+
+1. Run `npx deepseek-web-retrieval@latest list` from the original project directory,
+   using the same home and `XDG_CONFIG_HOME` as the original installation.
+2. Run `npx deepseek-web-retrieval@latest init` with the original `--host`, `--scope`,
+   `--search`, and `--fetch` values, changing only the settings you intend to change.
+   Review the plan and repeat with `--apply`; re-init preserves the original snapshots
+   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.
+
+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
+shows the old path's removals and retains the original uninstall snapshots. OpenCode's
+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
+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.
+
+Code importing the core's removed `formatFetchContent` helper must migrate to
+`formatFetchedContent`, which returns both `content` and `truncated`.
+
+## Available paths and future hosts
 
 - **MCP server** — shipped in `src/mcp/` (the fallback path in the [Pi](agents/pi.md) guide
   and the path in the [Codex](agents/codex.md) guide); the broadest route for hosts that

package/docs/research/control-matrix.md

@@ -118,7 +118,11 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
   ([rmcp_client.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/codex-mcp/src/rmcp_client.rs));
   `enabled_tools`/`disabled_tools` (verbatim raw tool-name match, filtered before
   registration so the model never sees a disabled tool; an empty `enabled_tools` allow-list
-  exposes nothing), per-tool approval modes, and output limits.
+  exposes nothing), per-tool approval modes, and output limits: MCP tool output can be
+  capped per tool via `output_token_limit` ("Token budget for one MCP tool's output,
+  before the standard 20% serialization allowance"; the default cap is not published
+  there)
+  ([mcp_types.rs at rust-v0.163.0](https://github.com/openai/codex/blob/rust-v0.163.0/codex-rs/config/src/mcp_types.rs)).
   stdio children do not inherit the parent environment (only `HOME`, `PATH`, and explicit
   `env`), so `DEEPSEEK_API_KEY` must be passed explicitly. When a tool result has
   `structuredContent`, Codex replaces the content blocks with the serialized JSON. No SSE.
@@ -146,6 +150,13 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
   tool from model requests entirely; `webfetch` has no disable config key at 2.0.32 — the
   deterministic paths are a permissions deny (`action: "webfetch"`) or a plugin
   tool-transform removal, the latter being what `fetchOverrideWebfetch` does.
+- **Tool output caps** — plugin tool results truncate at 2,000 lines / 50 KiB: every
+  tool result passes through `ToolOutput.truncate` (`MAX_LINES = 2000`,
+  `MAX_BYTES = 50 KiB`), with the full output retained to a `tool-output/` file for
+  7 days
+  ([tool-output.ts at v2.0.32](https://github.com/anomalyco/opencode/blob/v2.0.32/packages/core/src/tool-output.ts));
+  caps and model-channel behavior recorded in
+  [result-quality-passthrough.md](result-quality-passthrough.md).
 - **MCP registration** — out of scope for this host: the shipped path is the plugin
   adapter, and OpenCode's MCP support is not part of it.
 - **Rules** — `AGENTS.md` only (no CLAUDE.md fallback in v2): global
@@ -170,7 +181,9 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
   `process.env` (no forwarding), and results bypass the MCP layer entirely, so neither the
   20 KB truncation nor the 60 s request timeout applies. There is no per-extension options
   channel: the runtime config surface is the `DEEPSEEK_*` environment (the same pipeline as
-  the MCP server) plus a `deepseekWebRetrieval` settings namespace the installer writes for
+  the MCP server), the shared config file
+  (`~/.config/deepseek-web-retrieval/config.json`, layered under the environment), plus a
+  `deepseekWebRetrieval` settings namespace the installer writes for
   the off tier — Pi preserves unknown settings keys on read and on its own rewrites
   (`pi install`), verified at 1.3.0. Action methods such as `getSettings()` cannot be
   called during extension loading, so the adapter reads the settings files itself.
@@ -181,8 +194,8 @@ paths imply the available scopes; keys locked to a single scope are enumerated i
   prerequisite for every tier. SSE is rejected. Text results over 20 KB are
   middle-truncated with the full text saved to a file, and the per-request default
   timeout is 60 s. Pi is content-first for the model, with a `structuredContent`
-  fallback used only when a result has no content blocks — the one open-source host that
-  touches `structuredContent` at all — and a re-declared (not validated) tool
+  fallback used only when a result has no content blocks, unlike Codex's preference for
+  `structuredContent`, and a re-declared (not validated) tool
   `outputSchema`.
 - **Rules** — `AGENTS.md`/`CLAUDE.md` context files from the agent dir, the working
   directory, and its parents; `SYSTEM.md` replaces the system prompt and `APPEND_SYSTEM.md`

package/docs/research/mcp-compatibility.md

@@ -117,7 +117,10 @@ differences:
    content-first, falling back to `structuredContent` only when a result has no content
    blocks (verified in `tools.ts` at v1.3.0). No `outputSchema` is declared: the SDK
    rejects text-only results for a tool with a declared schema, and no host in the
-   matrix validates the schema anyway.
+   matrix validates the schema anyway. The per-host model-channel facts behind this —
+   which of `content`/`structuredContent` provably reaches the model on each host,
+   native adapter paths included — are recorded in
+   [result-quality-passthrough.md](result-quality-passthrough.md).
 2. **stdio is the universal transport.** Every host in the matrix launches stdio servers
    with the same conceptual JSON (`mcpServers` → `command`/`args`/`env`), differing only in
    file location and cosmetic field names. stdio needs no OAuth and no URL config, and the
@@ -129,7 +132,7 @@ differences:
    1.0.81+). A v1.x-built server still works today — modern clients fall back to the legacy
    handshake — but it can never offer the stateless era; v2 serves both from one entry
    point.
-4. **Streamable HTTP only for a hosted deployment.** All nine hosts support it (with
+4. **Streamable HTTP only for a hosted deployment.** All seven MCP hosts surveyed here support it (with
    different `type` strings: `http`, `streamable-http`, `streamableHttp`), and OAuth 2.1
    resource-server behavior (RFC 9728 metadata) then applies; prefer pre-registered clients
    over the now-deprecated Dynamic Client Registration.
@@ -139,6 +142,10 @@ differences:
    truncation, environment passing, output caps, and per-host approval surfaces; consult
    it per host rather than this summary.
 
+These protocol findings describe compatibility at the research baseline, not completed
+end-to-end support for every host. The shipped server exposes stdio; supported setup
+guides and installer coverage are listed in the [integration model](../integration.md).
+
 ## Sources
 
 ### Specification and SDKs