deepseek-web-retrieval 0.5.0 → 0.6.0

package/docs/agents/codex.md

@@ -27,7 +27,8 @@ For shared search/fetch limits, retries, and privacy behavior, see
 
 ## Requirements
 
-- Codex 0.163.0 or newer
+- Codex at the tested version in [`docs/hosts.jsonc`](../hosts.jsonc); init reports
+  version drift, and newer versions may require rechecking routing behavior
 - Node.js 20 or newer (`npx` runs the server)
 - 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
@@ -43,9 +44,9 @@ npx deepseek-web-retrieval init --host codex --scope global \
 ```
 
 It prints the full plan — every file, old value → new value, and notes about existing
-MCP servers — and writes nothing until you pass `--apply`. `uninstall` restores exactly
-what the plan applied (snapshots, merged entries, created files). Codex's config lives in
-`~/.codex/config.toml` at the user level only, so the server registration and kill switch
+MCP servers — and writes nothing until you pass `--apply`. `uninstall` removes recorded
+additions and restores snapshotted values that have not since been edited. Codex's config
+lives in `~/.codex/config.toml` at the user level only, so the server registration and kill switch
 are written there even for `--scope project`; the rules file follows the scope. An `off`
 capability is written as the tool's name in the server entry's `disabled_tools` array —
 Codex's own mechanism — merging with any entries you put there yourself. When `codex` is
@@ -54,6 +55,10 @@ release differs from the tested lock (see
 [hosts.jsonc](../hosts.jsonc)) — version-anchored behavior such as the kill switch may
 have drifted between the two.
 
+For an existing installer-managed setup, follow the
+[upgrade instructions](../integration.md#upgrading-existing-installs) from the original
+project directory and scope.
+
 ### Manual install
 
 Add the server to `~/.codex/config.toml`:
@@ -149,9 +154,9 @@ defaults and clamping match the other adapters. `DEEPSEEK_API_KEY` goes in `env_
 | `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
 | `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
 | `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score (0–3); results without a finite score pass at zero and are dropped at a positive threshold. |
 | `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0` to drop them. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0`/`no`/`off` to drop them. |
 | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Comma-separated; adds `-site:` operators to the query. |
 | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | Comma-separated; restricts results with `site:` operators. |
 | `DEEPSEEK_SEARCH_LANGUAGE` | unset | Adds a `lang:` operator, for example `zh,en`. |
@@ -208,7 +213,9 @@ Tested with Codex 0.163.0 on Linux over stdio.
 npx deepseek-web-retrieval uninstall --host codex --scope global
 ```
 
-This restores the previous `web_search` value, removes the `mcp_servers.deepseek` table
-and the rules block, and deletes files the installer created. Manually, remove the
+This restores snapshotted `web_search` and `mcp_servers.deepseek` values only when their
+current values still match what the installer wrote, removes the managed rules block,
+and deletes installer-created config files only when left empty. Later user edits to
+configuration values are kept and reported. For a manual installation, remove the
 `[mcp_servers.deepseek]` table, any `deepseek-web-retrieval` rules block in your
 `AGENTS.md`, and the top-level `web_search` key if it was only set for the forced tier.

package/docs/agents/opencode-v2.md

@@ -2,7 +2,7 @@
 
 OpenCode v2 adapter for [DeepSeek Web Retrieval](../../README.md).
 
-Integration mechanism: OpenCode's native plugin API (`@opencode/plugin` 2.0.32+), not MCP.
+Integration mechanism: OpenCode's native plugin API (`@opencode/plugin`), not MCP.
 
 When loaded, it adds:
 
@@ -18,7 +18,9 @@ For shared search/fetch limits, retries, and privacy behavior, see
 
 ## Requirements
 
-- OpenCode v2 with `@opencode/plugin` 2.0.32 or newer
+- 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
 - 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`
