deepseek-web-retrieval 0.2.0 → 0.3.0

package/docs/design/installer-design.md

@@ -0,0 +1,184 @@
+# Installer design
+
+Design note for the install-time flow, shipped as the `deepseek-web-retrieval init`,
+`uninstall`, and `list` subcommands for **OpenCode, Pi, and Codex**. It records how the
+[control tiers](../research/control-matrix.md) map to the artifacts the installer emits, so
+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.
+
+## Principles
+
+- **Never overwrite user configuration without the user's knowledge.** Every write is
+  shown as a plan — old value → new value, per file — and confirmed before it is
+  applied. Single-value keys are snapshotted so rollback can restore what was there.
+- **Post-install behavior and impact scope must be controllable and knowable.** The
+  installer reports what changes, which existing tools, rules, and MCP servers the
+  choice affects, what stops working, and how to undo it. If a choice cannot fully take
+  effect — a higher configuration layer outranks it — that is reported, never silently
+  dropped.
+
+## Goal
+
+At install time the user makes two decisions: per capability (search and fetch
+independently), how strongly the tools are routed — and separately, the effective scope
+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.
+- **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:
+
+1. **Detect.** Read the host config, the rules files, and the registered MCP servers.
+   Report the conflict surface: existing rules steering toward another web tool; other
+   web-capable MCP servers already on the field; array-valued keys the plan must merge
+   into rather than replace (`disabledTools`, `permissions.deny`, permissions
+   `exclude`, `disabled_tools`); and higher layers (Claude Code managed policy, Devin
+   enterprise team settings) that would outrank what the
+   installer writes.
+2. **Merge or snapshot.** Array keys merge with existing entries, recording exactly
+   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.
+
+## 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.
+- **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
+  project above user); competing MCP servers stay on the field; and approval-friction
+  asymmetry (for example Cursor's `autoAcceptWebSearch` making the built-in search
+  zero-friction) can outweigh prompt-level steering. The installer surfaces these
+  conditions; it does not resolve them.
+- **Forced is conditional**: the exclusion kill switches remove the built-in
+  competitor, not third-party web MCP servers — those must be excluded too (the
+  per-host keys cover them), or routing is not actually forced. Concretely: Pi's
+  per-server `enabled` key lets the plan disable detected web-capable competitors
+  (each prior value snapshotted for uninstall); Codex has no per-server kill switch,
+  so a detected web-capable competitor makes the plan refuse the tier instead of
+  promising non-exclusive routing; OpenCode's forced is replacement, which no
+  third-party server overrides. Detection classifies a server web-capable from its
+  name plus its command/args/url — a heuristic the plan notes never hide. Forced also
+  overrides
+  explicit user choices (OpenCode's `websearch.provider`), and its deny rules affect
+  workflows beyond this project (a Claude Code deny cannot be carved out by allow
+  rules), so the plan must state the blast radius before the user approves it.
+- **Forced is not universally available**: where hosts.jsonc records `forced: "none"`
+  (Cursor's search today), the wizard does not offer the tier — the tier-level analogue
+  of the scope rule: honor or report, never offer what cannot be delivered. Some kill
+  switches are session-scoped (Copilot fetch's `--deny-tool`/`--excluded-tools` flags);
+  an installer cannot persist them, so the plan reports that the exclusion evaporates on
+  restart and offers what persistence exists.
+
+## Scope
+
+The effective scope is a first-class install-time choice, decided by the user alongside
+the tiers — not inferred from the artifacts. The installer maps the choice onto the
+host's scope pairs (Pi's agent dir versus `.pi/`,
+Cursor's `cli-config.json` versus `.cursor/cli.json`, Claude Code's
+settings hierarchy, OpenCode's global versus project config) under three rules:
+
+- **Honor or report, never silently downgrade.** Some keys exist at only one scope:
+  Devin's `disabled_tools` is user-level only (project config allows just
+  `permissions`, `read_config_from`, and `hooks`); Cline's
+  `global-settings.json` and MCP settings file are user-scope at 0.0.13. When the
+  chosen scope cannot be honored for an artifact, the plan says so and offers the
+  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
+  `${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
+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,
+and uninstall runs the same check defensively before touching anything.
+
+## 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
+avoids: `plugin remove` deletes the plugin entry but leaves `websearch.provider`
+pointing at the removed plugin, and the user must clean up by hand.
+
+## Tier-to-artifact mapping
+
+| Choice | Artifacts |
+| --- | --- |
+| Optional | Host config registering the server, plus host-side per-tool filtering where supported (Copilot `tools` whitelist, Codex `enabled_tools`); Pi needs `"exposure": "direct"` |
+| Preferred | The above plus a rules file for the host (file names per host in the [per-host reference](../research/control-matrix.md#per-host-reference)) |
+| Forced (replacement) | OpenCode plugin options (`setDefaultWebsearch` / `fetchOverrideWebfetch`) |
+| Forced (exclusion) | The built-in competitor's kill switch (per-host keys in the per-host reference), plus the exclusion of any other web-capable MCP servers the detect phase found — Pi sets their `enabled` key to `false`; Codex, lacking a per-server kill switch, refuses the tier instead |
+| Forced (de-facto) | Nothing beyond the Optional artifacts — no competitor exists |
+| Off | The MCP entry with the capability's false-only server-side switch instead of that tool (`DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`); both capabilities off refuses to install |
+
+OpenCode additionally appends `permissions` allow entries for exactly the tools it
+registers (`websearch`, `deepseek_fetch`, and `webfetch` when fetch is forced), merged
+into any existing `permissions` array rather than replacing it.
+
+## Non-negotiables
+
+- **Cost warning on the Forced tier.** Search and Fetch are billed per successful
+  request; deterministic routing removes both the model's discretion and its restraint as
+  a cost brake. Every forced-tier plan carries a note naming the README's "Privacy and
+  cost" section.
+- **Rules content.** Name the full tool ids (`mcp__deepseek__deepseek_web_search`), state
+  trigger conditions rather than unconditional preference, and list exclusions
+  (localhost/private-network URLs go to local fetch tools; the server blocks them by
+  default).
+
+## Implementation notes
+
+- JSON edits go through `jsonc-parser` (the library behind VS Code's JSON support), so
+  comments and formatting in `opencode.jsonc` and Pi's `mcp.json` survive apply and
+  uninstall; TOML edits go through `smol-toml` and drop comments, which the plan reports
+  as a note. The hand-written JSONC stripper that predated this lived in `scripts/jsonc.ts`.
+- Install state lives per host and scope (global under
+  `~/.config/deepseek-web-retrieval/`, project under `.deepseek-web-retrieval/`); it
+  records snapshots, appended entries, created files, and created path prefixes — never
+  full file contents, so other servers' secrets stay out of the state file.
+- Re-applying over a previous init inherits the original snapshots instead of recording
+  the installer's own output as the "previous" value.
+- Verify is file-level: after apply it re-reads each written file and asserts every op
+  holds (set values in place, appended entries present, rules block present). Higher
+  layers would be a plan-time detect concern, and none of the three shipped hosts
+  documents a layer above user config, so there is nothing to check there yet.
+
+## Server-side gap (resolved)
+
+The MCP server now honors `DEEPSEEK_ENABLE_SEARCH` / `DEEPSEEK_ENABLE_FETCH`
+(false-only switches through the shared option pipeline) and refuses to start when both
+are disabled; the OpenCode plugin honors the matching `searchEnabled` / `fetchEnabled`
+options. Per-capability control is uniform across hosts, including those without
+host-side tool filtering.
+
+## Hosts without an installer story
+
+Claude Code, Cursor, Devin, GitHub Copilot, and Cline still have no
+host module; their artifacts (from the tier-to-artifact mapping) remain hand-edited
+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.

package/docs/hosts.jsonc

@@ -1,13 +1,23 @@
 {
   // Single source of truth for the host compatibility matrix. Machine consumers:
-  // scripts/render-matrix.ts (regenerates the table in docs/integration.md via
-  // `bun run docs:matrix`), scripts/ci-matrix.ts (GitHub Actions matrix),
+  // scripts/render-matrix.ts (regenerates the host table in docs/integration.md and the
+  // control matrix in docs/research/control-matrix.md via `bun run docs:matrix`),
+  // scripts/ci-matrix.ts (GitHub Actions matrix),
   // test/e2e/run.ts (Docker build args), and test/hosts.test.ts (invariants).
   // Narrative docs reference this file; they must not restate these facts.
   //
   // Mechanism ids in "paths" align with the Mechanisms table in
   // docs/integration.md: native-provider, native-override, plugin, extension,
   // mcp, wrapper. "paths" is ordered: the first entry is the recommended path.
+  // "control" aligns with docs/research/control-matrix.md: per capability, the optional/
+  // preferred tiers ("yes" or structurally "n/a") and the forced tier —
+  // "replacement" (swap the built-in implementation), "exclusion" (disable or
+  // deny the built-in competitor), "de-facto" (no built-in competitor), or
+  // "none" — plus the config key that realizes it.
+  // Version mentions inside `key` strings and per-host prose are research-provenance
+  // anchors verified at the locked version, not lock restatements; re-verify them
+  // whenever "baseline" or a host "version" changes (docs/research/control-matrix.md
+  // tracks the known drift points).
   // Rows render in file order — keep open-source hosts first, then alphabetical.
   "baseline": "2026-10-19",
   "hosts": [
@@ -20,7 +30,11 @@
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
       "paths": ["mcp", "plugin"],
-      "status": "no-adapter-yet"
+      "status": "no-adapter-yet",
+      "control": {
+        "search": { "optional": "yes", "preferred": "yes", "forced": "de-facto", "key": "no built-in web-search tool at 0.0.13 (binary-verified)" },
+        "fetch": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`disabledTools` in `~/.cline/data/settings/global-settings.json`" }
+      },
     },
     {
       "name": "codex",
@@ -31,29 +45,15 @@
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
       "paths": ["mcp"],
-      "status": "no-adapter-yet"
-    },
-    {
-      "name": "continue",
-      "display": "Continue",
-      "version": "1.5.47",
-      "license": "Apache-2.0",
-      "npm": "@continuedev/cli",
-      "nativeSearchProvider": false,
-      "nativeFetchOverride": false,
-      "paths": ["mcp"],
-      "status": "no-adapter-yet"
-    },
-    {
-      "name": "gemini",
-      "display": "Gemini",
-      "version": "0.64.0",
-      "license": "Apache-2.0",
-      "npm": "@google/gemini-cli",
-      "nativeSearchProvider": false,
-      "nativeFetchOverride": false,
-      "paths": ["mcp"],
-      "status": "no-adapter-yet"
+      "status": "supported",
+      "adapter": "src/mcp",
+      "installer": "src/installer/hosts/codex",
+      "guide": "docs/agents/codex.md",
+      "e2eScenario": "codex",
+      "control": {
+        "search": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`web_search = \"disabled\"` (top-level config.toml)" },
+        "fetch": { "optional": "yes", "preferred": "yes", "forced": "de-facto", "key": "no built-in fetch tool at 0.163.0" }
+      },
     },
     {
       "name": "opencode",
@@ -63,10 +63,15 @@
       "npm": "@opencode/cli",
       "nativeSearchProvider": true,
       "nativeFetchOverride": true,
-      "paths": ["plugin"],
+      "paths": ["native-provider", "native-override"],
       "status": "supported",
+      "control": {
+        "search": { "optional": "n/a", "preferred": "n/a", "forced": "replacement", "key": "`websearch.provider: \"deepseek\"` or plugin `setDefaultWebsearch`" },
+        "fetch": { "optional": "yes", "preferred": "yes", "forced": "replacement", "key": "`fetchOverrideWebfetch: true`" }
+      },
       "adapter": "src/opencode",
-      "guide": "docs/opencode-v2.md",
+      "installer": "src/installer/hosts/opencode",
+      "guide": "docs/agents/opencode-v2.md",
       "e2eScenario": "opencode"
     },
     {
@@ -79,8 +84,13 @@
       "nativeFetchOverride": false,
       "paths": ["mcp", "extension"],
       "status": "supported",
+      "control": {
+        "search": { "optional": "yes", "preferred": "yes", "forced": "de-facto", "key": "no built-in web tool at 1.3.0 (source-verified)" },
+        "fetch": { "optional": "yes", "preferred": "yes", "forced": "de-facto", "key": "no built-in web tool at 1.3.0 (source-verified)" }
+      },
       "adapter": "src/mcp",
-      "guide": "docs/pi.md",
+      "installer": "src/installer/hosts/pi",
+      "guide": "docs/agents/pi.md",
       "e2eScenario": "pi"
     },
     {
@@ -92,7 +102,11 @@
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
       "paths": ["mcp"],
-      "status": "no-adapter-yet"
+      "status": "no-adapter-yet",
+      "control": {
+        "search": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`permissions.deny: [\"WebSearch\"]` removes the tool from context" },
+        "fetch": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`permissions.deny: [\"WebFetch\"]`, or `CLAUDE_CODE_DISABLE_WEB_FETCH=1`" }
+      },
     },
     {
       "name": "cursor",
@@ -102,7 +116,11 @@
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
       "paths": ["mcp"],
-      "status": "no-adapter-yet"
+      "status": "no-adapter-yet",
+      "control": {
+        "search": { "optional": "yes", "preferred": "yes", "forced": "none", "key": "" },
+        "fetch": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`permissions.deny: [\"WebFetch(*)\"]`" }
+      },
     },
     {
       "name": "devin",
@@ -112,7 +130,11 @@
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
       "paths": ["mcp"],
-      "status": "no-adapter-yet"
+      "status": "no-adapter-yet",
+      "control": {
+        "search": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`disabled_tools` / `permissions.deny` in config.json" },
+        "fetch": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`disabled_tools` / `permissions.deny` in config.json" }
+      },
     },
     {
       "name": "github-copilot",
@@ -123,7 +145,11 @@
       "nativeSearchProvider": false,
       "nativeFetchOverride": false,
       "paths": ["mcp"],
-      "status": "no-adapter-yet"
+      "status": "no-adapter-yet",
+      "control": {
+        "search": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`githubMcpTools` settings (competitor ships via the bundled GitHub MCP server)" },
+        "fetch": { "optional": "yes", "preferred": "yes", "forced": "exclusion", "key": "`--deny-tool web_fetch` / `--excluded-tools` (session flags)" }
+      },
     }
   ]
 }

