deepseek-web-retrieval 0.2.0 → 0.4.0

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

@@ -0,0 +1,29 @@
+# Refuse drift between plan and apply
+
+The installer's plan previews the previous value each `set` op replaces, and the
+install record must snapshot exactly that value for uninstall to restore. We
+decided that apply re-verifies the current value at every `set` path still
+equals the plan-time `previous`, refuses with guidance when it does not
+("config changed since the plan was rendered — re-run"), and records the
+plan-time snapshot — so the preview, the secret guard, and the record all
+describe one snapshot taken once, at plan time.
+
+## Considered Options
+
+- **Inherit the plan-time snapshot silently.** Single source, but apply would
+  overwrite an edit made between plan review and `--apply` without the user's
+  knowledge — violating the installer's first principle.
+- **Keep re-deriving `previous` at write time** (previous status quo). The
+  preview and the record can disagree, and the secret guard, which checks the
+  plan-time value, no longer covers what is actually recorded.
+
+## Consequences
+
+A legitimate user edit between plan and apply costs one re-run of `init`. In
+exchange, "never overwrite user configuration without the user's knowledge"
+holds unconditionally, including the window between plan review and apply.
+
+The record's snapshots are re-derived at apply time rather than copied from the
+plan; because the drift check runs immediately before, the two are provably
+equal, so the record does describe the plan-time snapshot without a separate
+copy step.

package/docs/agents/codex.md