@@ -38,8 +40,9 @@ 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`. 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 everything. Search has no `preferred` tier on
-OpenCode (the provider is host-level config, never a model choice); the CLI rejects it.
+`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.
 
 ### OpenCode CLI install
 
@@ -100,9 +103,12 @@ A complete global config:
 Use the bare package name (optionally pinned) as the `package` value:
 
 ```jsonc
-"plugins": [{ "package": "deepseek-web-retrieval@0.4.0" }]
+"plugins": [{ "package": "deepseek-web-retrieval" }]
 ```
 
+Append `@X.Y.Z` to pin a published version. For an existing installer-managed setup,
+follow the [upgrade instructions](../integration.md#upgrading-existing-installs).
+
 **Global checkout**
 
 ```bash
@@ -234,7 +240,7 @@ using both an OpenCode-stored DeepSeek credential and `DEEPSEEK_API_KEY`.
 ## Uninstall
 
 With the installer CLI (restores the snapshotted `websearch.provider`, removes only the
-appended permissions, and deletes files it created):
+appended permissions, and deletes installer-created files only when they are left empty):
 
 ```bash
 npx deepseek-web-retrieval uninstall --host opencode --scope <project|global>

package/docs/agents/pi.md

@@ -25,7 +25,9 @@ shared search/fetch limits, retries, and privacy behavior, see
 
 ## Requirements
 
-- Pi 1.3.0 or newer
+- Pi with host SDKs in the `^1.3.0` peer range (`>=1.3.0 <2.0.0`); the tested
+  version is recorded in [`docs/hosts.jsonc`](../hosts.jsonc)
+- Node.js 20+ and npm when using the installer CLI or MCP fallback
 - A DeepSeek account with access to `/v1/tools/search` and `/v1/tools/fetch`
 - A funded DeepSeek account; Search and Fetch are billed per successful request
 - `DEEPSEEK_API_KEY` set in the shell that launches Pi
@@ -46,8 +48,12 @@ the extension: the plan appends `npm:deepseek-web-retrieval` to the `packages` a
 source at the next session start (the first launch fetches the package from npm;
 `pi update --extensions` refreshes it later). An off capability is written into the
 `deepseekWebRetrieval` settings namespace the extension reads at load. Pass `--path mcp`
-to install the [MCP fallback path](#the-mcp-fallback-path) instead. `uninstall` restores
-exactly what the plan applied.
+to install the [MCP fallback path](#the-mcp-fallback-path) instead. `uninstall` removes
+recorded additions and restores unchanged configuration values from their snapshots.
+
+For upgrades from 0.4.0, select `--path mcp` explicitly to retain the old path, or use
+the extension default to migrate; follow the shared
+[upgrade instructions](../integration.md#upgrading-existing-installs).
 
 ### Manual install
 
@@ -110,9 +116,9 @@ it outranks the environment and is preserved by Pi's own settings rewrites).
 | `DEEPSEEK_ENABLE_SEARCH` | `true` | Register the search tool. Only an explicit `false`/`0`/`no`/`off` disables it; at least one tool must stay enabled. |
 | `DEEPSEEK_SEARCH_COUNT` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
 | `DEEPSEEK_SEARCH_MAX_RESULTS` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. |
+| `DEEPSEEK_SEARCH_MIN_RERANK` | `0` | Drop results below this relevance score (0–3); results without a finite score pass at zero and are dropped at a positive threshold. |
 | `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `0` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0` to drop them. |
+| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `true` | Keep results whose authority is missing or unknown. Set `false`/`0`/`no`/`off` to drop them. |
 | `DEEPSEEK_SEARCH_BLOCKED_DOMAINS` | unset | Comma-separated; adds `-site:` operators to the query. |
 | `DEEPSEEK_SEARCH_INCLUDE_DOMAINS` | unset | Comma-separated; restricts results with `site:` operators. |
 | `DEEPSEEK_SEARCH_LANGUAGE` | unset | Adds a `lang:` operator, for example `zh,en`. |
@@ -175,7 +181,9 @@ With the installer CLI:
 npx deepseek-web-retrieval uninstall --host pi --scope <project|global>
 ```
 
-Or remove the source with Pi itself:
+For a manual installation, remove the source with Pi itself; use `--local` for a
+project-local install. Installer-managed installs should use `uninstall` above so
+rules, snapshots, and install records are cleaned up as well:
 
 ```bash
 pi remove npm:deepseek-web-retrieval

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.
 
@@ -215,8 +221,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,38 @@ 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`. If you pin the host's
+   package version, pass the desired `--package deepseek-web-retrieval@X.Y.Z` to init;
+   updating the CLI alone does not update an independently pinned host package.
+
+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

@@ -181,8 +181,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

@@ -129,7 +129,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 +139,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

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "deepseek-web-retrieval",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Token-efficient DeepSeek Search and Fetch for coding agents, starting with OpenCode v2.",
   "type": "module",
   "license": "MIT",

package/src/installer/apply.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { dirname } from "node:path";
+import { TOOL_VERSION } from "../version";
 import { codecFor, writeConfig } from "./formats";
 import { deepEqual, valueAt } from "./formats/value";
 import { withOperationLock } from "./operation-lock";
@@ -8,9 +9,9 @@ import { pruneEmptyDir, revertRecordedFile } from "./revert";
 import { deleteRecord, readRecord, statePathFor, writeRecord } from "./state";
 import type { ConfigOp, FileEdit, InstallerInput, InstallPlan, InstallRecord, RecordedFile } from "./types";
 
+/** What a successful apply reports; every failure mode throws instead. */
 export interface ApplyResult {
-  readonly lines: string[];
-  readonly ok: boolean;
+  readonly lines: readonly string[];
 }
 
 /** A failed apply tells callers whether retrying is safe or recovery is still needed. */
@@ -94,6 +95,7 @@ function applyLocked(plan: InstallPlan, input: InstallerInput): ApplyResult {
     lines.push(...verification.lines);
     const record: InstallRecord = {
       version: 1,
+      installerVersion: TOOL_VERSION,
       host: plan.host,
       scope: plan.scope,
       tiers: plan.tiers,
@@ -135,7 +137,7 @@ function applyLocked(plan: InstallPlan, input: InstallerInput): ApplyResult {
       error,
     );
   }
-  return { lines, ok: true };
+  return { lines };
 }
 
 function errorMessage(error: unknown): string {

package/src/installer/cli.ts

@@ -1,6 +1,7 @@
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import { applyPlan } from "./apply";
+import { TOOL_VERSION } from "../version";
+import { ApplyError, applyPlan } from "./apply";
 import { HOST_PLANNERS, HOST_VERSION_PROBES, planForHost } from "./hosts";
 import { renderPlan } from "./render";
 import { listRecords } from "./state";
@@ -12,12 +13,17 @@ const HOST_CHOICES = `<${HOSTS.join("|")}>`;
 const SCOPES: readonly Scope[] = ["project", "global"];
 const TIERS: readonly Tier[] = ["optional", "preferred", "forced", "off"];
 
+const EXIT_FAILURE = 1;
+const EXIT_USAGE = 2;
+const EXIT_RECOVERY = 3;
+
 const USAGE = `Usage:
   deepseek-web-retrieval init --host ${HOST_CHOICES} --scope <project|global> \
 --search <optional|preferred|forced|off> --fetch <optional|preferred|forced|off> \
 [--path <extension|mcp>] [--package <npm ref>] [--cwd <dir>] [--apply]
   deepseek-web-retrieval uninstall --host ${HOST_CHOICES} --scope <project|global> [--cwd <dir>]
   deepseek-web-retrieval list [--cwd <dir>]
+  deepseek-web-retrieval version
 
 init prints the full plan (every file, old value → new value) and writes nothing
 until --apply is passed. uninstall restores what the plan applied. --path picks
@@ -25,7 +31,12 @@ the integration mechanism for hosts with more than one (Pi: extension by
 default, mcp for the stdio MCP server). --package overrides the package ref
 written into host config; the Pi extension path turns it into the packages
 source (a bare name is prefixed with npm:, a ref that already starts with npm:
-is written as-is).`;
+is written as-is).
+
+Exit codes: 0 success; 1 refused or failed with nothing written (a failed apply
+is fully rolled back); 2 invalid command line; 3 recovery required — a failed
+apply could not roll back completely, follow the reported guidance before
+re-running.`;
 
 interface Flags {
   readonly values: Map<string, string>;
@@ -54,6 +65,10 @@ function parseFlags(args: readonly string[]): Flags {
         problems.push(`--${name} does not accept a value; use --${name} to enable it or omit it`);
         continue;
       }
+      if (booleans.has(name)) {
+        problems.push(`--${name} was given more than once`);
+        continue;
+      }
       booleans.add(name);
       continue;
     }
@@ -61,6 +76,10 @@ function parseFlags(args: readonly string[]): Flags {
       problems.push(`unknown flag --${name}`);
       continue;
     }
+    if (values.has(name)) {
+      problems.push(`--${name} was given more than once`);
+      continue;
+    }
     if (eq !== -1) {
       values.set(name, arg.slice(eq + 1));
       continue;
@@ -87,15 +106,23 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
   const out = io.out ?? ((line: string) => console.log(line));
   const err = io.err ?? ((line: string) => console.error(line));
   const [command, ...rest] = argv;
-  if (command === undefined || command === "help" || command === "--help") {
+  if (command === "version" || command === "--version") {
+    out(TOOL_VERSION);
+    return 0;
+  }
+  if (command === undefined) {
+    err(USAGE);
+    return EXIT_USAGE;
+  }
+  if (command === "help" || command === "--help") {
     out(USAGE);
-    return command === undefined ? 1 : 0;
+    return 0;
   }
   const flags = parseFlags(rest);
   if (flags.problems.length > 0) {
     for (const problem of flags.problems) err(`error: ${problem}`);
     err(`\n${USAGE}`);
-    return 1;
+    return EXIT_USAGE;
   }
   const cwd = resolve(flags.values.get("cwd") ?? process.cwd());
   const home = process.env.HOME ?? homedir();
@@ -114,8 +141,9 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
       return 0;
     }
     for (const record of records) {
+      const by = record.installerVersion ? ` by v${record.installerVersion}` : "";
       out(
-        `${record.host} (${record.scope}) — search=${record.tiers.search}, fetch=${record.tiers.fetch}, installed ${record.createdAt}`,
+        `${record.host} (${record.scope}) — search=${record.tiers.search}, fetch=${record.tiers.fetch}, installed ${record.createdAt}${by}`,
       );
       for (const file of record.files) out(`  ${file.created ? "created" : "modified"} ${file.file}`);
     }
@@ -136,7 +164,7 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
 
   if (command !== "init") {
     err(`Unknown command "${command}".\n\n${USAGE}`);
-    return 1;
+    return EXIT_USAGE;
   }
 
   const required = requireInput(flags, cwd, home, configHome, true);
@@ -158,17 +186,22 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
   try {
     const result = applyPlan(plan, input);
     for (const line of result.lines) out(line);
-    return result.ok ? 0 : 1;
+    return 0;
   } catch (error) {
     err(error instanceof Error ? error.message : String(error));
-    return 1;
+    return exitCodeForError(error);
   }
 }
 
+/** Maps a thrown error to its exit code; recovery is the case a script must not retry blindly. */
+export function exitCodeForError(error: unknown): number {
+  return error instanceof ApplyError && error.status === "recovery_required" ? EXIT_RECOVERY : EXIT_FAILURE;
+}
+
 function usageError(problems: readonly string[], err: (line: string) => void): number {
   for (const problem of problems) err(`error: ${problem}`);
   err(`\n${USAGE}`);
-  return 1;
+  return EXIT_USAGE;
 }
 
 /**

package/src/installer/state.ts

@@ -22,6 +22,7 @@ const operation = z.discriminatedUnion("op", [
 ]);
 const recordSchema = z.object({
   version: z.literal(1),
+  installerVersion: z.string().optional(),
   host: z.enum(["opencode", "pi", "codex"]),
   scope: z.enum(["global", "project"]),
   tiers: z.object({ search: tier, fetch: tier }),

package/src/installer/types.ts

@@ -136,6 +136,8 @@ export interface RecordedFile {
 /** Persisted install state; one record per host and scope. */
 export interface InstallRecord {
   readonly version: 1;
+  /** Version of the installer that wrote this record; absent on records from older releases. */
+  readonly installerVersion?: string;
   readonly host: HostName;
   readonly scope: Scope;
   readonly tiers: { readonly search: Tier; readonly fetch: Tier };

package/src/mcp/cli.ts

@@ -1,57 +1,14 @@
 #!/usr/bin/env node
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
-import { apiKeyFromEnv } from "../core/auth";
-import { resolveEnvOptions } from "../core/env";
-import { MISSING_API_KEY_MESSAGE } from "./auth";
-import { isJsonReplacingClient } from "./client";
-import { createDeepSeekServer, servePrecheck } from "./server";
-
-// Installer subcommands run before the server path; MCP clients spawn this bin
-// with no arguments, so the default stdio behavior is unchanged.
-const subcommand = process.argv[2];
-if (subcommand === "init" || subcommand === "uninstall" || subcommand === "list") {
+// Any argument means a human ran the CLI; MCP clients spawn this bin with no
+// arguments for the stdio server. The installer is imported statically and the
+// MCP server dynamically, so init/uninstall never load — or depend on — the
+// server's dependency graph, including when recovering from a bad server setup.
+if (process.argv.length > 2) {
   const { runInstallerCli } = await import("../installer/cli");
   process.exit(await runInstallerCli(process.argv.slice(2)));
 }
 
-// stdout is the JSON-RPC channel; all diagnostics must go to stderr.
-const env = process.env;
-if (!apiKeyFromEnv(env)) {
-  console.error(MISSING_API_KEY_MESSAGE);
-  process.exit(1);
-}
-
-const config = resolveEnvOptions(env);
-const precheck = servePrecheck(config);
-if (precheck) {
-  console.error(precheck);
-  process.exit(1);
-}
-const handle = serveStdio(() => {
-  const server = createDeepSeekServer(config, env);
-  // Fires after the handshake-era initialize exchange (the stateless era opens
-  // differently and simply never logs). One stderr line so a human run shows
-  // which client connected and whether text-only shaping kicked in; if a host
-  // renames its clientInfo, this line is where the regression becomes visible.
-  server.server.oninitialized = () => {
-    const info = server.server.getClientVersion();
-    if (info === undefined) return;
-    console.error(
-      `mcp client: ${info.name} ${info.version ?? "unknown"} — ` +
-        (isJsonReplacingClient(info.name)
-          ? "text-only results (this client replaces content with serialized structuredContent)"
-          : "text + structuredContent results"),
-    );
-  };
-  return server;
-});
-const tools = [
-  config.search.enabled ? `search (max ${config.search.maxResults} results)` : null,
-  config.fetch.enabled ? `fetch (max ${config.fetch.maxChars} chars)` : null,
-]
-  .filter(Boolean)
-  .join(", ");
-console.error(`deepseek-web-retrieval MCP server on stdio (${tools})`);
+const { serveMcp } = await import("./serve");
+serveMcp();
 
-process.on("SIGINT", () => void handle.close());
-process.on("SIGTERM", () => void handle.close());
+export {};