package/docs/integration.md

@@ -3,11 +3,11 @@
 [DeepSeek Web Retrieval](../README.md) is not tied to one host. Whether a coding agent can
 use it depends on that agent's extension points.
 
-**Research baseline:** 2026-10-19. This matrix covers CLI/terminal agents only; IDE and
-editor extension surfaces are out of scope. Versions are the latest stable CLI release
-checked on that date unless noted otherwise. `No` means no documented native provider or
-override was found in the checked version; several hosts still ship built-in web tools.
-MCP tools can add equivalent tools, but do not replace built-ins.
+**Research baseline:** the `baseline` field of [hosts.jsonc](hosts.jsonc). This matrix covers
+CLI/terminal agents only; IDE and editor extension surfaces are out of scope. Versions are
+the latest stable CLI release checked at that baseline unless noted otherwise. `No` means no
+documented native provider or override was found in the checked version; several hosts still
+ship built-in web tools. MCP tools can add equivalent tools, but do not replace built-ins.
 
 ## Mechanisms
 
@@ -15,7 +15,8 @@ MCP tools can add equivalent tools, but do not replace built-ins.
 | --- | --- | --- | --- | --- |
 | Native websearch provider | Yes | No | Host plugin API | OpenCode v2 adapter |
 | Native tool / fetch override | No | Yes | Host tool API | OpenCode v2 adapter |