@@ -0,0 +1,193 @@
+# Codex
+
+Codex adapter for [DeepSeek Web Retrieval](../../README.md).
+
+Integration mechanism: MCP server over stdio, registered in Codex's `~/.codex/config.toml`.
+Codex negotiates MCP revision `2025-06-18` (with `mcp_2026_07_28` behind a feature flag); the
+server also accepts clients from `2024-11-05` through `2026-07-28`, so the same build works
+for other MCP hosts (see [the compatibility research](../research/mcp-compatibility.md)).
+
+When registered, it adds:
+
+- A `deepseek_web_search` tool backed by DeepSeek Search
+- A `deepseek_fetch` tool backed by DeepSeek Fetch
+
+The tools appear in Codex as `mcp__deepseek__deepseek_web_search` and
+`mcp__deepseek__deepseek_fetch`. Codex's built-in `web_search` tool is not replaced; see
+[Control tiers](#control-tiers) for routing it away.
+
+For shared search/fetch limits, retries, and privacy behavior, see
+[General behavior](../../README.md#general-behavior).
+
+## Requirements
+
+- Codex 0.163.0 or newer
+- 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
+- `DEEPSEEK_API_KEY` set in the shell that launches Codex
+
+## Install
+
+The quickest option is the installer CLI:
+
+```bash
+npx deepseek-web-retrieval init --host codex --scope global \
+  --search <tier> --fetch <tier>
+```
+
+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
+are written there even for `--scope project`; the rules file follows the scope.
+
+### Manual install
+
+Add the server to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.deepseek]
+command = "npx"
+args = ["-y", "deepseek-web-retrieval"]
+env_vars = ["DEEPSEEK_API_KEY"]
+```
+
+> [!NOTE]
+> `env_vars` is load-bearing. Codex stdio children do not inherit the parent
+> environment — only `HOME`, `PATH`, and a few system variables — so the key must be
+> forwarded explicitly and set in the shell that launches Codex. Literal values can go
+> in an `env` table instead if you prefer them in the file.
+
+To disable one capability, set it in the `env` table:
+
+```toml
+[mcp_servers.deepseek.env]
+DEEPSEEK_ENABLE_SEARCH = "false"   # or DEEPSEEK_ENABLE_FETCH; at least one must stay on
+```
+
+### Local checkout
+
+```bash
+git clone https://github.com/gwokhou/deepseek-web-retrieval.git
+cd deepseek-web-retrieval && bun install && bun run build
+```
+
+```toml
+[mcp_servers.deepseek]
+command = "node"
+args = ["/absolute/path/to/deepseek-web-retrieval/dist/cli.js"]
+env_vars = ["DEEPSEEK_API_KEY"]
+```
+
+## Control tiers
+
+Codex ships a built-in `web_search` tool (default `cached` mode, an OpenAI index) and no
+built-in fetch tool, so the tiers differ per capability:
+
+| Capability | Optional | Preferred | Forced |
+| --- | --- | --- | --- |
+| Search | Tools registered; the built-in `web_search` stays available | Plus an AGENTS.md rules block steering the model to `mcp__deepseek__deepseek_web_search` | Exclusion: `web_search = "disabled"` at the top level of config.toml |
+| Fetch | Tools registered | Plus the rules block | De-facto: no built-in fetch tool exists |
+
+The installer maps each tier to these artifacts. `AGENTS.md` rules land in
+`~/.codex/AGENTS.md` (user) or `./AGENTS.md` (project); Codex reads both plus every
+`AGENTS.md` from the project root to the cwd.
+
+> [!WARNING]
+> The `[tools] web_search = <bool>` form parses but is a **silent no-op** at 0.163.0 —
+> only the top-level `web_search` key controls the tool. The installer refuses to plan
+> when it finds the trap in your config.
+
+## Authentication
+
+`DEEPSEEK_API_KEY` is the only source; MCP has no host credential store. It is forwarded
+to the server via `env_vars` and read per request, sent only to `api.deepseek.com` as a
+Bearer token. Without it the server exits at startup with a message on stderr.
+
+## Usage
+
+Ask naturally:
+
+```text
+Search the web for the latest Codex MCP config changes and cite the sources.
+Fetch https://developers.openai.com/codex/mcp and summarize the config keys.
+```
+
+The model calls `mcp__deepseek__deepseek_web_search` or `mcp__deepseek__deepseek_fetch`.
+
+## Configuration
+
+Set these in the server's `env` table. Values map onto the shared option pipeline, so
+defaults and clamping match the other adapters. `DEEPSEEK_API_KEY` goes in `env_vars`.
+
+### Search
+
+| Env variable | Default | Description |
+| --- | --- | --- |
+| `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_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_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`. |
+| `DEEPSEEK_SEARCH_MAX_SUMMARY_CHARS` | `1200` | Per-result summary cap, 0–1,000,000. |
+| `DEEPSEEK_SEARCH_TIMEOUT_MS` | `30000` | Search timeout, 1,000–120,000 ms. |
+
+### Fetch
+
+| Env variable | Default | Description |
+| --- | --- | --- |
+| `DEEPSEEK_ENABLE_FETCH` | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
+| `DEEPSEEK_FETCH_MAX_CHARS` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
+| `DEEPSEEK_FETCH_TIMEOUT_MS` | `30000` | Fetch timeout, 1,000–120,000 ms. |
+| `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset | If set, only these hosts and subdomains may be fetched. |
+| `DEEPSEEK_FETCH_BLOCKED_DOMAINS` | unset | Always block these hosts and subdomains. Blocked wins over allowed. |
+| `DEEPSEEK_FETCH_BLOCK_PRIVATE_HOSTS` | `true` | Reject localhost, private IPs, `.local`, `.internal`, and similar hosts. |
+
+### Credentials and retries
+
+| Env variable | Default | Description |
+| --- | --- | --- |
+| `DEEPSEEK_API_KEY` | required | DeepSeek API key, forwarded via `env_vars`. The server refuses to start without it. |
+| `DEEPSEEK_MAX_RETRIES` | `0` | Retries for 408, 425, 429, and 5xx responses, 0–5. |
+| `DEEPSEEK_RETRY_BASE_DELAY_MS` | `250` | Base delay for exponential backoff. `Retry-After` is honored up to 10 seconds. |
+
+## Troubleshooting
+
+| Error or symptom | What to do |
+| --- | --- |
+| Server fails to start or `HTTP 401` from the tools | `DEEPSEEK_API_KEY` must be set in the shell that launches Codex and forwarded via `env_vars`; stdio children do not inherit the environment. |
+| Both tools missing after startup | At least one of `DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH` must stay enabled; the server exits when both are false. |
+| Search still uses the built-in tool under the forced tier | The kill switch is the top-level `web_search = "disabled"` key; the `[tools] web_search` form is a no-op at 0.163.0. |
+| Tool results look like raw JSON | When a result has `structuredContent`, Codex replaces the content blocks with the serialized JSON — expected behavior. |
+| Tools time out around 60 s | Raise `tool_timeout_sec` for the server entry if you raise `DEEPSEEK_*_TIMEOUT_MS` beyond it. |
+| Routing not exclusive | Other `[mcp_servers.*]` entries stay registered and are noted in the plan. Under a forced tier, an entry that looks web-capable makes `init` refuse — Codex has no per-server kill switch, so remove the server or restrict its tools via `disabled_tools` by hand. |
+| `HTTP 402`, `HTTP 429` | Top up the DeepSeek account; wait, reduce concurrency, or set `DEEPSEEK_MAX_RETRIES`. |
+| Fetch fails on localhost or an internal URL | Use a local fetch tool; DeepSeek cannot reach private networks. |
+
+## Compatibility
+
+| Component | Version |
+| --- | --- |
+| Codex | locked in [`docs/hosts.jsonc`](../hosts.jsonc) |
+| MCP revision | `2025-06-18` negotiated (`mcp_2026_07_28` behind a flag); server accepts `2024-11-05`–`2026-07-28` |
+| MCP SDK | `@modelcontextprotocol/server` 2.3.1 |
+| Runtime | Node.js 20+ (stdio) |
+| DeepSeek API | `/v1/tools/search`, `/v1/tools/fetch` |
+
+Tested with Codex 0.163.0 on Linux over stdio.
+
+## Uninstall
+
+```bash
+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
+`[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/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

package/docs/agents/issue-tracker.md

@@ -0,0 +1,45 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --comments`, filtering comments by `jq` and also fetching labels.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh pr list --state open --json number,title,body,labels,author,authorAssociation,comments` then keep only `authorAssociation` of `CONTRIBUTOR`, `FIRST_TIME_CONTRIBUTOR`, or `NONE` (drop `OWNER`/`MEMBER`/`COLLABORATOR`).
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/docs/{opencode-v2.md → agents/opencode-v2.md}

@@ -1,6 +1,6 @@
 # OpenCode v2
 
-OpenCode v2 adapter for [DeepSeek Web Retrieval](../README.md).
+OpenCode v2 adapter for [DeepSeek Web Retrieval](../../README.md).
 
 Integration mechanism: OpenCode's native plugin API (`@opencode/plugin` 2.0.32+), not MCP.
 
@@ -14,7 +14,7 @@ The built-in `webfetch` is not replaced by default. Set `fetchOverrideWebfetch`
 if you want all Markdown fetches to go through DeepSeek.
 
 For shared search/fetch limits, retries, and privacy behavior, see
-[General behavior](../README.md#general-behavior).
+[General behavior](../../README.md#general-behavior).
 
 ## Requirements
 
@@ -28,7 +28,22 @@ No build step is required. OpenCode loads the TypeScript entry point directly.
 
 ## Install
 
-The quickest option is the OpenCode CLI:
+The quickest option is the installer CLI:
+
+```bash
+npx deepseek-web-retrieval init --host opencode --scope <project|global> \
+  --search <optional|forced|off> --fetch <optional|preferred|forced|off>
+```
+
+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 CLI install
+
+The next option is the OpenCode CLI:
 
 ```bash
 opencode plugin add github:gwokhou/deepseek-web-retrieval
@@ -82,11 +97,10 @@ A complete global config:
 
 **Published npm package**
 
-Once the package is published to npm, use the bare package name (optionally
-pinned) as the `package` value:
+Use the bare package name (optionally pinned) as the `package` value:
 
 ```jsonc
-"plugins": [{ "package": "deepseek-web-retrieval@0.2.0" }]
+"plugins": [{ "package": "deepseek-web-retrieval@0.4.0" }]
 ```
 
 **Global checkout**
@@ -157,11 +171,12 @@ Set these in the plugin's `options` object.
 
 | Option | Default | Description |
 | --- | --- | --- |
+| `searchEnabled` | `true` | Register the DeepSeek search provider at all. Only an explicit `false` disables it. |
 | `count` | `10` | Results requested from DeepSeek, 1–50. Billing is per request, not per result. |
-| `maxResults` | `5` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `minRerank` | `1.5` | Drop results below this relevance score. DeepSeek scores are 0–3. |
-| `minAuthority` | `2` | Drop known authorities below this tier. Authority is 0–4. |
-| `allowUnknownAuthority` | `false` | Keep results whose authority is missing or unknown. |
+| `maxResults` | `10` | Results returned to the model after filtering, 0–50. `0` returns no results. |
+| `minRerank` | `0` | Drop results below this relevance score. DeepSeek scores are 0–3. |
+| `minAuthority` | `0` | Drop known authorities below this tier. Authority is 0–4. |
+| `allowUnknownAuthority` | `true` | Keep results whose authority is missing or unknown. Only an explicit `false` disables it. |
 | `blockedDomains` | `[]` | Add `-site:` operators to the search query. |
 | `includeDomains` | `[]` | Restrict results with `site:` operators. |
 | `language` | unset | Add a `lang:` operator, for example `zh,en`. |
@@ -173,6 +188,7 @@ Set these in the plugin's `options` object.
 
 | Option | Default | Description |
 | --- | --- | --- |
+| `fetchEnabled` | `true` | Register any DeepSeek fetch tooling (the separate tool and the webfetch override). |
 | `fetchMaxChars` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
 | `fetchTimeoutMs` | `30000` | Fetch timeout, 1,000–120,000 ms. |
 | `fetchOverrideWebfetch` | `false` | Replace the built-in `webfetch`. |
@@ -208,7 +224,7 @@ Set these in the plugin's `options` object.
 
 | Component | Version |
 | --- | --- |
-| OpenCode / plugin API | locked in [`docs/hosts.jsonc`](hosts.jsonc) |
+| OpenCode / plugin API | locked in [`docs/hosts.jsonc`](../hosts.jsonc) |
 | Runtime | Bun (provided by OpenCode) |
 | DeepSeek API | `/v1/tools/search`, `/v1/tools/fetch` |
 
@@ -217,6 +233,13 @@ 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):
+
+```bash
+npx deepseek-web-retrieval uninstall --host opencode --scope <project|global>
+```
+
 For a CLI install, remove the config entry with:
 
 ```bash

package/docs/{pi.md → agents/pi.md}

@@ -1,11 +1,11 @@
 # Pi
 
-Pi adapter for [DeepSeek Web Retrieval](../README.md).
+Pi adapter for [DeepSeek Web Retrieval](../../README.md).
 
 Integration mechanism: MCP server over stdio, launched from Pi's `mcp.json`. Pi 1.3.0
 negotiates MCP revision `2025-11-25`; the server also accepts clients from `2024-11-05`
 through `2026-07-28`, so the same build works for other MCP hosts (see
-[the compatibility research](mcp-compatibility.md)).
+[the compatibility research](../research/mcp-compatibility.md)).
 
 When registered, it adds:
 
@@ -16,7 +16,7 @@ The tools appear in Pi as `mcp__deepseek__deepseek_web_search` and
 `mcp__deepseek__deepseek_fetch`. Pi's built-in tools are not replaced.
 
 For shared search/fetch limits, retries, and privacy behavior, see
-[General behavior](../README.md#general-behavior).
+[General behavior](../../README.md#general-behavior).
 
 ## Requirements
 
@@ -28,6 +28,25 @@ For shared search/fetch limits, retries, and privacy behavior, see
 
 ## Install
 
+The quickest option is the installer CLI:
+
+```bash
+npx deepseek-web-retrieval init --host pi --scope <project|global> \
+  --search <optional|preferred|forced|off> --fetch <optional|preferred|forced|off>
+```
+
+It prints the full plan — every file, old value → new value, and notes about existing
+MCP servers and the `exposure` requirement — and writes nothing until you pass `--apply`.
+JSON edits preserve comments. `uninstall` restores exactly what the plan applied. Under a
+forced tier, other registered MCP servers that look web-capable are disabled
+(`enabled: false`, prior value snapshotted) so DeepSeek routing is exclusive, and
+`uninstall` restores them. The
+tiers follow the [control matrix](../research/control-matrix.md): Pi ships no built-in web
+tool, so forced is de-facto for both capabilities and `off` writes
+`DEEPSEEK_ENABLE_SEARCH`/`DEEPSEEK_ENABLE_FETCH` into the server's env block.
+
+### Manual install
+
 Add the server to `~/.pi/agent/mcp.json` (user) or `.pi/mcp.json` (project):
 
 ```jsonc
@@ -61,7 +80,8 @@ or a new session.
 
 ### Local checkout
 
-Until the package is published to npm, run the server from a checkout:
+To run the server from a checkout instead of the published package (for
+development):
 
 ```bash
 git clone https://github.com/gwokhou/deepseek-web-retrieval.git
@@ -110,11 +130,12 @@ defaults and clamping match the OpenCode adapter.
 
 | Env variable | Default | Description |
 | --- | --- | --- |
+| `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` | `5` | Results returned to the model after filtering, 0–50. `0` returns no results. |
-| `DEEPSEEK_SEARCH_MIN_RERANK` | `1.5` | Drop results below this relevance score. DeepSeek scores are 0–3. |
-| `DEEPSEEK_SEARCH_MIN_AUTHORITY` | `2` | Drop known authorities below this tier. Authority is 0–4. |
-| `DEEPSEEK_SEARCH_ALLOW_UNKNOWN_AUTHORITY` | `false` | Keep results whose authority is missing or unknown. Set `true`/`1`. |
+| `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_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_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`. |
@@ -124,7 +145,8 @@ defaults and clamping match the OpenCode adapter.
 ### Fetch
 
 | Env variable | Default | Description |
-| --- | --- | --- |
+| --- | --- |
+| `DEEPSEEK_ENABLE_FETCH` | `true` | Register the fetch tool. Same false-only semantics as `DEEPSEEK_ENABLE_SEARCH`. |
 | `DEEPSEEK_FETCH_MAX_CHARS` | `16000` | Maximum characters returned, including the title, 0–1,000,000. |
 | `DEEPSEEK_FETCH_TIMEOUT_MS` | `30000` | Fetch timeout, 1,000–120,000 ms. |
 | `DEEPSEEK_FETCH_ALLOWED_DOMAINS` | unset | If set, only these hosts and subdomains may be fetched. |
@@ -160,7 +182,7 @@ Invalid values fall back to the shared default.
 
 | Component | Version |
 | --- | --- |
-| Pi | locked in [`docs/hosts.jsonc`](hosts.jsonc) |
+| Pi | locked in [`docs/hosts.jsonc`](../hosts.jsonc) |
 | MCP revision | `2025-11-25` negotiated; server accepts `2024-11-05`–`2026-07-28` |
 | MCP SDK | `@modelcontextprotocol/server` 2.3.1 |
 | Runtime | Node.js 20+ (stdio) |
@@ -172,7 +194,13 @@ test personas (`2024-11-05`, `2025-06-18`, `2025-11-25`, `2026-07-28`).
 
 ## Uninstall
 
-Remove the `deepseek` entry from `~/.pi/agent/mcp.json` or `.pi/mcp.json`, or run:
+With the installer CLI:
+
+```bash
+npx deepseek-web-retrieval uninstall --host pi --scope <project|global>
+```
+
+Or remove the `deepseek` entry from `~/.pi/agent/mcp.json` or `.pi/mcp.json`, or run:
 
 ```bash
 pi mcp remove deepseek

package/docs/agents/triage-labels.md

@@ -0,0 +1,15 @@
+# Triage Labels
+
+The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
+
+| Label in mattpocock/skills | Label in our tracker | Meaning                                  |
+| -------------------------- | -------------------- | ---------------------------------------- |
+| `needs-triage`             | `needs-triage`       | Maintainer needs to evaluate this issue  |
+| `needs-info`               | `needs-info`         | Waiting on reporter for more information |
+| `ready-for-agent`          | `ready-for-agent`    | Fully specified, ready for an AFK agent  |
+| `ready-for-human`          | `ready-for-human`    | Requires human implementation            |
+| `wontfix`                  | `wontfix`            | Will not be actioned                     |
+
+When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
+
+Edit the right-hand column to match whatever vocabulary you actually use.