-| Custom tool plugin | Yes | Yes | Host plugin API | Cline CLI/SDK and Pi; no adapter yet |
+| Custom tool plugin | Yes | Yes | Host plugin API | Cline CLI/SDK; no adapter yet |
+| Extension API | Yes | Yes | Host extension API | Pi; no adapter yet |
 | MCP server | Yes | Yes | Host MCP client | Shipped (`src/mcp/`; Pi guide first) |
 | CLI/HTTP wrapper | Yes | Yes | Host can call external tools | Not shipped |
 
@@ -30,12 +31,10 @@ Rows are sorted with open-source hosts first, then by host name alphabetically.
 
 | Host | Version checked | Open source | Native search provider | Native fetch override | Best path | Status |
 | --- | --- | --- | --- | --- | --- | --- |
-| Cline | 0.0.13 | Yes (Apache-2.0) | No | No | MCP server or plugin | No adapter yet |
-| Codex | 0.163.0 | Yes (Apache-2.0) | No | No | MCP server | No adapter yet |
-| Continue | 1.5.47 | Yes (Apache-2.0) | No | No | MCP server | No adapter yet |
-| Gemini | 0.64.0 | Yes (Apache-2.0) | No | No | MCP server | No adapter yet |
-| OpenCode | 2.0.32 | Yes (MIT) | Yes | Yes | plugin | Supported |
-| Pi | 1.3.0 | Yes (MIT) | No | No | MCP server or extension | Supported |
+| Cline | 0.0.13 | Yes (Apache-2.0) | No | No | MCP server or custom tool plugin | No adapter yet |
+| Codex | 0.163.0 | Yes (Apache-2.0) | No | No | MCP server | Supported |
+| OpenCode | 2.0.32 | Yes (MIT) | Yes | Yes | native websearch provider or native tool/fetch override | Supported |
+| Pi | 1.3.0 | Yes (MIT) | No | No | MCP server or extension API | Supported |
 | Claude Code | 2.1.303 | No | No | No | MCP server | No adapter yet |
 | Cursor | 2026.10.08 | No | No | No | MCP server | No adapter yet |
 | Devin | 3000.11.92 | No | No | No | MCP server | No adapter yet |
@@ -44,8 +43,8 @@ Rows are sorted with open-source hosts first, then by host name alphabetically.
 <!-- /generated: host-matrix -->
 
 `Open source` refers to the CLI/client code at the checked version, verified from the
-project repositories on 2026-10-19. It does not cover the hosted model service. Cline,
-Codex, Continue, and Gemini CLI are Apache-2.0; OpenCode and Pi are MIT. Claude Code and
+project repositories on 2026-10-19. It does not cover the hosted model service. Cline and
+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.
 
@@ -55,41 +54,38 @@ listed as supported only after an adapter and guide exist; for the remaining hos
 `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
 source of truth for this table; OpenCode is pinned to the adapter's tested target, not
-necessarily the latest OpenCode release.
+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),
+whose per-host reference also carries MCP registration and rules files.
 
 ## Host notes
 
+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
   exposes both a websearch provider and a fetch tool/override. See
-  [OpenCode v2](opencode-v2.md).
-- **Claude Code** — Ships built-in `WebSearch` and `WebFetch` tools. No documented native
-  provider or override; MCP servers can add tools, and hooks can block calls but do not
-  replace the fetch implementation.
-- **Codex** — MCP servers can add tools. No documented native websearch provider or fetch
-  override.
-- **Gemini** — Gemini CLI ships built-in `google_web_search` and `web_fetch` tools. No
-  documented native provider or override; MCP servers and extensions can add tools.
-- **Cursor** — Cursor CLI uses the same `mcp.json` servers as the editor. No documented
-  native provider or fetch override.
-- **GitHub Copilot** — Copilot CLI supports MCP servers; plugins can bundle MCP servers.
-  No documented native provider or fetch override.
-- **Cline** — Cline CLI supports MCP. CLI/SDK plugins can add custom tools, but the built-in
-  `fetch_web_content` tool is not replaced.
-- **Continue** — Continue CLI supports MCP servers. A built-in `search_web` tool exists, but
-  it is not a custom provider, and there is no documented fetch override.
-- **Devin** — Devin CLI supports MCP servers. Plugins bundle skills, rules, hooks, and MCP
-  servers, not arbitrary custom tools. Windsurf Desktop/Cascade is a separate IDE surface
-  and is not included in this row.
-- **Pi** — Pi 1.3.0 has native MCP support and a TypeScript extension API that can add
-  custom tools. The core ships read/bash/edit/write tools; web search/fetch are added by
-  extensions or MCP. No native websearch provider or fetch override. Supported through the
-  MCP server; see [Pi](pi.md).
+  [OpenCode v2](agents/opencode-v2.md).
+- **Claude Code** — Ships built-in `WebSearch` and `WebFetch` tools. See
+  [Claude Code](research/control-matrix.md#claude-code).
+- **Codex** — Ships a built-in `web_search` tool. Supported through the MCP server; see
+  [Codex](agents/codex.md) and [Codex in the per-host reference](research/control-matrix.md#codex).
+- **Cursor** — Uses the same `mcp.json` servers as the editor; ships built-in web search
+  and `WebFetch` tools. See [Cursor](research/control-matrix.md#cursor).
+- **GitHub Copilot** — Ships a built-in `web_fetch` tool, and web search via the bundled
+  GitHub MCP server. See [GitHub Copilot](research/control-matrix.md#github-copilot).
+- **Cline** — Ships a built-in `fetch_web_content` tool. See
+  [Cline](research/control-matrix.md#cline).
+- **Devin** — Ships built-in `web_search` and `webfetch` tools. See
+  [Devin](research/control-matrix.md#devin).
+- **Pi** — No built-in web tools; MCP plus a TypeScript extension API. Supported through
+  the MCP server; see [Pi](agents/pi.md) and [Pi in the per-host reference](research/control-matrix.md#pi).
 
 ## Roadmap
 
-- **MCP server** — shipped in `src/mcp/` with the [Pi](pi.md) guide; the broadest path for
+- **MCP server** — shipped in `src/mcp/` with the [Pi](agents/pi.md) guide; the broadest path for
   hosts that support MCP tools. Protocol compatibility across these hosts is researched in
-  [mcp-compatibility.md](mcp-compatibility.md).
+  [mcp-compatibility.md](research/mcp-compatibility.md).
 - **Host-specific guides** — added as requests and testing land; the server itself is
   host-agnostic.
 
@@ -100,16 +96,12 @@ necessarily the latest OpenCode release.
   [tools reference](https://code.claude.com/docs/en/tools-reference)
 - Codex: [MCP](https://developers.openai.com/codex/mcp),
   [CLI](https://developers.openai.com/codex/cli)
-- Gemini CLI: [tools reference](https://geminicli.com/docs/reference/tools/),
-  [MCP](https://geminicli.com/docs/tools/mcp-server/)
 - Cursor: [MCP](https://cursor.com/docs/mcp),
   [CLI changelog](https://cursor.com/docs/cli/changelog)
 - Copilot CLI: [repository](https://github.com/github/copilot-cli),
   [MCP docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)
 - Cline: [MCP](https://docs.cline.bot/mcp/mcp-overview),
   [tools reference](https://docs.cline.bot/tools-reference/all-cline-tools)
-- Continue: [MCP](https://docs.continue.dev/customize/deep-dives/mcp),
-  [agent tools](https://docs.continue.dev/ide-extensions/agent/how-it-works)
 - Devin CLI: [extensibility](https://docs.devin.ai/cli/extensibility/index),
   [MCP](https://docs.devin.ai/cli/extensibility/mcp/overview)
 - Pi: [extensions](https://pi.dev/docs/latest/extensions),
@@ -119,15 +111,13 @@ Version sources:
 
 - npm: [Claude Code](https://www.npmjs.com/package/@anthropic-ai/claude-code),
   [Codex](https://www.npmjs.com/package/@openai/codex),
-  [Gemini CLI](https://www.npmjs.com/package/@google/gemini-cli),
   [Cline CLI](https://www.npmjs.com/package/@cline/cli),
-  [Continue CLI](https://www.npmjs.com/package/@continuedev/cli),
   [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
 - Releases: [Copilot CLI](https://github.com/github/copilot-cli/releases)
 - Changelogs: [Cursor CLI](https://cursor.com/docs/cli/changelog),
   [Devin CLI](https://docs.devin.ai/cli/changelog),
   [Pi](https://pi.dev/changelog)
-- OpenCode: `2.0.32` adapter target in this repository
+- OpenCode: the adapter's tested target, locked in [hosts.jsonc](hosts.jsonc)
 
 ## Evaluating a host
 
@@ -137,11 +127,14 @@ Check the host's documentation for these questions:
 2. Can a plugin add a custom tool, or replace the built-in fetch tool?
 3. Does the host support MCP servers?
 4. Can the host call an external CLI or HTTP tool?
+5. Which rules or instruction files does the host read, and can they steer tool preference?
+6. Which built-in web tools does it ship, and can each be disabled or denied?
 
-Record the answers in `docs/<agent>.md`. Add a link from the README Usage section only after
-the adapter ships. To request evaluation for another host,
-[open an issue](https://github.com/gwokhou/deepseek-web-retrieval/issues) with links to its
-plugin, tool, or MCP documentation.
+Record the answers in the per-host reference in
+[research/control-matrix.md](research/control-matrix.md#per-host-reference). Add a link from
+the README Usage section only after the adapter ships. To request evaluation for another
+host, [open an issue](https://github.com/gwokhou/deepseek-web-retrieval/issues) with links
+to its plugin, tool, or MCP documentation.
 
 ## Why the distinction matters
 
@@ -155,5 +148,5 @@ code and docs need to match the mechanism the host actually provides.
   the host table with `bun run docs:matrix`.
 - Put shared retrieval logic in `src/core/`.
 - Put host-specific glue in `src/<agent>/`, or in `src/mcp/` for the cross-host MCP server.
-- Document setup and usage in `docs/<agent>.md`.
+- Document setup and usage in `docs/agents/<agent>.md`.
 - Link the guide from the README Usage section.