docs(web): explain plugins and MCP with verified Computer Use setup [skip ci]

Answer the integration chooser, actual catalog prerequisites, supported plugin formats, direct-versus-plugin MCP authentication and troubleshooting on the existing paper/blue pages. Link the plugin guide from docs navigation and refresh its plain-text index. Add explicit Computer Use GitHub/contributor links in all18locales and version-aware direct-MCP setup for published CLI0.10.2, whose older built-in bundle is not upgraded by catalog installation. Reconcile repository EN/ZH docs for config precedence, validation/reload, URL-only servers, environment credentials, trust hashes, pinned-source updates and catalog freshness. Current marketplace and unreleased source remain separate from installed-release claims; DSH and MCPApps are not presented as universally qualified. Verified locally:47existingwebtests passed (26dictionary/copy+21llms/docsIA); focused ESLint, TypeScript, locale/GT checks and diff check passed. Initial custom test harness missed Vite alias configuration in2suites; corrected harness passed those21checks. Desktop1280/mobile390 EN/ZH browser review passed; stale development module hydration mismatch cleared after owned dev-server restart. Published CLI0.10.2 discovered current CU0.16.1 tools and executed request_access through a local synthetic model:ok=true/viaapp, accessibilitygranted, screen-captureprobeok. No input or provider spend. Credential-free Cloudflare Docs MCP discovery listed2tools. Existing-helper setup is not clean-Mac/app-task qualification. Generated agent documentation uses51hashedinputs: our5revieweddocs plus committed da143039f7 content for all other inputs, excluding active peer GUIDE/feature/native drafts. Full clean web validation/deployment follows this frozen commit; no Engine release qualification. CU setup README is carried separately by codewhale-cu-plugin afb98e8. Evidence:CW/artifacts/plugin-mcp-discoverability-20261107. Tracking:CW-7848; CU acceptance remains CW-6732.
2026-11-07 10:36:05 -10:00 · 2026-11-07 00:52:15 -08:00
1 parent da143039f7
commit 0ced14d36b
@@ -2811,8 +2811,9 @@ reasoning contract, and all four membership ids omit generic sampling fields.
  Custom paths must be absolute; a relative value falls back to the user-global
  path so changing the launch directory cannot silently change the MCP pool.
  It is visible in `/config` and can be changed from the TUI. The new path is
-  used immediately by `/mcp`, but rebuilding the model-visible MCP tool pool
-  requires restarting the TUI.
+  used immediately by `/mcp`; run `/mcp reload` to rebuild the model-visible
+  MCP tool pool without restarting the TUI. A headless runtime still needs a
+  restart because its `ConfigReload` request does not refresh MCP connections.
 - `notes_path` (string, optional): defaults to `~/.codewhale/notes.txt`, with
  legacy `~/.deepseek/notes.txt` fallback when the Codewhale path is absent, and
  is used by the model-visible `note` tool.
@@ -5,7 +5,29 @@ In the terminal, `/mcp` (also `/mcps`) opens **Extensions → MCP**. Enter opens

 > 阅读简体中文版：[zh_hans/MCP.md](zh_hans/MCP.md)

-codewhale can load additional tools via MCP (Model Context Protocol). MCP servers can be local stdio processes that the TUI starts, or remote URL-based servers that speak Streamable HTTP with legacy SSE fallback.
+Codewhale can load additional tools via MCP (Model Context Protocol). MCP servers can be local stdio processes that Codewhale starts, or remote URL-based servers that speak Streamable HTTP with legacy SSE fallback.
+
+## Version scope
+
+This page describes the main candidate. As of November 7, 2026, the latest
+published CLI release is [v0.10.2](https://github.com/codewhale-hq/Codewhale/releases/tag/v0.10.2).
+For that installed release, use its [versioned MCP guide](https://github.com/codewhale-hq/Codewhale/blob/v0.10.2/docs/MCP.md).
+Local stdio, remote HTTP/SSE, environment-backed authentication, direct remote
+OAuth, and reviewed plugin-contributed MCP are already supported in v0.10.2.
+Selected differences described below are candidate behavior:
+
+| Surface | Published v0.10.2 | Main candidate |
+| --- | --- | --- |
+| Default MCP client backend | Rust; SDK host is opt-in | Official MCP SDK 2.4.0 host; explicit Rust selection remains available |
+| Native stdio server protocols | Legacy revisions through 2025-06-18 | Adds 2025-11-25 and modern 2026-07-28 discovery |
+| Direct remote OAuth | Discovery, dynamic registration or a pre-registered public client | Adds issuer/resource-bound credentials and hosted client metadata support |
+| Catalogue freshness and MCP Skills | No TTL/list-change refresh or MCP Skills extension | Bounded refresh and verified skill resource reads; no native skill activation |
+| Package-runner connect budget | Default 30 seconds | At least 120 seconds unless the server has an explicit override |
+
+The candidate's default host needs a supported Node runtime (`^22.19 || >=24`);
+Bun 1.4.0 or newer is opt-in. See [extension runtime requirements](EXTENSIONS.md).
+An MCP server's own executable, dependencies, authentication and OS requirements
+remain separate from Codewhale's transport support.

 Browsing note:
 - `Web` is the canonical, deferred built-in browsing tool; it provides
@@ -84,7 +106,14 @@ stay consistent.
 A reviewed local plugin bundle may contribute MCP servers without creating a
 second transport or approval system. The servers use the same MCP manager,
 tool approval, resource, prompt, timeout, and network-policy paths documented
-here, and appear under namespaced `<plugin>-<server>` identities.
+here, and appear under collision-resistant
+`plugin-<plugin-name-byte-length>-<plugin>-<server>` identities.
+
+Authentication differs from direct user-authored MCP configuration. Plugin
+remotes may use `env_headers` or `bearer_token_env_var`, but plugin-contributed
+MCP OAuth is disabled in both v0.10.2 and the main candidate. Declaring OAuth,
+scopes or an OAuth resource in a plugin MCP manifest fails validation. To use
+OAuth, configure the remote server directly in your own `mcp.json` instead.

 The bundle boundary is intentionally stricter than user-authored `mcp.json`:
 unknown fields and ambiguous transports fail closed; stdio environment values
@@ -94,7 +123,7 @@ the normalized endpoint host set; and redirects remain on the reviewed origin.
 Reviewed plugin remotes also bypass ambient HTTP proxy configuration entirely;
 proxy credentials and proxy-observed traffic are not part of the v1 review.
 The plugin review discloses local host-user authority, structural argv,
-environment provenance, endpoint, auth source names, scopes, and tool filters
+environment provenance, endpoint, auth source names, and tool filters
 without reading or printing secret values.

 Trust stages reviewed content but does not enable it. Enablement attaches that
@@ -133,6 +162,14 @@ codewhale mcp remove <name>
 codewhale mcp validate
 ```

+Shell commands inspect their own process's MCP pool. In particular,
+`codewhale mcp validate` starts and connects enabled, allowed servers and reports
+connection/discovery failures; it is not a static configuration check and does
+not attach those connections to a running TUI. In the TUI, `/mcp validate`
+reports the last recorded snapshot without reconnecting; `/mcp reload` rebuilds
+that session's live pool. `codewhale doctor` is the static diagnostic path
+unless an explicit probe is requested.
+
 `codewhale mcp logout <name>` (and `/mcp logout`) clears locally stored
 OAuth credentials only — the provider may keep its standing grant. The next
 login forces the consent screen, so the authorized account/workspace can
@@ -259,8 +296,11 @@ ambient proxy authority.

 ## Remote HTTP Auth

-URL-based MCP servers can use static headers, env-derived headers, bearer-token
-env vars, or OAuth. Authorization precedence is conservative:
+Direct URL-based MCP servers can use static headers, env-derived headers,
+bearer-token env vars, or OAuth. Plugin-contributed remotes are limited to
+environment-backed headers/bearer tokens and cannot use MCP OAuth; see
+[Plugin-contributed MCP](#plugin-contributed-mcp). Authorization precedence for
+direct servers is conservative:

 1. `headers` and `env_headers` are applied first.
 2. `bearer_token_env_var` adds `Authorization: Bearer <env value>` when no
@@ -371,16 +411,15 @@ shape looks like this:
  "servers": {
    "huggingface": {
      "url": "https://huggingface.co/mcp",
-      "headers": {
-        "Authorization": "Bearer ${HF_TOKEN}"
-      }
+      "bearer_token_env_var": "HF_TOKEN"
    }
  }
 }
 ```

-The placeholder above is not a runnable secret. Use the settings-generated
-value in your private MCP config and never commit real Hugging Face tokens.
+Set `HF_TOKEN` in the environment that launches Codewhale; the example contains
+only its variable name. Literal `headers` values do not expand `${HF_TOKEN}`.
+Adapt the settings-generated server entry and never commit real tokens.

 Interactive helpers:

@@ -461,7 +500,20 @@ Default path:
 Overrides:

 - Config: `mcp_config_path = "/path/to/mcp.json"`
- Env: `DEEPSEEK_MCP_CONFIG=/path/to/mcp.json`
+- Env: `CODEWHALE_MCP_CONFIG=/absolute/path/to/mcp.json` (takes precedence over
+  the legacy `DEEPSEEK_MCP_CONFIG` spelling)
+
+Custom paths must be absolute; a relative `mcp_config_path` falls back to the
+user-global path rather than changing with the launch directory.
+
+Codewhale also reads `<workspace>/.codewhale/mcp.json` after the workspace is
+trusted in user-owned configuration. Project entries override same-named global
+servers; project-local files cannot grant that trust themselves or redirect the
+global `mcp_config_path`. Global and trusted-project entries take precedence
+over a colliding plugin-contributed identity. Project stdio commands default
+their working directory to the workspace. In the main candidate,
+`always_allow_tools` is accepted only from the global server configuration,
+not from project or plugin declarations.

 `codewhale mcp init` (and `codewhale setup --mcp`) writes to this resolved path.

@@ -513,11 +565,26 @@ The CLI also exposes helper tools when MCP is enabled:
 }
 ```

-You can also use `mcpServers` instead of `servers` for compatibility with other clients.
+You can also use `mcpServers` instead of `servers` for compatibility with other
+clients. Use exactly one map key in a file: a file containing both fails to
+parse.

 ## Running Codewhale as an MCP Server

-You can register your local Codewhale binary as an MCP server so other Codewhale sessions (or any MCP client) can call its tools.
+You can register your local Codewhale binary as a stdio MCP server for another
+Codewhale session or a client supporting one of its advertised protocol
+revisions. This exposes native tools; it is separate from connecting Codewhale
+to external servers.
+
+### Client configuration vs server configuration
+
+`mcp.json` tells a client which servers to launch or contact. The native
+`codewhale serve --mcp` process separately reads `[server]` from the retained
+legacy path `~/.deepseek/mcp_server.toml`. By default it exposes only
+`file_read` and `search`. Writing files or running commands requires naming
+those tools in `expose_tools` and explicitly setting `require_approval = false`
+in that server file. This stdio server has no interactive approval channel;
+with approval required, writing/executing tools are withheld and refused.

 ### Quick Setup

@@ -731,7 +798,8 @@ activation.

 Per-server settings:

- `command` (string, required)
+- `command` (string, required for a local stdio server): executable to start.
+  Remote servers use `url` instead; a URL-only entry is valid.
 - `args` (array of strings, optional)
 - `env` (object, optional)
 - `connect_timeout`, `execute_timeout`, `read_timeout` (seconds, optional). A per-server value overrides the global `timeouts` block, and each budget is independent of the others:
@@ -12,9 +12,64 @@ format (`plugin.json`, compatible `kimi.plugin.json` or
 the trust/enable lifecycle — this document covers how bits get onto disk in
 the first place.

+## Choose a plugin, skill, or MCP connection
+
+| What you need | Use | Starting point |
+| --- | --- | --- |
+| Reusable instructions that work through your existing tools | A skill | `/skills`, then `/skill <name>`; [Skills](SKILLS.md) |
+| A reviewed bundle of workflows, tools, commands or agent profiles | A plugin | `/plugin marketplace list`; [first-party catalog](https://github.com/codewhale-hq/codewhale-plugin-marketplace) |
+| Tools or context from a particular local process or remote service | A direct MCP connection | `/mcp`; [MCP setup](MCP.md) |
+
+A plugin can combine skills, Markdown commands, Fleet agent profiles, hooks,
+MCP servers and AI-provider declarations. Tools come from an MCP server or an
+experimental native extension; there is no generic application-UI component in
+the bundle manifest. Computer Use's Mac helper and Chromewhale's browser
+extension have their own setup after plugin review.
+
+MCP has two connection kinds: a local process over stdio, or a remote URL over
+Streamable HTTP. Legacy SSE is available when the server still supports it.
+User-configured remote servers can use environment-backed credentials or the
+host's OAuth login. Plugin-contributed remote servers require explicit
+environment-backed credentials when authentication is needed; their interactive
+OAuth path is not supported. Installing a skill or plugin does not connect an
+account or establish that a service works.
+
+A local stdio server runs with your operating-system user's access. Requested
+filesystem roots in a plugin manifest do not sandbox that process.
+
+For example, configure [Cloudflare's public documentation server](https://developers.cloudflare.com/changelog/post/2026-10-22-cloudflare-mcp-servers-retire-sse/)
+directly, or install the `cloudflare-docs` plugin when you also want its skill:
+
+```sh
+codewhale mcp add cloudflare-docs --url https://docs.mcp.cloudflare.com/mcp
+codewhale mcp connect cloudflare-docs
+codewhale mcp tools cloudflare-docs
+```
+
+Choose one setup for that server. `connect` is a diagnostic connection; it does
+not attach tools to an already running session. In an existing terminal session,
+run `/mcp reload` after changing configuration.
+
+## Bundle compatibility
+
+| Format | Supported boundary |
+| --- | --- |
+| Native `plugin.json` or legacy `plugin.toml` | Reviewed declarative adapters above; [manifest contract](PLUGIN_BUNDLES.md) |
+| Claude `.claude-plugin/plugin.json` | Skills, commands, agent profiles and MCP subset; hooks, LSP, custom MCP paths and plugin-root expansion are rejected; [compatibility details](CLAUDE_PLUGIN_COMPAT.md) |
+| `kimi.plugin.json` | Compatible skills, commands, agents and MCP declarations; unsupported runtime fields fail closed |
+| Local DSH package | Explicit preview and exact-hash import through `/plugin import dsh`; experimental native runtime, not blanket DSH compatibility or release qualification; [current evidence and limits](DSH_PLUGIN_COMPAT.md) |
+
+Native TypeScript extensions require `extension_host = true` under `[features]`
+and fresh capability review. LSP, requested filesystem roots and lifecycle mutation
+remain inventory-only. Current DSH adapters include work beyond the published
+v0.10.2 CLI; third-party DSH plugins' complete workflows are not established by
+an import succeeding. DSH plugin UI is unsupported. Other applications' plugin
+directories and credentials are not borrowed.
+
 `/plugin suggest <task>` is a local, read-only companion: it ranks already
 installed bundles (name, keywords, description, bundled skill names, declared
-hosts) and any marketplace catalogs you have added with `/plugin marketplace add`.
+hosts) and available marketplace catalogs, including the bundled snapshot and
+catalogs you have added with `/plugin marketplace add`.
 It explains the match and gives the next review, enable, or catalog-install
 step, but never installs, trusts, or enables a bundle on its own.

@@ -34,8 +89,10 @@ Codewhale is helpful about plugins, not pushy. The rules:
  `request_plugin_install` once per session to ask you to review a plugin the
  task needs; a second call fails. Exec, ACP, and runtime-API sessions do not
  get the tool.
- **Built-ins are never advertised.** Bundled plugins such as Computer Use
-  appear only in `/plugin list` and Extensions.
+- **Built-ins are never advertised.** Inspect existing bundles in `/plugin list`
+  and Extensions before installing another copy. The published v0.10.2 CLI
+  includes Computer Use; its layout differs from the current source candidate.
+  See [Computer Use across versions](PLUGIN_MARKETPLACE.md#computer-use-across-versions).
 - **Specific terms only.** Generic words (accessibility, browser, chrome,
  docs, screenshot, web, wiki, …) and Codewhale's own vocabulary (agent, code,
  data, MCP, model, session, tool) never trigger an offer, so asking why an
@@ -57,7 +114,7 @@ Codewhale is helpful about plugins, not pushy. The rules:
  `/plugin marketplace list`, Extensions, and the browser guide below.

 Codewhale does not invent a remote plugin URL; missing plugins are suggested
-only from catalogs you added. On-disk bundle changes still toast
+only from available catalogs. On-disk bundle changes still toast
 `/plugin reload` on send and between turns.

 ## Browser: pick one
@@ -69,7 +126,7 @@ what it can see.
 | --- | --- | --- |
 | `chrome-devtools` MCP (`/mcp recommendations`) | A Chrome it drives, which can include signed-in pages | DevTools-level inspection and performance work |
 | Playwright MCP (`/mcp recommendations`) | A fresh, isolated profile with `--isolated` | Scripted flows and testing without your identity |
-| Computer Use `browser_*` tools (bundled, off until reviewed) | One it launches, in a profile of its own | Browser steps inside a wider desktop task |
+| Computer Use browser tools (off until reviewed) | One it launches, in a profile of its own | Browser steps inside a wider desktop task |
 | Chromewhale (developer preview, `codewhale-hq/codewhale-plugin-marketplace`) | Yours, already open, in your own Chrome profile; load unpacked | Reading or acting on the tab you are looking at, one granted site at a time |

 None of these is offered to you proactively. Add the one that fits the job.
@@ -168,10 +225,14 @@ matching and the plugin goes inactive until you review again.
 - `update` re-downloads the recorded source. Identical bytes are a no-op; a
  changed bundle is swapped atomically and its trust receipt is automatically
  invalidated (the hash no longer matches), so re-review is forced before the
-  plugin can activate again. Plugins installed from a local path cannot be
-  re-downloaded. To replace their installed copy, disable and uninstall it,
-  then run `/plugin install <path>` and review the new bundle; the original
-  source directory is left intact. See the [local authoring loop](PLUGIN_AUTHORING.md#4-iterate-and-review-changes).
+  plugin can activate again. For a local install, it stages a fresh copy of the
+  recorded source directory; keep that authoring directory available. Editing
+  the installed copy does not update its source. See the
+  [local authoring loop](PLUGIN_AUTHORING.md#4-iterate-and-review-changes).
+- `update` retains the recorded repository revision, npm version, archive URL
+  and bundle selector. Refreshing a catalog does not retarget that source. To
+  select a newer catalog pin, follow
+  [Changing an installed pin](PLUGIN_MARKETPLACE.md#changing-an-installed-pin).
 - `uninstall` refuses enabled plugins (disable first), deletes the bundle
  directory, and removes its persisted trust/enablement entry.

@@ -420,8 +420,12 @@ and renders every candidate with an honest install plan:
 - Foreign policies are visibly ignored: a Codex `INSTALLED_BY_DEFAULT` entry
  is listed with a `NO_AUTO_INSTALL` warning and nothing is installed until
  an operator runs the install verb.
- Sources Codewhale cannot fetch (npm packages, `command:` sources, non-tarball
-  URLs) are listed as `not installable` with the reason.
+- Catalog npm package declarations, `command:` sources and non-tarball URLs
+  are listed as `not installable` with the reason. Explicit
+  `/plugin install npm:package@1.2.3` and `codewhale install npm:package@1.2.3`
+  instead fetch an exact-version npm registry tarball containing a native plugin
+  manifest. They do not run npm lifecycle scripts or install dependencies; see
+  [install sources](PLUGINS.md#sources).
 - `install` routes through the same reviewed installer as `/plugin install`:
  the bundle lands disabled and untrusted, and enters the hash-bound trust
  review before anything activates.
@@ -2,9 +2,10 @@

 Codewhale includes an offline snapshot of the `codewhale` catalog in the same
 marketplace store consumed by the terminal, Extensions, recommendations, and
-Runtime API. It lists Computer Use, WhaleWiki, Whalesong, Cloudflare Docs, the
-Codewhale skill bundle, and Codewhale for Chrome (Chromewhale). Browsing does
-not fetch or execute anything.
+Runtime API. Browse the [public first-party marketplace](https://github.com/codewhale-hq/codewhale-plugin-marketplace)
+for current entries and their prerequisites. Its contents can be newer than
+the snapshot in your installed CLI. Browsing a catalog does not fetch or
+execute a plugin.

 ```text
 /plugin marketplace list
@@ -12,11 +13,11 @@ not fetch or execute anything.
 /plugin marketplace install codewhale whalewiki
 /plugin show whalewiki
 /plugin trust whalewiki
-/plugin enable whalewiki
-/plugin update whalewiki
 ```

-Review the manifest and capabilities before trust and enablement. Installation
+The last command prints a review. Run its exact confirmation command containing
+both full hashes, then `/plugin enable whalewiki`. Review the manifest and
+capabilities before trust and enablement. Installation
 uses the existing size-limited, traversal-safe installer and starts disabled
 and untrusted. An update with changed bytes requires review again. Official
 catalog provenance grants no execution or network permission. Removing the
@@ -30,22 +31,81 @@ ambiguous roots, links, oversized archives, and changed plugin identities are
 rejected. The install receipt preserves the source, including its selector,
 so `/plugin update` retains the same bundle selector and reviewed revision.

-## Computer Use across upgrades
+## Catalog freshness and pinned installs

-Computer Use is an ordinary independently released plugin. Install it from
-Connectors or `/plugin marketplace install codewhale computer-use`, review its
-capabilities, then enable it. Install the signed Mac helper from
-[Computer Use setup](https://codewhale.net/computer-use) for native permission
-setup, trust and Pause/Stop controls.
+The published v0.10.2 CLI contains the 19-entry catalog from marketplace revision
+`2e3a6fba453c9b34d5b1444ab5bd6edc7b119189`. Current source and the public
+marketplace include later additions, such as Office and Studio; that does not
+make them part of the v0.10.2 snapshot. Use `/plugin marketplace show codewhale`
+to inspect the catalog your session actually has.

-The catalog uses the stable `computer-use.tar.gz` asset on the canonical
-repository's latest release. `/plugin update computer-use` downloads that source;
-changed bytes require review again. Later CU releases need no Engine rebuild.
-Older Engine versions embedded a CU copy. Their snapshots and receipts remain
-intact, but the current Engine does not discover them. Install and review the
-ordinary plugin once; a built-in receipt cannot authorize a new downloaded
-bundle. Existing manually installed or pinned bundles keep their normal source
-and review rules.
+The bundled catalog is a build-time snapshot. It does not poll the public
+repository. To use a separately reviewed catalog revision, obtain a local copy
+of the public marketplace, inspect its changes, then add its local document:
+
+```text
+/plugin marketplace add codewhale /absolute/path/codewhale-plugin-marketplace/marketplace.json
+/plugin marketplace show codewhale
+```
+
+Re-adding the same document refreshes its saved contents. If `codewhale` already
+names a different local source, remove that catalog first with
+`/plugin marketplace remove codewhale`, then add the intended document. Catalog
+removal does not remove installed plugins or change their trust.
+
+Repository entries in the bundled snapshot pin an immutable marketplace commit.
+Remote entries keep their declared URL and any archive checksum. The current
+public Computer Use entry pins a versioned `computer-use.tar.gz` asset and its
+SHA-256; it does not follow GitHub's latest-release address. `/plugin update`
+re-reads the installed bundle's recorded source, including its pin. It does not
+select a new source from a refreshed catalog.
+
+### Changing an installed pin
+
+For a user-scope bundle installed by Codewhale, retain its original source and
+any local changes before replacing it: uninstall deletes the installed copy.
+After refreshing and reviewing the catalog, this example selects its current
+WhaleWiki entry:
+
+```text
+/plugin show whalewiki
+/plugin disable whalewiki
+/plugin uninstall whalewiki
+/plugin marketplace install codewhale whalewiki
+/plugin trust whalewiki
+```
+
+Run the exact hash-bound confirmation printed by the new review, then
+`/plugin enable whalewiki`. Do not apply this sequence to built-in or workspace
+bundles: update and uninstall accept only user-scope installed bundles. A local
+catalog's `path:` source records that local directory, so keep it available for
+future `/plugin update` calls. A changed source still needs review and does not
+silently inherit an earlier receipt.
+
+## Computer Use across versions
+
+For the current helper with published CLI v0.10.2, follow the [direct MCP setup](https://github.com/codewhale-hq/codewhale-cu-plugin#codewhale-cli-setup), which uses the app’s bundled runtime. Disable an enabled older built-in before using that connection. Direct MCP supplies tools separately from plugin commands and skills.
+
+The published v0.10.2 CLI embeds Computer Use 0.12.1. To inspect that older bundle, start with
+`/plugin show computer-use`, review with `/plugin trust computer-use`, run the
+printed hash-bound confirmation, then `/plugin enable computer-use`. A catalog
+install of the same name reports that the built-in already exists; it does not
+replace it with a newer release. Direct installation of a second bundle with
+that name is refused. Built-in bundles cannot be updated or uninstalled through
+the user-plugin commands.
+
+The current Engine source candidate no longer creates or discovers the embedded
+copy. On that layout, install `computer-use` from the catalog as an ordinary
+user plugin, then review, trust and enable it. Its old snapshots and receipts
+remain intact; a built-in receipt cannot authorize the downloaded bundle.
+This source transition does not establish a published CLI migration path.
+
+Computer Use has its own [published releases](https://github.com/codewhale-hq/codewhale-cu-plugin/releases)
+and [contribution guide](https://github.com/codewhale-hq/codewhale-cu-plugin/blob/main/CONTRIBUTING.md).
+Install the native Mac helper separately using the
+[setup guide](https://codewhale.net/computer-use) for system permissions and
+Pause/Stop controls. A helper release, a plugin bundle and an Engine release
+have separate versions; their presence alone does not qualify a combination.

 ## Chromewhale

@@ -63,7 +123,7 @@ until you review it.
 | --- | --- | --- |
 | Catalog, WhaleWiki, Whalesong, Cloudflare Docs | `codewhale-hq/codewhale-plugin-marketplace` | Core catalog snapshot |
 | Bundled skills | Core active catalog and `crates/tui/assets/skills` | Marketplace `skills` and `skills/upstream.json` |
-| Computer Use | `codewhale-hq/codewhale-cu-plugin` | Stable release archive; no runtime mirrors |
+| Computer Use | `codewhale-hq/codewhale-cu-plugin` | Versioned release archive and checksum in the catalog; no current runtime mirror |

 The `Marketplace connection` workflow validates the exact catalog revision on
 catalog changes. Its weekly and manual runs compare the current public
@@ -94,9 +154,9 @@ npm test && npm run check:web

 Review the generated snapshot and rebuild Core. Its provenance records the
 exact marketplace commit. Local bundle URLs pin that immutable revision; remote
-entries retain their declared source. Updating catalog metadata requires a new
-Core snapshot; updating a remote plugin at its stable release URL does not. An
-existing pinned install does not silently follow `main`. Push the
+entries retain their declared source. Updating the bundled catalog requires a
+new Core snapshot; users may explicitly add a reviewed local catalog without
+rebuilding Core. Neither change retargets an existing pinned install. Push the
 reviewed marketplace revision before publishing a Core release that references it. Hosted CI must be green for the
 actual published revisions; local checks do not prove a public URL works.

@@ -1,10 +1,10 @@
 # MCP（外部工具服务器）

-> 本文翻译自英文版 [MCP.md](../MCP.md)，与英文源文件同步于 2026-09-29。
+> 本文依据英文版 [MCP.md](../MCP.md)，包含 main 候选版本的行为。截至 2026 年 11 月 7 日，最新公开 CLI 为 [v0.10.2](https://github.com/codewhale-hq/Codewhale/releases/tag/v0.10.2)。基本 stdio、HTTP/SSE、直接配置的远程 OAuth 和插件 MCP 已在该版本提供；SDK 默认后端、现代协议、凭据绑定和目录扩展等差异请参阅英文版[版本对照](../MCP.md#version-scope)。使用已安装的 v0.10.2 时，可查阅[对应版本指南](https://github.com/codewhale-hq/Codewhale/blob/v0.10.2/docs/MCP.md)。

 在终端中，`/mcp`（也可用 `/mcps`）会打开 **Extensions → MCP**。按 Enter 会对所选服务器执行恢复操作，或打开只读详情。清单为空时会提供服务器建议；浏览这些建议不会安装任何内容。`/mcp status`、`/mcp doctor`、`/mcp login`、`/mcp add` 等显式子命令的行为保持不变。

-codewhale 可以通过 MCP（Model Context Protocol，模型上下文协议）加载额外工具。MCP 服务器可以是 TUI 启动的本地 stdio 进程，也可以是使用 Streamable HTTP（带传统 SSE 回退）的远程基于 URL 的服务器。
+Codewhale 可以通过 MCP（Model Context Protocol，模型上下文协议）加载额外工具。MCP 服务器可以是 Codewhale 启动的本地 stdio 进程，也可以是使用 Streamable HTTP（带传统 SSE 回退）的远程基于 URL 的服务器。

 浏览说明：
 - `Web` 是规范的、延迟加载的内置浏览工具；在网络策略允许时，它提供 `search`、`fetch` 和 `wait` 操作。
@@ -60,9 +60,11 @@ codewhale 可以通过 MCP（Model Context Protocol，模型上下文协议）

 ## 插件贡献的 MCP

-通过审查的本地插件包可以贡献 MCP 服务器，而无需创建第二套传输或审批系统。这些服务器使用本文档记载的同一条 MCP 管理器、工具审批、资源、提示、超时和网络策略路径，并以命名空间化的 `<plugin>-<server>` 身份出现。
+通过审查的本地插件包可以贡献 MCP 服务器，而无需创建第二套传输或审批系统。这些服务器使用本文档记载的同一条 MCP 管理器、工具审批、资源、提示、超时和网络策略路径，并以避免身份冲突的 `plugin-<plugin-name-byte-length>-<plugin>-<server>` 命名。

-插件包边界有意比用户编写的 `mcp.json` 更严格：未知字段和模糊的传输方式默认失败关闭；stdio 环境变量值必须是精确的环境来源引用；远程字面量请求头和含机密信息的 URL 会被拒绝；声明的网络主机必须与规范化后的端点主机集合完全匹配；重定向保持在已审查的源站内。已审查的插件远程端点还会完全绕过环境中的 HTTP 代理配置；代理凭据和代理可见流量不属于 v1 审查范围。插件审查会披露本地主机用户权限、结构化 argv、环境来源、端点、认证来源名称、作用域和工具过滤器，但不会读取或打印机密值。
+认证范围与用户直接编写的 MCP 配置不同：插件远程服务器可使用 `env_headers` 或 `bearer_token_env_var`，但 v0.10.2 和 main 候选版本均不支持插件提供的 MCP OAuth。插件 MCP 清单声明 OAuth、作用域或 OAuth 资源时会验证失败。需要 OAuth 时，请直接在你自己的 `mcp.json` 中配置该远程服务器。
+
+插件包边界有意比用户编写的 `mcp.json` 更严格：未知字段和模糊的传输方式默认失败关闭；stdio 环境变量值必须是精确的环境来源引用；远程字面量请求头和含机密信息的 URL 会被拒绝；声明的网络主机必须与规范化后的端点主机集合完全匹配；重定向保持在已审查的源站内。已审查的插件远程端点还会完全绕过环境中的 HTTP 代理配置；代理凭据和代理可见流量不属于 v1 审查范围。插件审查会披露本地主机用户权限、结构化 argv、环境来源、端点、认证来源名称和工具过滤器，但不会读取或打印机密值。

 信任（Trust）会暂存已审查的内容，但不会启用它。启用操作会把该暂存快照附加到当前工作区的 MCP 池。禁用、撤销以及其他跨进程的代际变更会移除目录条目、取消进行中的操作，并终止插件的 stdio 子进程。在每次分派/目录边界之前，源码或暂存树的漂移都会被完全重新验证，并让下一个边界失败关闭；v0.9.1 不会在已经运行的调用期间持续对可变树做哈希，因此不承诺由漂移触发的调用中途取消。MCP 订阅不会通过插件包暴露。完整的生命周期契约请参阅[插件包](./PLUGIN_BUNDLES.md)。

@@ -92,6 +94,8 @@ codewhale mcp remove <name>
 codewhale mcp validate
 ```

+终端中的 `codewhale mcp validate` 会在自己的进程中启动并连接已启用且获准的服务器，报告连接或发现失败；它不是静态检查，也不会把连接附加到正在运行的 TUI。TUI 中的 `/mcp validate` 只报告最近记录的快照，不会重新连接；`/mcp reload` 才会重建该会话的实时连接池。`codewhale doctor` 默认提供静态诊断，除非显式请求实际探测。
+
 `codewhale mcp logout <name>`（以及 `/mcp logout`）只会清除本地存储的 OAuth 凭据——提供商可能仍保留其既有授权。下一次登录会强制显示授权确认页，因此可以更换所授权的账号/工作区；若要在远端彻底撤销授权，请在提供商的账号设置中撤销该应用。

 ## TUI 内管理器
@@ -164,7 +168,7 @@ v0.9.10 的产品建议使用这些经过审查的固定版本定义。Plugins

 ## 远程 HTTP 认证

-基于 URL 的 MCP 服务器可以使用静态请求头、环境变量派生的请求头、bearer-token 环境变量或 OAuth。授权优先级是保守的：
+直接配置的基于 URL 的 MCP 服务器可以使用静态请求头、环境变量派生的请求头、bearer-token 环境变量或 OAuth。插件远程服务器只支持基于环境变量的请求头或 bearer token，不支持 MCP OAuth；参阅[插件贡献的 MCP](#插件贡献的-mcp)。直接配置的服务器按以下优先级选择认证：

 1. `headers` 和 `env_headers` 首先应用。
 2. 若 `Authorization` 头尚未设置，`bearer_token_env_var` 会添加 `Authorization: Bearer <env value>`。
@@ -243,15 +247,13 @@ Codewhale 同时读取 `servers` 和 `mcpServers`，因此设置页生成的片
  "servers": {
    "huggingface": {
      "url": "https://huggingface.co/mcp",
-      "headers": {
-        "Authorization": "Bearer ${HF_TOKEN}"
-      }
+      "bearer_token_env_var": "HF_TOKEN"
    }
  }
 }
 ```

-上面的占位符不是可运行的机密。请在私有 MCP 配置中使用设置页生成的值，并且永远不要提交真实的 Hugging Face 令牌。
+请在启动 Codewhale 的环境中设置 `HF_TOKEN`；上例只保存变量名。字面量 `headers` 值不会展开 `${HF_TOKEN}`。按需调整设置页生成的服务器条目，不要提交真实令牌。

 交互式辅助命令：

@@ -274,7 +276,11 @@ Codewhale 同时读取 `servers` 和 `mcpServers`，因此设置页生成的片
 覆盖方式：

 - 配置项：`mcp_config_path = "/path/to/mcp.json"`
- 环境变量：`DEEPSEEK_MCP_CONFIG=/path/to/mcp.json`
+- 环境变量：`CODEWHALE_MCP_CONFIG=/absolute/path/to/mcp.json`，优先于旧名 `DEEPSEEK_MCP_CONFIG`。
+
+自定义路径必须是绝对路径；相对 `mcp_config_path` 会回退到用户全局路径，不会随启动目录改变。
+
+工作区在用户拥有的配置中获准信任后，Codewhale 还会读取 `<workspace>/.codewhale/mcp.json`。项目中的同名服务器覆盖全局条目；项目文件不能自行授予信任，也不能覆盖全局 `mcp_config_path`。全局或受信任项目中的显式条目优先于身份冲突的插件服务器。项目 stdio 命令默认以工作区为工作目录。main 候选版本中的 `always_allow_tools` 仅接受全局服务器配置，不接受项目或插件声明。

 `codewhale mcp init`（以及 `codewhale setup --mcp`）会写入这个解析出的路径。

@@ -321,11 +327,15 @@ Codewhale 同时读取 `servers` 和 `mcpServers`，因此设置页生成的片
 }
 ```

-为了与其他客户端兼容，你也可以使用 `mcpServers` 而不是 `servers`。
+为了与其他客户端兼容，你也可以使用 `mcpServers` 而不是 `servers`，但同一文件只能使用其中一个，同时出现会解析失败。`env_http_headers` 是 `env_headers` 的别名。

 ## 将 Codewhale 作为 MCP 服务器运行

-你可以把本地 Codewhale 二进制注册为 MCP 服务器，这样其他 Codewhale 会话（或任何 MCP 客户端）就能调用它的工具。
+你可以把本地 Codewhale 二进制注册为 stdio MCP 工具服务器，供其他 Codewhale 会话或支持其声明协议版本的客户端使用。这与让 Codewhale 连接外部 MCP 服务器是两个方向。
+
+### 客户端配置与服务器配置
+
+`mcp.json` 告诉客户端启动或连接哪些服务器。原生 `codewhale serve --mcp` 则从保留的旧版路径 `~/.deepseek/mcp_server.toml` 读取 `[server]` 配置，默认仅暴露 `file_read` 和 `search`。写入文件或执行命令，需要在 `expose_tools` 中列出对应工具，并显式设置 `require_approval = false`。这个 stdio 服务器没有交互式审批通道；要求审批时，写入和执行工具会被隐藏并拒绝调用。

 ### 快速设置

@@ -431,7 +441,7 @@ codewhale mcp tools codewhale

 每个服务器的设置：

- `command`（字符串，必需）
+- `command`（字符串，本地 stdio 服务器必需）：要启动的程序。远程服务器改用 `url`，只有 URL 的条目同样有效。
 - `args`（字符串数组，可选）
 - `env`（对象，可选）
 - `connect_timeout`、`execute_timeout`、`read_timeout`（秒，可选）。服务器级的值会覆盖全局 `timeouts` 块，三个预算彼此独立：
@@ -2,6 +2,7 @@

 > 英文原文：[PLUGINS.md](../PLUGINS.md)。
 > 最后与英文同步日期（last synced with English revision）：2026-09-26。
+> 2026-11-07 定点更正：版本范围、目录与固定来源、信任确认、本地更新；未做全文重译。

 想做一个插件包，先从[编写你的第一个 Codewhale 插件](./PLUGIN_AUTHORING.md)
 和里面可运行的 Skills 示例入手。
@@ -12,9 +13,14 @@
 兼容的 `kimi.plugin.json`、`.claude-plugin/plugin.json`，或旧版 `plugin.toml`。
 本文讲的是文件最初怎么落盘。

+版本范围：已发布的 CLI v0.10.2 内置 Computer Use 0.12.1；当前 Engine 源码候选版
+已改为单独安装的普通插件。刷新目录或安装新版 Mac 助手，不会替换旧 CLI 的内置包。
+完整的版本差异、目录时效和更换固定版本的步骤，见
+[英文市场指南](../PLUGIN_MARKETPLACE.md#catalog-freshness-and-pinned-installs)。
+
 `/plugin suggest <task>` 是一个本地、只读的配套命令：它会按名称、关键词、
-描述、所含 skill 名、声明的主机，给已安装的插件包排序，也给你用
-`/plugin marketplace add` 添加的市场目录排序。它还会说明匹配的原因，
+描述、所含 skill 名、声明的主机，给已安装的插件包与可用目录里的候选项排序，
+包括内置目录快照和你用 `/plugin marketplace add` 添加的目录。它还会说明匹配的原因，
 并给出下一步：审查、启用，或从目录安装。但它自己从不安装、信任或启用插件包。

 ## Codewhale 如何推荐插件
@@ -32,17 +38,17 @@ Codewhale 在插件上只帮忙，不推销。规则如下：
  在交互式 TUI 里，模型每个会话可以调用一次 `request_plugin_install`，
  请你审查任务需要的某个插件；第二次调用会失败。
  Exec、ACP 和 runtime-API 会话拿不到这个工具。
- **内置插件从不作为推荐出现。** Computer Use 这类内置插件，
-  只会出现在 `/plugin list` 和 Extensions 里。
+- **内置插件从不作为推荐出现。** 先在 `/plugin list` 和 Extensions 检查已有插件。
+  在 v0.10.2 上，对 Computer Use 执行目录安装只会提示内置包已存在，不会升级它；
+  应审查、信任并启用已有包。安装独立 Computer Use 包的方式适用于当前源码候选版的新布局。
 - **只认具体词。** 泛化词（accessibility、browser、chrome、docs、screenshot、
  web、wiki 等）和 Codewhale 自己的词汇（agent、code、data、MCP、model、
  session、tool）永远不触发推荐，所以问 MCP 服务器为什么卡住，不会冒出某个
  厂商的插件。有辨识度的名称、短语和域名照常匹配。匹配器和市场的
  `check-marketplace.mjs` 共用同一份停用词表。
 - **只推荐本机跑得起来的。** 插件的 `when.os` 若排除了当前操作系统，就不会被推荐。
- **给出真正的下一步。** 模型请求的那一行会按插件的实际需要写成 Install、
-  Review trust 或 Enable。只有那个按钮可点，它打开的是 `/plugin show <name>`；
-  它从不安装、信任或启用。
+- **审查后再操作。** 模型请求的那一行提供 Review，打开 Extensions 中的插件或市场目录。
+  点击本身不会安装、信任或启用；仍需选择目录中的显式操作并审查已安装的内容。
 - **关闭可以撤销。** 按 Esc 时，如果草稿非空，先清空草稿，然后才隐藏这一行，
  而且只对当前会话生效。“Don't suggest again”是你显式做出的选择，
  会被持久保存。`/plugin dismissals` 会列出这两种；
@@ -50,7 +56,7 @@ Codewhale 在插件上只帮忙，不推销。规则如下：
 - **新插件要靠自己找。** 想找新插件，就看这些文档、`/plugin marketplace list`、
  Extensions，以及下面的浏览器指南。

-Codewhale 不会凭空编造远程插件 URL；缺失的插件只会从你添加过的目录里推荐。
+Codewhale 不会凭空编造远程插件 URL；缺失的插件只会从可用目录里推荐。
 磁盘上的插件包有变化时，发送消息时和回合之间仍会弹出 `/plugin reload` 的 toast。

 ## 浏览器：选一个
@@ -61,14 +67,16 @@ Codewhale 不会凭空编造远程插件 URL；缺失的插件只会从你添加
 | --- | --- | --- |
 | `chrome-devtools` MCP（`/mcp recommendations`） | 它自己驱动的一个 Chrome，可以包含已登录的页面 | DevTools 级别的检查和性能分析 |
 | Playwright MCP（`/mcp recommendations`） | 带 `--isolated` 的全新隔离 profile | 不带你身份的脚本化流程和测试 |
-| Computer Use 的 `browser_*` 工具（内置，审查前关闭） | 它自己启动的浏览器，用独立的 profile | 更宽泛的桌面任务里的浏览器步骤 |
+| Computer Use 的浏览器工具（审查前关闭） | 它自己启动的浏览器，用独立的 profile | 更宽泛的桌面任务里的浏览器步骤 |
 | Chromewhale（开发者预览版，`codewhale-hq/codewhale-plugin-marketplace`） | 你自己的、已经打开的 Chrome profile；以 unpacked 方式加载 | 读取或操作你当前正看的标签页，每次授权一个站点 |

 这些都不会主动推荐给你。按任务需要自己添加。

 ## 来源

-`/plugin install <spec>` 接受三种来源：
+`/plugin install <spec>` 的常用来源如下。完整来源和限制见
+[英文来源说明](../PLUGINS.md#sources)，包括指定版本的 GitHub 与 npm tarball；
+`codewhale install <spec>` 是使用同一安装器的 shell 入口，不需要模型凭据。

 ```text
 /plugin install ./path/to/bundle            # local directory (copied)
@@ -122,6 +130,9 @@ Claude 的 `http` 传输映射为 Streamable HTTP。

 这里渲染的审查内容和确认 token 与 `/plugin trust <name>` 完全相同。
 信任走的是严格的、绑定哈希的回执流程，不是一个仅供参考的标记。
+不带 token 的 `/plugin trust <name>` 只显示审查内容，不会授予信任。
+必须执行审查打印出的原样确认命令，保留内容哈希和能力哈希这两个完整值；
+确认信任后，仍需单独执行 `/plugin enable <name>`。
 插件包的内容或声明的能力一旦变化，回执就不再匹配，插件随之失效，直到你重新审查。

 ## 更新与卸载
@@ -134,10 +145,13 @@ Claude 的 `http` 传输映射为 Streamable HTTP。

 - `update` 会重新下载记录在案的来源。字节完全相同就什么都不做；
  有变化的插件包会被原子替换，其信任回执自动失效（哈希不再匹配），
-  所以想让插件再次激活，必须重新审查。从本地路径安装的插件无法重新下载。
-  要替换已安装的副本，先停用再卸载，然后运行 `/plugin install <path>`
-  并审查新的插件包；原来源目录保持不动。参见
+  所以想让插件再次激活，必须重新审查。本地安装则从记录的原来源目录重新暂存副本，
+  因此应保留该目录；直接修改已安装副本不会修改原来源。参见
  [本地编写循环](./PLUGIN_AUTHORING.md#4-修改并重新审查)。
+- `update` 保留记录中的仓库修订、npm 版本、归档 URL 和包选择路径。
+  刷新市场目录不会改变已安装包的来源。要换到更新的固定版本，见
+  [英文更换步骤](../PLUGIN_MARKETPLACE.md#changing-an-installed-pin)；
+  该步骤仅适用于安装器管理的用户级插件，卸载前应保留原来源与本地修改。
 - `uninstall` 拒绝卸载已启用的插件（先停用），删除插件包目录，
  并移除它持久化的信任/启用记录。

@@ -1,3 +1,4 @@
+import Link from "next/link";
 import { Icon } from "@/components/icon";
 import { PageHeader, Section } from "@/components/page-header";
 import { Status } from "@/components/status-badge";
@@ -44,17 +45,25 @@ export default async function ComputerUsePage({ params }: { params: Promise<{ lo
            {t.requirements}
          </>
        }
-      >
-        {release.status === "ready" && primary ? (
-          <div className="cu-download">
-            <div className="actions">
+        actions={
+          <>
+            {release.status === "ready" && primary ? (
              <a className="btn btn-primary btn-lg" href={primary.downloadUrl}>
                {t.download}
              </a>
-              <span className="page-meta tabular">
-                v{release.version} · {Math.ceil(primary.size / 1024 / 1024)} MB
-              </span>
-            </div>
+            ) : null}
+            <a href={COMPUTER_USE_REPO} className="btn btn-secondary btn-lg">
+              {t.source}
+              <Icon name="external" className="icon" />
+            </a>
+          </>
+        }
+      >
+        {release.status === "ready" && primary ? (
+          <div className="cu-download">
+            <span className="page-meta tabular">
+              v{release.version} · {Math.ceil(primary.size / 1024 / 1024)} MB
+            </span>
            <p className="status-line">
              <a href={release.receiptUrl} className="link">{t.receipt}</a>
              {release.dmg ? <a href={release.downloadUrl} className="link">{t.downloadZip}</a> : null}
@@ -88,6 +97,22 @@ export default async function ComputerUsePage({ params }: { params: Promise<{ lo
          </ol>
        </Section>

+        <Section id="cu-codewhale" title={t.connectTitle}>
+          <p>{t.connectVersion}</p>
+          <p>{t.connectLimit}</p>
+          <p>{t.connectRuntime}</p>
+          <pre tabIndex={0} className="code-block">{`APP="/Applications/Codewhale Computer Use.app"
+codewhale mcp add computer --command "$APP/Contents/MacOS/node" --arg "$APP/Contents/Resources/plugin/mcp/server.mjs"
+codewhale mcp tools computer`}</pre>
+          <p>{t.connectReload}</p>
+          <pre tabIndex={0} className="code-block">{t.connectPrompt}</pre>
+          <p>{t.connectExpected}</p>
+          <p className="status-line">
+            <Link href={`/${locale}/docs/mcp`} className="link">{t.connectGuide}</Link>
+            <a href={`${COMPUTER_USE_REPO}/blob/main/README.md#codewhale-cli-setup`} className="link">Computer Use</a>
+          </p>
+        </Section>
+
        <section className="page-section" aria-label={t.controlsTitle}>
          <div className="grid-2">
            <div className="tile">
@@ -119,13 +144,17 @@ export default async function ComputerUsePage({ params }: { params: Promise<{ lo
            </p>
            <div className="actions">
              <a href={`${COMPUTER_USE_REPO}/blob/main/docs/TROUBLESHOOTING.md`} className="btn btn-secondary">{t.help}</a>
-              <a href={COMPUTER_USE_REPO} className="btn btn-ghost">
-                {t.source}
-                <Icon name="external" className="icon" />
-              </a>
            </div>
          </div>
        </section>
+
+        <Section id="cu-contribute" title={t.contributeTitle}>
+          <p>{t.contributeBody}</p>
+          <div className="actions">
+            <a href={`${COMPUTER_USE_REPO}/blob/main/CONTRIBUTING.md`} className="btn btn-secondary">{t.contributeGuide}</a>
+            <a href={`${COMPUTER_USE_REPO}/issues`} className="btn btn-ghost">{t.contributeIssue}</a>
+          </div>
+        </Section>
      </div>
    </>
  );
@@ -2,7 +2,7 @@ import Link from "next/link";
 import { Icon } from "@/components/icon";
 import { PageHeader, Section } from "@/components/page-header";
 import { buildPageMetadata } from "@/lib/page-meta";
-import { PLUGINS_COPY, PLUGIN_COMMANDS } from "@/lib/content/plugins";
+import { PLUGINS_COPY, PLUGIN_COMMANDS, INTEGRATIONS_COPY, INTEGRATION_CHOICES, PLUGIN_EXAMPLES, PLUGIN_COMPATIBILITY } from "@/lib/content/plugins";
 import type { LocalizedText } from "@/lib/content/vocabulary";
 import { pickText } from "@/lib/i18n/dictionaries";

@@ -48,10 +48,20 @@ export default async function PluginsPage({ params }: { params: Promise<{ locale
      />

      <div className="page-body">
+        <Section id="choose-title" title={t(INTEGRATIONS_COPY.chooseTitle)} scope={t(INTEGRATIONS_COPY.chooseLead)}>
+          <div className="grid-3">
+            {INTEGRATION_CHOICES.map((choice) => (
+              <Link key={choice.href} href={choice.href.startsWith("/") ? `/${locale}${choice.href}` : choice.href} className="tile">
+                <h3 className="section-title">{t(choice.title)}</h3>
+                <p>{t(choice.detail)}</p>
+              </Link>
+            ))}
+          </div>
+        </Section>
        <Section id="cu-title" title={t(PLUGINS_COPY.cuTitle)} scope={t(PLUGINS_COPY.cuLead)}>
          <div className="split">
            <div className="stack">
-              <pre tabIndex={0} className="code-block">{t(PLUGINS_COPY.cuInstall)}</pre>
+              <p>{t(INTEGRATIONS_COPY.cuSetupNote)}</p>
              <p className="section-scope">{t(PLUGINS_COPY.cuToolsNote)}</p>
              <Link href={`/${locale}/computer-use`} className="section-link">
                Computer Use
@@ -59,7 +69,7 @@ export default async function PluginsPage({ params }: { params: Promise<{ locale
              </Link>
            </div>
            <dl className="def-rows">
-              {PLUGINS_COPY.cuFeatures.map((feature) => (
+              {PLUGINS_COPY.cuFeatures.slice(0, 2).map((feature) => (
                <div key={t(feature.title)} className="def-row">
                  <dt>{t(feature.title)}</dt>
                  <dd>{t(feature.detail)}</dd>
@@ -72,14 +82,14 @@ export default async function PluginsPage({ params }: { params: Promise<{ locale
        <Section id="catalog-title" title={t(PLUGINS_COPY.catalogTitle)} scope={t(PLUGINS_COPY.catalogLead)}>
          <pre tabIndex={0} className="code-block mb-4">{t(PLUGINS_COPY.catalogBrowse)}</pre>
          <ul className="dir-list dir-list-card" role="list">
-            {PLUGINS_COPY.catalogEntries.map((entry) => (
-              <li key={entry.reference}>
-                <Link href={MARKETPLACE_REPO} className="dir-row">
+            {PLUGIN_EXAMPLES.map((entry) => (
+              <li key={entry.name}>
+                <Link href={`${MARKETPLACE_REPO}/tree/main/plugins/${entry.name}`} className="dir-row">
                  <span className="dir-mark" aria-hidden="true"><Icon name="plug" /></span>
                  <span className="dir-text">
-                    <span className="dir-title">{t(entry.title)}</span>
+                    <span className="dir-title">{entry.title}</span>
                    <span className="dir-purpose">{t(entry.detail)}</span>
-                    <span className="dir-meta">{entry.reference}</span>
+                    <span className="dir-meta">{`/plugin marketplace install codewhale ${entry.name}`}</span>
                  </span>
                  <span className="dir-action" aria-hidden="true"><Icon name="external" /></span>
                </Link>
@@ -89,6 +99,25 @@ export default async function PluginsPage({ params }: { params: Promise<{ locale
          <p className="section-scope mt-4">{t(PLUGINS_COPY.catalogNote)}</p>
        </Section>

+        <Section id="mcp-title" title={t(INTEGRATIONS_COPY.mcpTitle)} scope={t(INTEGRATIONS_COPY.mcpLead)}>
+          <pre tabIndex={0} className="code-block">{`codewhale mcp add cloudflare-docs --url "https://docs.mcp.cloudflare.com/mcp"
+codewhale mcp tools cloudflare-docs`}</pre>
+          <Link href={`/${locale}/docs/mcp`} className="section-link mt-4">
+            {t(INTEGRATIONS_COPY.mcpLink)}<Icon name="arrow-right" className="icon icon-flip" />
+          </Link>
+        </Section>
+
+        <Section id="compatibility-title" title={t(INTEGRATIONS_COPY.compatibilityTitle)} scope={t(INTEGRATIONS_COPY.compatibilityLead)}>
+          <dl className="def-rows">
+            {PLUGIN_COMPATIBILITY.map((format) => (
+              <div key={format.href} className="def-row">
+                <dt><Link className="link" href={format.href.startsWith("/") ? `/${locale}${format.href}` : format.href}>{t(format.title)}</Link></dt>
+                <dd>{t(format.detail)}</dd>
+              </div>
+            ))}
+          </dl>
+        </Section>
+
        <Section id="sources-title" title={t(PLUGINS_COPY.sourcesTitle)} scope={t(PLUGINS_COPY.sourcesLead)}>
          <ul className="dir-list dir-list-card" role="list">
            {PLUGINS_COPY.sources.map((source) => (
@@ -119,6 +148,13 @@ export default async function PluginsPage({ params }: { params: Promise<{ locale
          <p className="section-scope mt-4">{t(PLUGINS_COPY.trustNote)}</p>
        </Section>

+        <Section id="contribute-title" title={t(INTEGRATIONS_COPY.contributeTitle)} scope={t(INTEGRATIONS_COPY.contributeLead)}>
+          <div className="actions">
+            <Link href={AUTHORING_DOC} className="btn btn-secondary">{t(PLUGINS_COPY.docsCta)}</Link>
+            <Link href={`${MARKETPLACE_REPO}/issues`} className="section-link">{t(INTEGRATIONS_COPY.catalogLink)}<Icon name="external" className="icon" /></Link>
+          </div>
+        </Section>
+
        <Section id="commands-title" title={t(PLUGINS_COPY.commandsTitle)} scope={t(PLUGINS_COPY.commandsLead)} link={authoringLink}>
          <pre tabIndex={0} className="code-block">{PLUGIN_COMMANDS.join("\n")}</pre>
        </Section>
@@ -32,8 +32,8 @@
    "sources": [
      {
        "path": "docs/CONFIGURATION.md",
-        "sha256": "dccb4bcfb41e3d04abb256237817b6ef6ac310fc7c57f5f8829c62a9a7479092",
-        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
+        "sha256": "61fac67413aac35a4a67f410e174122a4ee09befbe2f2248fd3f9a6e4f08d99a",
+        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
      },
      {
        "path": "docs/CODEWHALE_AGENT.md",
@@ -64,8 +64,8 @@
    "sources": [
      {
        "path": "docs/CONFIGURATION.md",
-        "sha256": "dccb4bcfb41e3d04abb256237817b6ef6ac310fc7c57f5f8829c62a9a7479092",
-        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
+        "sha256": "61fac67413aac35a4a67f410e174122a4ee09befbe2f2248fd3f9a6e4f08d99a",
+        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
      },
      {
        "path": "docs/LEGACY_PATHS.md",
@@ -96,8 +96,8 @@
      },
      {
        "path": "docs/CONFIGURATION.md",
-        "sha256": "dccb4bcfb41e3d04abb256237817b6ef6ac310fc7c57f5f8829c62a9a7479092",
-        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
+        "sha256": "61fac67413aac35a4a67f410e174122a4ee09befbe2f2248fd3f9a6e4f08d99a",
+        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
      }
    ]
  },
@@ -208,8 +208,8 @@
    "sources": [
      {
        "path": "docs/MCP.md",
-        "sha256": "a7413202ce16f0ea25de1a84acc5d1bdfdf6cd3f7f00ebbf6ccd7aa8a1dd493a",
-        "content": "# MCP (External Tool Servers)\n\nIn the terminal, `/mcp` (also `/mcps`) opens **Extensions → MCP**. Enter opens the selected server’s recovery action or read-only details. An empty inventory offers server suggestions; browsing them installs nothing. Explicit subcommands such as `/mcp status`, `/mcp doctor`, `/mcp login`, and `/mcp add` retain their existing behavior.\n\n\n> 阅读简体中文版：[zh_hans/MCP.md](zh_hans/MCP.md)\n\ncodewhale can load additional tools via MCP (Model Context Protocol). MCP servers can be local stdio processes that the TUI starts, or remote URL-based servers that speak Streamable HTTP with legacy SSE fallback.\n\nBrowsing note:\n- `Web` is the canonical, deferred built-in browsing tool; it provides\n  `search`, `fetch`, and `wait` actions when network policy permits.\n- `web_search`, `fetch_url`, and `wait_for_dev_server` are hidden replay-only\n  aliases. New prompts and integrations should use `Web`.\n\nServer mode note:\n- `codewhale serve --mcp` runs the MCP stdio server.\n- `codewhale serve --http` runs the runtime HTTP/SSE API (separate mode).\n- `codewhale mcp-server` is an equivalent stdio entrypoint on the same\n  consolidated runtime.\n\nIn 0.10.1, the old child-server aggregation proxy is removed. `mcp-server`\nnow uses the same native tool server as `serve --mcp`; it does not launch the\nlegacy `mcp.server_definitions` list. Saved definitions are left intact. Configure\nexternal servers in `mcp.json` for the existing MCP client, or connect to those\nservers directly from your external client. Native server write tools remain\nwithheld unless the operator explicitly permits them in its server configuration.\n\nThe native stdio server supports MCP **2026-07-28** with required per-request\nmetadata and `server/discover`; no initialization handshake is needed for that\nrevision. It also supports the explicit legacy revisions **2024-11-05**,\n**2025-03-26**, **2025-06-18** and **2025-11-25** through `initialize`.\nInitialization never selects a modern revision; unsupported initialization\nversions fall back to 2025-11-25. Legacy callers should send\n`notifications/initialized`, but calls may proceed after a valid initialize\nresponse. This describes Codewhale as a server; outbound MCP client version\nsupport is configured separately.\n\n`resources/list` pages through the effective native skill instruction catalog,\nand `resources/read` returns the accepted instruction body for an exact listed\n`codewhale://skills/...` URI. Discovery follows the configured skill roots,\nprecedence and workspace trust; disabled skills are omitted. Reads supply inert\nMarkdown and never activate a skill. These are instruction-body resources, not\noriginal SKILL.md files or complete skill packages. Plugin skills, arbitrary\nfilesystem paths and session transcripts are not exposed by this catalog.\nThe old workspace/session entries, which had no resource reader, are removed.\nResource templates are empty. Lists and reads use private caching with a zero\nTTL; restart pagination if a changed catalog invalidates a cursor.\n\nOnly tools and resources are advertised. Subscriptions, list-change\nnotifications, the Skills extension, Apps, tasks and interactive approval are\nnot implemented by this server. Tool execution remains serialized through the\nRust registry, and request cancellation reaches the existing tool context.\nKeep stdin open until responses arrive; closing it cancels outstanding work.\nMalformed JSON and oversized input frames are discarded by the bounded SDK\ntransport, while well-formed invalid JSON-RPC receives an error.\n\n## Setup wizard vs manual MCP setup (#3407)\n\nThe `/setup` hub includes an optional **Tools and MCP**\nstep. That step is discovery/readiness only:\n\n| Wizard can do | Still requires manual / explicit action |\n| --- | --- |\n| Show configured servers as `healthy` / `needs_config` / `off` | Start or connect MCP servers |\n| Report config path presence (global + project) | Write or edit `mcp.json` contents |\n| Safe static health probe (missing command/url, broken absolute path, missing bearer env) | `codewhale mcp validate`, live connect, OAuth login |\n| Point at safe on-ramps (`/mcp`, `codewhale mcp init`, `codewhale doctor`) | Install community skills, trust skills, enable plugins |\n| Share Hotbar source counts from the same skill/MCP adapters (#3399) | Bind Hotbar slots (Hotbar step / `H`) |\n| Record optional/`needs_action` setup_state without blocking first-run | Anything that spawns processes or installs packages |\n\nEmpty inventory is **not** an error: first-run users see “nothing configured\nyet, that’s fine.” Failing or incomplete configured servers surface as\n`needs_config` with an actionable hint and never block setup completion.\nEnumeration never executes MCP/plugin commands beyond the static probe.\nSummaries redact commands, args, env, headers, and tokens.\n\n`codewhale doctor` reports MCP/skills/tools/plugLine truncated
+        "sha256": "d6d2f83cc1149151a9fa91b7d15973cfdeb72e8a5f5c03d5c80b9962d346c0ae",
+        "content": "# MCP (External Tool Servers)\n\nIn the terminal, `/mcp` (also `/mcps`) opens **Extensions → MCP**. Enter opens the selected server’s recovery action or read-only details. An empty inventory offers server suggestions; browsing them installs nothing. Explicit subcommands such as `/mcp status`, `/mcp doctor`, `/mcp login`, and `/mcp add` retain their existing behavior.\n\n\n> 阅读简体中文版：[zh_hans/MCP.md](zh_hans/MCP.md)\n\nCodewhale can load additional tools via MCP (Model Context Protocol). MCP servers can be local stdio processes that Codewhale starts, or remote URL-based servers that speak Streamable HTTP with legacy SSE fallback.\n\n## Version scope\n\nThis page describes the main candidate. As of November 7, 2026, the latest\npublished CLI release is [v0.10.2](https://github.com/codewhale-hq/Codewhale/releases/tag/v0.10.2).\nFor that installed release, use its [versioned MCP guide](https://github.com/codewhale-hq/Codewhale/blob/v0.10.2/docs/MCP.md).\nLocal stdio, remote HTTP/SSE, environment-backed authentication, direct remote\nOAuth, and reviewed plugin-contributed MCP are already supported in v0.10.2.\nSelected differences described below are candidate behavior:\n\n| Surface | Published v0.10.2 | Main candidate |\n| --- | --- | --- |\n| Default MCP client backend | Rust; SDK host is opt-in | Official MCP SDK 2.4.0 host; explicit Rust selection remains available |\n| Native stdio server protocols | Legacy revisions through 2025-06-18 | Adds 2025-11-25 and modern 2026-07-28 discovery |\n| Direct remote OAuth | Discovery, dynamic registration or a pre-registered public client | Adds issuer/resource-bound credentials and hosted client metadata support |\n| Catalogue freshness and MCP Skills | No TTL/list-change refresh or MCP Skills extension | Bounded refresh and verified skill resource reads; no native skill activation |\n| Package-runner connect budget | Default 30 seconds | At least 120 seconds unless the server has an explicit override |\n\nThe candidate's default host needs a supported Node runtime (`^22.19 || >=24`);\nBun 1.4.0 or newer is opt-in. See [extension runtime requirements](EXTENSIONS.md).\nAn MCP server's own executable, dependencies, authentication and OS requirements\nremain separate from Codewhale's transport support.\n\nBrowsing note:\n- `Web` is the canonical, deferred built-in browsing tool; it provides\n  `search`, `fetch`, and `wait` actions when network policy permits.\n- `web_search`, `fetch_url`, and `wait_for_dev_server` are hidden replay-only\n  aliases. New prompts and integrations should use `Web`.\n\nServer mode note:\n- `codewhale serve --mcp` runs the MCP stdio server.\n- `codewhale serve --http` runs the runtime HTTP/SSE API (separate mode).\n- `codewhale mcp-server` is an equivalent stdio entrypoint on the same\n  consolidated runtime.\n\nIn 0.10.1, the old child-server aggregation proxy is removed. `mcp-server`\nnow uses the same native tool server as `serve --mcp`; it does not launch the\nlegacy `mcp.server_definitions` list. Saved definitions are left intact. Configure\nexternal servers in `mcp.json` for the existing MCP client, or connect to those\nservers directly from your external client. Native server write tools remain\nwithheld unless the operator explicitly permits them in its server configuration.\n\nThe native stdio server supports MCP **2026-07-28** with required per-request\nmetadata and `server/discover`; no initialization handshake is needed for that\nrevision. It also supports the explicit legacy revisions **2024-11-05**,\n**2025-03-26**, **2025-06-18** and **2025-11-25** through `initialize`.\nInitialization never selects a modern revision; unsupported initialization\nversions fall back to 2025-11-25. Legacy callers should send\n`notifications/initialized`, but calls may proceed after a valid initialize\nresponse. This describes Codewhale as a server; outbound MCP client version\nsupport is configured separately.\n\n`resources/list` pages through the effective native skill instruction catalog,\nand `resources/read` returns the accepted instruction body for an exact listed\n`codewhale://skills/...` URI. Discovery follows the configured skill roots,\nprecedence and workspace trust; disabled skills are omitted. Reads supply inert\nMarkdown and never activate a skill. These are instruction-body resources, not\noriginal SKILL.md files or complete skill packages. Plugin skills, arbitrary\nfilesystem paths and session transcripts are not exposed by this catalog.\nThe old workspace/session entries, which had no resource reader, are removed.\nResource templates are empty. Lists and reads use private caching with a zero\nTTL; restart pagination if a changed catalog invalidates a cursor.\n\nOnly tools and resources are advertised. Subscriptions, list-change\nnotifications, the Skills extension, Apps, tasks and interactive approval are\nnot implemented by this server. Tool execution remains serialized through the\nRust regisLine truncated
      }
    ]
  },
@@ -224,8 +224,8 @@
      },
      {
        "path": "docs/CONFIGURATION.md",
-        "sha256": "dccb4bcfb41e3d04abb256237817b6ef6ac310fc7c57f5f8829c62a9a7479092",
-        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
+        "sha256": "61fac67413aac35a4a67f410e174122a4ee09befbe2f2248fd3f9a6e4f08d99a",
+        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
      }
    ]
  },
@@ -256,8 +256,8 @@
      },
      {
        "path": "docs/CONFIGURATION.md",
-        "sha256": "dccb4bcfb41e3d04abb256237817b6ef6ac310fc7c57f5f8829c62a9a7479092",
-        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
+        "sha256": "61fac67413aac35a4a67f410e174122a4ee09befbe2f2248fd3f9a6e4f08d99a",
+        "content": "# Configuration\n\ncodewhale reads configuration from a TOML file plus environment variables.\nAt process startup it may also load literal built-in-provider credentials from\na workspace-local `.env` file. Use the tracked `.env.example` as the template;\ncopy it to `.env`, then add only credential values.\n\nA workspace is not configuration authority. Codewhale therefore ignores\nconfig/profile/home paths, provider/model/base-URL routing, MCP/plugin state,\napproval/sandbox/shell posture, executable paths, runtime settings, and every\nother non-credential `.env` entry. Variable expansion is rejected so a\nrepository cannot substitute an ambient secret into a credential value. Use\n`config.toml`, CLI flags, or values exported by the launching shell for those\nexplicit control-plane settings. `.env` is read from a stable regular-file\nhandle, is capped at 1 MiB, and symbolic links, reparse points, and multiply\nlinked files are rejected.\n\n## Reading and checking configuration from the CLI\n\n`codewhale config get <key>` reads scalar keys, whole tables such as `tools`,\nand nested paths such as `tools.user_input_timeout_seconds`. Displayed tables\nand nested values apply the same recursive credential redaction as `config dump`.\n\n`config set` supports its named scalar keys and the provider, route, and\nnotification commands. It refuses a key that nothing reads and suggests the\nnearest real key (`config set calm_mod on` names `calm_mode`). A settings.toml\nkey such as `calm_mode` or `tool_collapse` is validated and written to the\nuser-global settings.toml, not config.toml; `config get` reads it back from\nthere even when an old config.toml copy (which nothing reads) is still present,\nand names that copy so you can `config unset` it. Settings keys have no project\nscope, so `--project` refuses them. A config.toml key is checked against the\ntype its reader expects and stored as a TOML boolean or number where the\nreader needs one (`yolo = true`, `max_subagents = 4`); `reasoning_effort`\naccepts the same aliases as `/effort` (#6563). Other dotted writes fail before\nmodifying the file and name the TOML table to edit. For example, set a tools\ntimeout in the file as:\n\n```toml\n[tools]\nuser_input_timeout_seconds = 0\n```\n\n`codewhale config doctor` checks credential presence and endpoint shape, and\nwarns about each config.toml root key that nothing reads: a settings.toml key\nleft in config.toml is named as misplaced, and any other unread key gets a\ndid-you-mean. Keys read by any runtime reader are not reported. The warnings do\nnot fail the check, and a clean result does not validate every runtime setting's\nvalue (#6083, #6563).\n\n## Usage and execution statistics\n\n`codewhale stats` is an alias of `codewhale metrics`; both use the same local,\nread-only backend. Use `--json` for the structured `stats` report. For example:\n\n```sh\ncodewhale stats --days 7 --models 10 --tools 20 --roles 10\ncodewhale metrics --project /path/to/workspace --json\n```\n\n`--days N` accepts a positive number of days and conflicts with `--since`.\n`--since 24h` and the existing duration syntax remain available. `--models N`,\n`--tools N` and `--roles N` select the top positive N rows by known tokens,\nidentified tool executions and recorded Fleet tasks respectively. These limits\nonly shorten the display; they do not remove stored receipts.\n\nThe report separates saved-document and Runtime views, frozen native-source\nmoney and token subtotals by actual model, retained tool-result history\nestimates and outcomes, completed compaction observations, and recorded Fleet\nroles. USD and CNY stay separate. A cumulative correction replaces its proven\npredecessor; copied Session/Runtime receipts and inherited Runtime fork rows\nare not added as new provider work. Conflicting source versions are shown\nseparately and excluded from the subtotal. Saved legacy display totals remain\nvisible as document projections without being charged again globally.\n\nCoverage is explicit. A missing quote, usage receipt, tool outcome, output\nshape or recovery link is unknown, not zero. Empty scalar usage from older\ntransport records cannot prove a reported zero. Token counts describe known\nreported data; tool history tokens are estimates of retained text, not bytes\nproven to have been replayed on a provider request. Latest prepared-request\ncomponents and source-linked compaction/role economics are unavailable where\nthey were not captured. The report does not infer provider invoices or prove\ncomplete historical coverage.\n\n`--project WORKSPACE` filters current saved/thread/Fleet views. Original source\nworkspace is not yet captured, so native money and model subtotals are\nunavailable for that filter; mutable current metadata is not used to assign a\ncharge. Older receipt projections without reliable workspace scope are also\nunavailable under this filter. Without it, those legacy receipt views remain\nseparate fromLine truncated
      }
    ]
  },
@@ -267,13 +267,18 @@
    "sources": [
      {
        "path": "docs/PLUGINS.md",
-        "sha256": "66a354c06964da0c786e3e29d5b79fee8b090ad2fbb53170a75d62e241759867",
-        "content": "# Installing plugins\n\n> 阅读简体中文版：[zh_hans/PLUGINS.md](zh_hans/PLUGINS.md)。\n\nTo create a bundle, start with [Write your first Codewhale plugin](PLUGIN_AUTHORING.md)\nand its runnable Skills example.\n\nThis is the walkthrough for the `/plugin install` on-ramp (v0.9.4, #5182).\n[PLUGIN_BUNDLES.md](PLUGIN_BUNDLES.md) remains the contract for the bundle\nformat (`plugin.json`, compatible `kimi.plugin.json` or\n`.claude-plugin/plugin.json`, or legacy `plugin.toml`), discovery, validation, and\nthe trust/enable lifecycle — this document covers how bits get onto disk in\nthe first place.\n\n`/plugin suggest <task>` is a local, read-only companion: it ranks already\ninstalled bundles (name, keywords, description, bundled skill names, declared\nhosts) and any marketplace catalogs you have added with `/plugin marketplace add`.\nIt explains the match and gives the next review, enable, or catalog-install\nstep, but never installs, trusts, or enables a bundle on its own.\n\n## How Codewhale offers plugins\n\nCodewhale is helpful about plugins, not pushy. The rules:\n\n- **One proactive surface.** Sending a task can show one quiet toast when the\n  prompt matches an installed-but-idle plugin or a catalog candidate you do\n  not have yet, for example `/plugin trust supabase` or\n  `/plugin marketplace install <catalog> supabase`. Nothing appears while you\n  type, and nothing is appended to your message to advertise plugins.\n- **One switch.** With `contextual_tips` off, no plugin guidance appears\n  anywhere. Required notices and your own `/plugin` commands still work.\n- **One budget.** Plugin offers share the per-session guidance budget with\n  other tips. In the interactive TUI the model can call\n  `request_plugin_install` once per session to ask you to review a plugin the\n  task needs; a second call fails. Exec, ACP, and runtime-API sessions do not\n  get the tool.\n- **Built-ins are never advertised.** Bundled plugins such as Computer Use\n  appear only in `/plugin list` and Extensions.\n- **Specific terms only.** Generic words (accessibility, browser, chrome,\n  docs, screenshot, web, wiki, …) and Codewhale's own vocabulary (agent, code,\n  data, MCP, model, session, tool) never trigger an offer, so asking why an\n  MCP server is stuck does not suggest a vendor's plugin. Distinctive names,\n  phrases and domains still do. The matcher and the marketplace's\n  `check-marketplace.mjs` share one stoplist.\n- **Only what runs here.** Plugins whose `when.os` excludes this OS are not\n  offered.\n- **Review before acting.** A model-requested row offers Review. Its button\n  opens the existing Extensions inventory: Plugins for an installed bundle,\n  Marketplace for a suggestion that is not installed. Nothing is installed,\n  trusted, or enabled by that click. Choose the inventory's explicit action;\n  trust still reviews the exact installed content before activation.\n- **Reversible dismissal.** Esc clears a non-empty draft first, then hides the\n  row for this session only. \"Don't suggest again\" is the explicit,\n  persisted choice. `/plugin dismissals` lists both kinds, and\n  `/plugin dismissals reset [<name>]` lets suggestions offer a plugin again.\n- **Discovery is passive.** Find new plugins in these docs,\n  `/plugin marketplace list`, Extensions, and the browser guide below.\n\nCodewhale does not invent a remote plugin URL; missing plugins are suggested\nonly from catalogs you added. On-disk bundle changes still toast\n`/plugin reload` on send and between turns.\n\n## Browser: pick one\n\nSeveral options can drive a browser. They differ in whose browser it is and\nwhat it can see.\n\n| Option | Whose browser | Good for |\n| --- | --- | --- |\n| `chrome-devtools` MCP (`/mcp recommendations`) | A Chrome it drives, which can include signed-in pages | DevTools-level inspection and performance work |\n| Playwright MCP (`/mcp recommendations`) | A fresh, isolated profile with `--isolated` | Scripted flows and testing without your identity |\n| Computer Use `browser_*` tools (bundled, off until reviewed) | One it launches, in a profile of its own | Browser steps inside a wider desktop task |\n| Chromewhale (developer preview, `codewhale-hq/codewhale-plugin-marketplace`) | Yours, already open, in your own Chrome profile; load unpacked | Reading or acting on the tab you are looking at, one granted site at a time |\n\nNone of these is offered to you proactively. Add the one that fits the job.\n\n## Sources\n\n`codewhale install <spec>` and `/plugin install <spec>` use the same installer.\nThe shell entry does not start a model or require model credentials. Both keep\nbundles disabled and untrusted until you explicitly review and enable them.\n\n```sh\ncodewhale install git:github.com/example/plugin@v1.0.0\ncodewhale install npm:@example/plugin@1.0.0\ncodewhale install ./local-plugin\n```\n\nGit shorthand supports GitHub archives only; refs must be a single safe segment.\nUseLine truncated
+        "sha256": "2b69ca39b3ecb8f02a2ba3454c24dd7e9d49f4c26b3a36407ef76b6ab1e4cb0c",
+        "content": "# Installing plugins\n\n> 阅读简体中文版：[zh_hans/PLUGINS.md](zh_hans/PLUGINS.md)。\n\nTo create a bundle, start with [Write your first Codewhale plugin](PLUGIN_AUTHORING.md)\nand its runnable Skills example.\n\nThis is the walkthrough for the `/plugin install` on-ramp (v0.9.4, #5182).\n[PLUGIN_BUNDLES.md](PLUGIN_BUNDLES.md) remains the contract for the bundle\nformat (`plugin.json`, compatible `kimi.plugin.json` or\n`.claude-plugin/plugin.json`, or legacy `plugin.toml`), discovery, validation, and\nthe trust/enable lifecycle — this document covers how bits get onto disk in\nthe first place.\n\n## Choose a plugin, skill, or MCP connection\n\n| What you need | Use | Starting point |\n| --- | --- | --- |\n| Reusable instructions that work through your existing tools | A skill | `/skills`, then `/skill <name>`; [Skills](SKILLS.md) |\n| A reviewed bundle of workflows, tools, commands or agent profiles | A plugin | `/plugin marketplace list`; [first-party catalog](https://github.com/codewhale-hq/codewhale-plugin-marketplace) |\n| Tools or context from a particular local process or remote service | A direct MCP connection | `/mcp`; [MCP setup](MCP.md) |\n\nA plugin can combine skills, Markdown commands, Fleet agent profiles, hooks,\nMCP servers and AI-provider declarations. Tools come from an MCP server or an\nexperimental native extension; there is no generic application-UI component in\nthe bundle manifest. Computer Use's Mac helper and Chromewhale's browser\nextension have their own setup after plugin review.\n\nMCP has two connection kinds: a local process over stdio, or a remote URL over\nStreamable HTTP. Legacy SSE is available when the server still supports it.\nUser-configured remote servers can use environment-backed credentials or the\nhost's OAuth login. Plugin-contributed remote servers require explicit\nenvironment-backed credentials when authentication is needed; their interactive\nOAuth path is not supported. Installing a skill or plugin does not connect an\naccount or establish that a service works.\n\nA local stdio server runs with your operating-system user's access. Requested\nfilesystem roots in a plugin manifest do not sandbox that process.\n\nFor example, configure [Cloudflare's public documentation server](https://developers.cloudflare.com/changelog/post/2026-10-22-cloudflare-mcp-servers-retire-sse/)\ndirectly, or install the `cloudflare-docs` plugin when you also want its skill:\n\n```sh\ncodewhale mcp add cloudflare-docs --url https://docs.mcp.cloudflare.com/mcp\ncodewhale mcp connect cloudflare-docs\ncodewhale mcp tools cloudflare-docs\n```\n\nChoose one setup for that server. `connect` is a diagnostic connection; it does\nnot attach tools to an already running session. In an existing terminal session,\nrun `/mcp reload` after changing configuration.\n\n## Bundle compatibility\n\n| Format | Supported boundary |\n| --- | --- |\n| Native `plugin.json` or legacy `plugin.toml` | Reviewed declarative adapters above; [manifest contract](PLUGIN_BUNDLES.md) |\n| Claude `.claude-plugin/plugin.json` | Skills, commands, agent profiles and MCP subset; hooks, LSP, custom MCP paths and plugin-root expansion are rejected; [compatibility details](CLAUDE_PLUGIN_COMPAT.md) |\n| `kimi.plugin.json` | Compatible skills, commands, agents and MCP declarations; unsupported runtime fields fail closed |\n| Local DSH package | Explicit preview and exact-hash import through `/plugin import dsh`; experimental native runtime, not blanket DSH compatibility or release qualification; [current evidence and limits](DSH_PLUGIN_COMPAT.md) |\n\nNative TypeScript extensions require `extension_host = true` under `[features]`\nand fresh capability review. LSP, requested filesystem roots and lifecycle mutation\nremain inventory-only. Current DSH adapters include work beyond the published\nv0.10.2 CLI; third-party DSH plugins' complete workflows are not established by\nan import succeeding. DSH plugin UI is unsupported. Other applications' plugin\ndirectories and credentials are not borrowed.\n\n`/plugin suggest <task>` is a local, read-only companion: it ranks already\ninstalled bundles (name, keywords, description, bundled skill names, declared\nhosts) and available marketplace catalogs, including the bundled snapshot and\ncatalogs you have added with `/plugin marketplace add`.\nIt explains the match and gives the next review, enable, or catalog-install\nstep, but never installs, trusts, or enables a bundle on its own.\n\n## How Codewhale offers plugins\n\nCodewhale is helpful about plugins, not pushy. The rules:\n\n- **One proactive surface.** Sending a task can show one quiet toast when the\n  prompt matches an installed-but-idle plugin or a catalog candidate you do\n  not have yet, for example `/plugin trust supabase` or\n  `/plugin marketplace install <catalog> supabase`. Nothing appears while you\n  type, and nothing is appended to your message to advertise plugins.\n- **One switch.** With Line truncated
      },
      {
        "path": "docs/PLUGIN_BUNDLES.md",
-        "sha256": "47437bf9e128db39302605ea2c6e4737b12c22caccf35bf8b5e974d8b1c3fdbf",
-        "content": "# Plugin bundles\n\n> 阅读简体中文版：[zh_hans/PLUGIN_BUNDLES.md](zh_hans/PLUGIN_BUNDLES.md)。\n\nCodewhale supports a deliberately small plugin-bundle boundary. The boundary\nwas drawn in v0.9.1 and is extended deliberately in v0.9.10: a bundle may\ncontribute declarative Skills, MCP configuration, Commands, Agent profiles,\nand Hooks through Codewhale's existing engines. Unsupported declarations stay\ninventoried instead of disabling a mixed bundle. Discovery alone never\nexecutes, enables, trusts, downloads, updates, or installs anything.\n\nThis document owns the bundle formats, discovery,\nvalidation, and the trust/enable/runtime contract. [PLUGINS.md](PLUGINS.md)\nowns how bits get onto and off disk — the `/plugin install`, `update`,\n`uninstall`, and `suggest` on-ramp added in v0.9.4 (#5182). Compatible Claude Code bundles use the same native adapters; their supported subset is\n[CLAUDE_PLUGIN_COMPAT.md](CLAUDE_PLUGIN_COMPAT.md).\nFor a runnable native example and explicit OpenCode/DSH data conversion, see\n[Write your first plugin](PLUGIN_AUTHORING.md).\n\n## Discovery and precedence\n\nCodewhale scans only its own roots, looking in each `<name>/` directory for a\nmanifest named `plugin.json` (the native Agent Plugins v1.0.0 format, since\nv0.9.4), `kimi.plugin.json` (the compatible Kimi Skills/MCP subset, since\nv0.9.8), `plugin.toml` (the legacy Codewhale format, still fully readable), or\n`.claude-plugin/plugin.json` (the compatible Claude subset, since v0.9.13):\n\n- User: `~/.codewhale/plugins/<name>/`\n- Workspace: `<workspace>/.codewhale/plugins/<name>/`\n\nA bundle that publishes multiple formats is read through `plugin.json` first,\nthen `kimi.plugin.json`, then the legacy `plugin.toml`, then\n`.claude-plugin/plugin.json`.\nComputer Use installs from the first-party catalog as a normal user plugin.\nIt updates independently of the Engine and requires review and enablement.\nThe native Mac helper is installed separately for permission setup and the\ncomputer-control indicator. See the [Computer Use guide](https://github.com/codewhale-hq/codewhale-cu-plugin).\n\nUser plugins take precedence over workspace plugins. Symbolic-link roots,\nmanifests, component paths, and nested component files fail closed.\nHistorical built-in snapshots and receipts remain untouched for older binaries;\nthe current Engine neither creates nor discovers a built-in Computer Use copy.\nInstall and review the catalog plugin once when upgrading from that layout.\n\nNew user and workspace bundles are always untrusted and disabled. Discovery is\nread-only and does not inspect any other application's extension or credential\ndirectories: ambient roots such as `.claude/plugins` or `.cursor/plugins` are\nnever scanned.\n\nPre-v0.9.1 `overrides.json` enablement was intentionally not imported as\ntrust; every bundle activates only through the content-hash and\n`codewhale-plugin-capabilities-v3` activation-policy review below.\n\n## Manifest\n\nAll supported encodings parse into the same internal manifest, so validation, hashing,\nreview, and runtime behavior are identical downstream. On-disk auto-migration\nbetween them is deliberately not performed; `/plugin export <name>\n<target-dir>` publishes a loaded bundle as a spec-valid Agent Plugins v1.0.0\ndirectory without modifying the installed one.\n\n### `plugin.json` (Agent Plugins v1.0.0)\n\nThe standard's manifest root is closed: `$schema`, `name`, and the optional\nwell-known fields (`version`, `description`, `author`, `homepage`,\n`repository`, `license`, `keywords`, `extensions`). An unknown root key is a\nparse error. Client-specific data lives under `extensions`, keyed by\nreverse-domain namespace: unknown vendor namespaces are ignored, never\nrejected — that is what lets a bundle authored for another client load here —\nwhile unknown keys inside Codewhale's own `extensions[\"net.codewhale\"]`\nnamespace are rejected rather than silently dropped.\n\nNames follow the standard's rule: 1–64 lowercase ASCII letters, digits, or\ninternal single `-`/`.`, starting and ending alphanumeric, never `--` or `..`.\nA `skills/` directory in the bundle root is picked up automatically; other\ncomponent locations, `capabilities`, `when`, and `display_name` ride in\n`extensions[\"net.codewhale\"]`.\n\nMCP servers cannot live in `plugin.json` (the root is closed); they live in a\nsibling `mcp.json` under `mcpServers`, with `stdio`, `streamable-http`, or\n`sse` transports (`type` may be omitted and is inferred from `command` vs\n`url`). Codewhale-only server options — timeouts, tool filters, env-backed\ncredentials, enablement — ride per-server under `extensions[\"net.codewhale\"]`.\nThe `env` names `PLUGIN_ROOT` and `PLUGIN_DATA` are reserved by the standard\nfor the host runtime and are rejected in plugin definitions.\n\n### `plugin.toml` (legacy Codewhale format)\n\n```toml\nschema_version = 1\n\n[plugin]\nname = \"example\"\nversion = \"0.1.0\Line truncated
+        "sha256": "5595f972609b6fcc425b830eb13bfc75095107e77152149a1cd6f890751b205c",
+        "content": "# Plugin bundles\n\n> 阅读简体中文版：[zh_hans/PLUGIN_BUNDLES.md](zh_hans/PLUGIN_BUNDLES.md)。\n\nCodewhale supports a deliberately small plugin-bundle boundary. The boundary\nwas drawn in v0.9.1 and is extended deliberately in v0.9.10: a bundle may\ncontribute declarative Skills, MCP configuration, Commands, Agent profiles,\nand Hooks through Codewhale's existing engines. Unsupported declarations stay\ninventoried instead of disabling a mixed bundle. Discovery alone never\nexecutes, enables, trusts, downloads, updates, or installs anything.\n\nThis document owns the bundle formats, discovery,\nvalidation, and the trust/enable/runtime contract. [PLUGINS.md](PLUGINS.md)\nowns how bits get onto and off disk — the `/plugin install`, `update`,\n`uninstall`, and `suggest` on-ramp added in v0.9.4 (#5182). Compatible Claude Code bundles use the same native adapters; their supported subset is\n[CLAUDE_PLUGIN_COMPAT.md](CLAUDE_PLUGIN_COMPAT.md).\nFor a runnable native example and explicit OpenCode/DSH data conversion, see\n[Write your first plugin](PLUGIN_AUTHORING.md).\n\n## Discovery and precedence\n\nCodewhale scans only its own roots, looking in each `<name>/` directory for a\nmanifest named `plugin.json` (the native Agent Plugins v1.0.0 format, since\nv0.9.4), `kimi.plugin.json` (the compatible Kimi Skills/MCP subset, since\nv0.9.8), `plugin.toml` (the legacy Codewhale format, still fully readable), or\n`.claude-plugin/plugin.json` (the compatible Claude subset, since v0.9.13):\n\n- User: `~/.codewhale/plugins/<name>/`\n- Workspace: `<workspace>/.codewhale/plugins/<name>/`\n\nA bundle that publishes multiple formats is read through `plugin.json` first,\nthen `kimi.plugin.json`, then the legacy `plugin.toml`, then\n`.claude-plugin/plugin.json`.\nComputer Use installs from the first-party catalog as a normal user plugin.\nIt updates independently of the Engine and requires review and enablement.\nThe native Mac helper is installed separately for permission setup and the\ncomputer-control indicator. See the [Computer Use guide](https://github.com/codewhale-hq/codewhale-cu-plugin).\n\nUser plugins take precedence over workspace plugins. Symbolic-link roots,\nmanifests, component paths, and nested component files fail closed.\nHistorical built-in snapshots and receipts remain untouched for older binaries;\nthe current Engine neither creates nor discovers a built-in Computer Use copy.\nInstall and review the catalog plugin once when upgrading from that layout.\n\nNew user and workspace bundles are always untrusted and disabled. Discovery is\nread-only and does not inspect any other application's extension or credential\ndirectories: ambient roots such as `.claude/plugins` or `.cursor/plugins` are\nnever scanned.\n\nPre-v0.9.1 `overrides.json` enablement was intentionally not imported as\ntrust; every bundle activates only through the content-hash and\n`codewhale-plugin-capabilities-v3` activation-policy review below.\n\n## Manifest\n\nAll supported encodings parse into the same internal manifest, so validation, hashing,\nreview, and runtime behavior are identical downstream. On-disk auto-migration\nbetween them is deliberately not performed; `/plugin export <name>\n<target-dir>` publishes a loaded bundle as a spec-valid Agent Plugins v1.0.0\ndirectory without modifying the installed one.\n\n### `plugin.json` (Agent Plugins v1.0.0)\n\nThe standard's manifest root is closed: `$schema`, `name`, and the optional\nwell-known fields (`version`, `description`, `author`, `homepage`,\n`repository`, `license`, `keywords`, `extensions`). An unknown root key is a\nparse error. Client-specific data lives under `extensions`, keyed by\nreverse-domain namespace: unknown vendor namespaces are ignored, never\nrejected — that is what lets a bundle authored for another client load here —\nwhile unknown keys inside Codewhale's own `extensions[\"net.codewhale\"]`\nnamespace are rejected rather than silently dropped.\n\nNames follow the standard's rule: 1–64 lowercase ASCII letters, digits, or\ninternal single `-`/`.`, starting and ending alphanumeric, never `--` or `..`.\nA `skills/` directory in the bundle root is picked up automatically; other\ncomponent locations, `capabilities`, `when`, and `display_name` ride in\n`extensions[\"net.codewhale\"]`.\n\nMCP servers cannot live in `plugin.json` (the root is closed); they live in a\nsibling `mcp.json` under `mcpServers`, with `stdio`, `streamable-http`, or\n`sse` transports (`type` may be omitted and is inferred from `command` vs\n`url`). Codewhale-only server options — timeouts, tool filters, env-backed\ncredentials, enablement — ride per-server under `extensions[\"net.codewhale\"]`.\nThe `env` names `PLUGIN_ROOT` and `PLUGIN_DATA` are reserved by the standard\nfor the host runtime and are rejected in plugin definitions.\n\n### `plugin.toml` (legacy Codewhale format)\n\n```toml\nschema_version = 1\n\n[plugin]\nname = \"example\"\nversion = \"0.1.0\Line truncated
+      },
+      {
+        "path": "docs/PLUGIN_MARKETPLACE.md",
+        "sha256": "93e8eeb319da86064d8288940e5c13ccfc47c99e1c6a50e0d20604212651bfef",
+        "content": "# First-party plugin marketplace\n\nCodewhale includes an offline snapshot of the `codewhale` catalog in the same\nmarketplace store consumed by the terminal, Extensions, recommendations, and\nRuntime API. Browse the [public first-party marketplace](https://github.com/codewhale-hq/codewhale-plugin-marketplace)\nfor current entries and their prerequisites. Its contents can be newer than\nthe snapshot in your installed CLI. Browsing a catalog does not fetch or\nexecute a plugin.\n\n```text\n/plugin marketplace list\n/plugin marketplace show codewhale\n/plugin marketplace install codewhale whalewiki\n/plugin show whalewiki\n/plugin trust whalewiki\n```\n\nThe last command prints a review. Run its exact confirmation command containing\nboth full hashes, then `/plugin enable whalewiki`. Review the manifest and\ncapabilities before trust and enablement. Installation\nuses the existing size-limited, traversal-safe installer and starts disabled\nand untrusted. An update with changed bytes requires review again. Official\ncatalog provenance grants no execution or network permission. Removing the\ncatalog persists the choice and leaves installed plugins untouched; a locally\nadded catalog named `codewhale` takes precedence over the bundled snapshot.\n\nThe bundle source uses a gzip tarball URL with `#path=plugins/whalewiki` (or\n`#path=skills`). The fragment selects exactly one bundle inside the shared\nrepository archive. Only that subtree is installed. Empty paths, traversal,\nambiguous roots, links, oversized archives, and changed plugin identities are\nrejected. The install receipt preserves the source, including its selector,\nso `/plugin update` retains the same bundle selector and reviewed revision.\n\n## Catalog freshness and pinned installs\n\nThe published v0.10.2 CLI contains the 19-entry catalog from marketplace revision\n`2e3a6fba453c9b34d5b1444ab5bd6edc7b119189`. Current source and the public\nmarketplace include later additions, such as Office and Studio; that does not\nmake them part of the v0.10.2 snapshot. Use `/plugin marketplace show codewhale`\nto inspect the catalog your session actually has.\n\nThe bundled catalog is a build-time snapshot. It does not poll the public\nrepository. To use a separately reviewed catalog revision, obtain a local copy\nof the public marketplace, inspect its changes, then add its local document:\n\n```text\n/plugin marketplace add codewhale /absolute/path/codewhale-plugin-marketplace/marketplace.json\n/plugin marketplace show codewhale\n```\n\nRe-adding the same document refreshes its saved contents. If `codewhale` already\nnames a different local source, remove that catalog first with\n`/plugin marketplace remove codewhale`, then add the intended document. Catalog\nremoval does not remove installed plugins or change their trust.\n\nRepository entries in the bundled snapshot pin an immutable marketplace commit.\nRemote entries keep their declared URL and any archive checksum. The current\npublic Computer Use entry pins a versioned `computer-use.tar.gz` asset and its\nSHA-256; it does not follow GitHub's latest-release address. `/plugin update`\nre-reads the installed bundle's recorded source, including its pin. It does not\nselect a new source from a refreshed catalog.\n\n### Changing an installed pin\n\nFor a user-scope bundle installed by Codewhale, retain its original source and\nany local changes before replacing it: uninstall deletes the installed copy.\nAfter refreshing and reviewing the catalog, this example selects its current\nWhaleWiki entry:\n\n```text\n/plugin show whalewiki\n/plugin disable whalewiki\n/plugin uninstall whalewiki\n/plugin marketplace install codewhale whalewiki\n/plugin trust whalewiki\n```\n\nRun the exact hash-bound confirmation printed by the new review, then\n`/plugin enable whalewiki`. Do not apply this sequence to built-in or workspace\nbundles: update and uninstall accept only user-scope installed bundles. A local\ncatalog's `path:` source records that local directory, so keep it available for\nfuture `/plugin update` calls. A changed source still needs review and does not\nsilently inherit an earlier receipt.\n\n## Computer Use across versions\n\nFor the current helper with published CLI v0.10.2, follow the [direct MCP setup](https://github.com/codewhale-hq/codewhale-cu-plugin#codewhale-cli-setup), which uses the app’s bundled runtime. Disable an enabled older built-in before using that connection. Direct MCP supplies tools separately from plugin commands and skills.\n\nThe published v0.10.2 CLI embeds Computer Use 0.12.1. To inspect that older bundle, start with\n`/plugin show computer-use`, review with `/plugin trust computer-use`, run the\nprinted hash-bound confirmation, then `/plugin enable computer-use`. A catalog\ninstall of the same name reports that the built-in already exists; it does not\nreplace it with a newer release. Direct installation of a second bundle with\nthat name is refused. Built-in buLine truncated
      },
      {
        "path": "docs/EXTENSIONS.md",
@@ -804,7 +804,7 @@
            "codeTerms": true
          },
          {
-            "p": "Keys, endpoints, provider choice, MCP servers, hooks, skills, and extra instruction files always come from your own config, so a cloned repository cannot point Codewhale at its own server or files. Start with `--no-project-config` to ignore a repository's file for one launch."
+            "p": "Provider keys, endpoints and provider choice come from your own config. MCP servers can also come from `.codewhale/mcp.json` after you trust the workspace in user-owned settings; project entries override same-named global entries. Review that executable authority before trusting a repository. See [MCP configuration](/docs/mcp#config)."
          },
          {
            "p": "Project instructions — how an agent should work in this repository — belong in `AGENTS.md` instead. Run `/init` to create one."
@@ -949,27 +949,74 @@
  },
  "docs-mcp": {
    "metaTitle": "Connect tools with MCP · Codewhale Docs",
-    "metaDescription": "Add Model Context Protocol servers so Codewhale can use more tools, sign in to remote servers, run Codewhale itself as an MCP server, and try code mode.",
+    "metaDescription": "Connect local and remote MCP servers, understand authentication and plugin compatibility, and troubleshoot missing tools.",
    "bodyClassName": "text-ink-soft leading-relaxed",
    "title": "Connect tools with MCP",
-    "lede": "MCP servers give Codewhale more tools — a database, an issue tracker, a browser. Add a local server that Codewhale starts for you, or a remote server by URL. Its tools then go through the same approvals as built-in ones.",
+    "lede": "Connect a local tool server or a remote service through Model Context Protocol. Codewhale discovers its tools and applies your tool permissions and approvals when you use them.",
    "sections": [
      {
        "id": "add",
-        "title": "Add a server",
+        "title": "Try the Cloudflare Docs server",
        "blocks": [
          {
-            "code": "codewhale mcp add git --command \"uvx\" --arg \"mcp-server-git\"\ncodewhale mcp add docs --url \"https://example.com/mcp\"\ncodewhale mcp list\ncodewhale mcp validate",
+            "p": "The public [Cloudflare Documentation server](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/) provides documentation search and a Pages-to-Workers migration guide. [View its official source](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize). Add it without credentials:"
+          },
+          {
+            "code": "codewhale mcp add cloudflare-docs --url \"https://docs.mcp.cloudflare.com/mcp\"\ncodewhale mcp tools cloudflare-docs",
            "lang": "Terminal"
          },
          {
-            "p": "`--command` starts a local server over stdio; repeat `--arg` for each argument. `--url` connects to a remote server over Streamable HTTP, with legacy SSE as a fallback. `mcp validate` checks the config and the servers you require."
+            "p": "The tool list should include `search_cloudflare_documentation` and `migrate_pages_to_workers_guide`. In an existing TUI session, run `/mcp reload` to load the new configuration into that session."
+          },
+          {
+            "note": "Checked on November 7, 2026 with published CLI v0.10.2: both commands exited successfully and listed those two tools without credentials. This checked setup and discovery, not tool execution. The [released guide](https://github.com/codewhale-hq/Codewhale/blob/v0.10.2/docs/MCP.md) describes that version; the [main source guide](https://github.com/codewhale-hq/Codewhale/blob/main/docs/MCP.md) may include unreleased changes."
          },
          {
            "p": "Inside a session, `/mcp` opens the MCP manager: each server's state, transport, timeouts, errors, and discovered tools. The same actions are available there, for example `/mcp add stdio <name> <command>` and `/mcp add http <name> <url>`."
          },
          {
-            "note": "An MCP server runs with your permissions. Add only servers you trust, as you would any program you install."
+            "note": "Local MCP servers run with the permissions of the Codewhale process; remote calls use the access you grant that service. Add only servers you trust."
+          }
+        ]
+      },
+      {
+        "id": "compatibility",
+        "title": "What can connect",
+        "blocks": [
+          {
+            "rows": [
+              [
+                "Local stdio",
+                "Codewhale starts the executable you configure with `--command`; repeat `--arg` for its arguments. Install the server and its required runtime first."
+              ],
+              [
+                "Remote HTTP / SSE",
+                "Use `--url` for Streamable HTTP, with legacy SSE fallback. A legacy SSE endpoint can use `--transport sse`. A remote entry does not need `command`."
+              ],
+              [
+                "Direct remote authentication",
+                "Your own MCP configuration can use environment-backed headers, bearer tokens or OAuth. OAuth needs compatible server metadata and client registration."
+              ],
+              [
+                "Plugin-contributed MCP",
+                "A reviewed, enabled plugin can supply stdio or remote MCP servers. Plugin MCP supports environment-backed authentication, but plugin-contributed MCP OAuth is unsupported."
+              ],
+              [
+                "Tools, resources and prompts",
+                "Codewhale discovers what the server actually advertises. Resources, templates and prompts are available when the server implements them."
+              ],
+              [
+                "Optional extensions and MCP Apps",
+                "General MCP Apps UI support is not available. Basic MCP transport support does not guarantee support for every optional extension or server."
+              ],
+              [
+                "Server requirements",
+                "Each server keeps its own OS, executable, browser, dependency and account requirements. A local server runs on the computer hosting Codewhale; Computer Use has its own platform limits."
+              ]
+            ]
+          },
+          {
+            "p": "A direct MCP entry does not require a plugin. [Plugins](/plugins) can package MCP tools with instructions and other components; each component still needs compatible dependencies, review and permissions."
          }
        ]
      },
@@ -978,12 +1025,15 @@
        "title": "Sign in to a remote server",
        "blocks": [
          {
-            "p": "For a server that uses OAuth, add it by URL and log in. For a bearer token, keep the token in an environment variable instead of the config file:"
+            "p": "For a directly configured OAuth server, add its real URL, then log in using the name you gave it:"
          },
          {
-            "code": "codewhale mcp login docs\ncodewhale mcp add tracker --url \"https://example.com/mcp\" --bearer-token-env-var TRACKER_TOKEN",
+            "code": "codewhale mcp login <server>\ncodewhale mcp logout <server>",
            "lang": "Terminal"
          },
+          {
+            "p": "For a bearer token, use `--bearer-token-env-var TOKEN_NAME` when adding the server, and set that variable in the environment launching Codewhale. `env_headers` maps header names to environment variable names. Literal `headers` values do not expand `${TOKEN_NAME}`. Plugin MCP entries cannot use OAuth; configure that server directly instead."
+          },
          {
            "p": "An explicit Authorization header always wins: headers from config apply first, then the bearer-token variable, then a stored OAuth login. `codewhale mcp logout <name>` removes the stored login on this machine; the provider may keep its own grant until you revoke it there."
          }
@@ -994,14 +1044,20 @@
        "title": "Edit the config file",
        "blocks": [
          {
-            "p": "Servers live in `~/.codewhale/mcp.json`. `codewhale mcp init` writes a starter file. The `mcpServers` key used by other clients works too, so you can paste an existing entry."
+            "p": "Global servers live in `~/.codewhale/mcp.json`; the legacy `~/.deepseek/mcp.json` is read when the Codewhale file is absent. `codewhale mcp init` writes a starter file. Use an absolute `mcp_config_path` or `CODEWHALE_MCP_CONFIG` to override it. The environment also accepts `DEEPSEEK_MCP_CONFIG`; the Codewhale name wins when both are set."
          },
          {
-            "code": "{\n  \"servers\": {\n    \"example\": {\n      \"command\": \"node\",\n      \"args\": [\"./path/to/your-mcp-server.js\"],\n      \"env\": {},\n      \"disabled\": false\n    }\n  }\n}",
+            "code": "{\n  \"servers\": {\n    \"cloudflare-docs\": {\n      \"url\": \"https://docs.mcp.cloudflare.com/mcp\"\n    }\n  }\n}",
            "lang": "mcp.json"
          },
          {
-            "p": "After editing the file, run `/mcp reload` in the session; no restart is needed. A server starts only when a turn needs one of its tools, unless you mark it `\"required\": true` to connect at startup."
+            "p": "Use either `servers` or its `mcpServers` alias, never both in one file. `env_http_headers` is an alias for `env_headers`. Adapt the server's documented command, arguments and auth fields rather than assuming every client's configuration format is interchangeable."
+          },
+          {
+            "p": "A trusted workspace can add `.codewhale/mcp.json`. Its entries override same-named global servers; the repository cannot grant itself that trust or override your global config path. Explicit global or trusted-project entries win over a colliding plugin server identity."
+          },
+          {
+            "p": "After editing, run `/mcp reload` in the TUI; no restart is needed. Enabled, allowed servers connect at session start by default. Set `\"lazy\": true` on a user-configured server to connect on demand; `\"required\": true` still connects it at startup. Plugin MCP servers have no lazy manifest option. Headless runtimes need a restart after config changes."
          }
        ]
      },
@@ -1010,10 +1066,44 @@
        "title": "Find the tools",
        "blocks": [
          {
-            "p": "Each tool appears to the model as `mcp_<server>_<tool>`: a server named `git` with a `status` tool becomes `mcp_git_status`. `codewhale mcp tools <server>` lists what a server offers. A server that fails to connect or is disabled never shows up as an available tool."
+            "p": "Each tool appears to the model as `mcp_<server>_<tool>`. For this example, documentation search is `mcp_cloudflare-docs_search_cloudflare_documentation`. `codewhale mcp tools <server>` lists discovered tools in its own process; it does not attach those connections to a running session."
          },
          {
-            "p": "MCP tools follow your [approval setting](/docs/modes): listing and reading a server's resources and prompts can run without a prompt when policy allows, and tools with side effects ask first. Full Access does not override repository rules or managed policy."
+            "p": "MCP tools follow your [approval setting](/docs/modes), allow/deny rules and network policy. Whether a call asks first depends on that policy and posture. Full Access does not override repository rules or managed policy."
+          }
+        ]
+      },
+      {
+        "id": "troubleshooting",
+        "title": "When tools do not appear",
+        "blocks": [
+          {
+            "rows": [
+              [
+                "Check configuration",
+                "Run `codewhale doctor` for static path and configuration diagnostics. Shell `codewhale mcp validate` connects enabled, allowed servers in a separate process; it is a live check."
+              ],
+              [
+                "Refresh this session",
+                "TUI `/mcp validate` shows its last snapshot without reconnecting. Use `/mcp reload` after config changes, or `/mcp retry <name>` for one server."
+              ],
+              [
+                "Connected, but missing a tool",
+                "Check `codewhale mcp tools <server>`, the server's advertised tools, `enabled_tools` / `disabled_tools`, and the session's allow/deny rules. A connected transport alone does not mean a tool is available or permitted."
+              ],
+              [
+                "Authentication required",
+                "For a direct OAuth server, run `/mcp login <name>`. For token auth, check that the variable is present in Codewhale's launch environment. A successful login in one process does not attach its transport to another."
+              ],
+              [
+                "Local command fails",
+                "Check the server's executable, arguments, working directory and runtime. On Windows, package runners may need their `.cmd` name. Follow the server vendor's OS and dependency instructions."
+              ],
+              [
+                "Plugin server is absent",
+                "Check the owning plugin's review, trust and enabled state. MCP settings cannot activate an untrusted plugin or bypass a rejected manifest."
+              ]
+            ]
          }
        ]
      },
@@ -1022,14 +1112,14 @@
        "title": "Run Codewhale as an MCP server",
        "blocks": [
          {
-            "p": "Other MCP clients can use Codewhale as a tool server. By default, it exposes only read-only `file_read` and `search` tools."
+            "p": "A client supporting Codewhale's advertised MCP protocol revisions can launch it as a stdio tool server. By default, it exposes only read-only `file_read` and `search` tools."
          },
          {
            "code": "codewhale mcp add-self\ncodewhale mcp tools codewhale",
            "lang": "Terminal"
          },
          {
-            "p": "`add-self` registers `codewhale serve --mcp` over stdio; `codewhale mcp-server` is the equivalent entry point. Write tools stay withheld unless the operator explicitly permits them in server configuration. [Runtime API](/docs/runtime-api) HTTP is a separate transport."
+            "p": "`add-self` registers `codewhale serve --mcp`; `codewhale mcp-server` is the equivalent entry point. This server reads its separate `[server]` settings from the legacy `~/.deepseek/mcp_server.toml`, not the client `mcp.json`. Write or shell tools require explicit exposure and `require_approval = false`; there is no interactive approval channel. [Runtime API](/docs/runtime-api) HTTP is separate from MCP."
          }
        ]
      },
@@ -1037,6 +1127,9 @@
        "id": "code-mode",
        "title": "Compose tool calls with code mode (experimental)",
        "blocks": [
+          {
+            "note": "This section follows the main candidate's source and can include behavior newer than published v0.10.2."
+          },
          {
            "p": "Code mode lets the model write one short JavaScript program that calls several tools, loops, and filters results, instead of making each call as a separate step. Only the program's final value goes back to the model, which keeps long lookups compact. It is on by default — `execute_tools` is advertised from the first request — and MCP and plugin tools compose inside a program the same way built-in ones do. Turning it off does not remove code mode: `execute_tools` goes back to being deferred, and the model can still find it through `tool_search`. To turn it off for one session, or in config:"
          },
@@ -2075,7 +2168,7 @@
      },
      {
        "title": "Connect your agent",
-        "body": "In Codewhale, install Computer Use with /plugin marketplace install codewhale computer-use, then review and enable the plugin. Other compatible MCP hosts connect to the helper using the setup guide."
+        "body": "Choose the Codewhale setup below for your CLI version. Other compatible MCP hosts use the repository setup guide."
      }
    ],
    "controlsTitle": "Stay in control",
@@ -2085,7 +2178,19 @@
    "help": "Setup and troubleshooting",
    "notes": "Release notes",
    "demo": "See the background check",
-    "source": "Other hosts and platforms",
-    "platforms": "The Mac helper is a beta, and the marketplace plugin supports Mac. Published releases also include an unsigned experimental Windows x64 preview; Linux requires experimental source or Docker setup. Windows and Linux input uses the shared desktop."
+    "source": "View on GitHub",
+    "platforms": "The Mac helper is a beta, and the marketplace plugin supports Mac. Published releases also include an unsigned experimental Windows x64 preview; Linux requires experimental source or Docker setup. Windows and Linux input uses the shared desktop.",
+    "connectTitle": "Connect Codewhale",
+    "connectVersion": "Codewhale 0.10.2 includes an older Computer Use plugin. Installing the catalog entry does not upgrade it. Use the installed Mac helper directly over MCP.",
+    "connectLimit": "Direct MCP adds tools without plugin skills. Do not use it alongside the older built-in plugin. If that plugin is enabled, run /plugin disable computer-use first.",
+    "connectRuntime": "The app includes Node; no separate Node install is needed. If installed elsewhere, set APP to the actual app bundle path.",
+    "connectReload": "In a running terminal session, run /mcp reload, switch to Operate, and ask:",
+    "connectPrompt": "Check Computer Use permissions with request_access. Do not send input.",
+    "connectExpected": "Check for via: app, the helper version and any missing permissions. If the helper is missing, stop and follow the setup hint. This checks the connection and permissions only.",
+    "connectGuide": "MCP setup guide",
+    "contributeTitle": "Help improve Computer Use",
+    "contributeBody": "Improve the docs or test an app workflow and share reproducible results.",
+    "contributeGuide": "Contribution guide",
+    "contributeIssue": "Report an issue"
  }
 }
@@ -804,7 +804,7 @@
            "codeTerms": true
          },
          {
-            "p": "密钥、服务端点、提供商选择、MCP 服务器、钩子、技能和额外的说明文件，始终来自你自己的配置，因此克隆下来的仓库无法让 Codewhale 指向它自己的服务器或文件。启动时加上 `--no-project-config`，可以在这一次运行中忽略仓库的配置文件。"
+            "p": "提供商密钥、服务端点及提供商选择来自你自己的配置。在用户设置中信任工作区后，MCP 服务器也可来自 `.codewhale/mcp.json`；项目条目覆盖同名的全局条目。信任仓库前，请审阅这些可执行权限。参阅 [MCP 配置](/docs/mcp#config)。"
          },
          {
            "p": "项目说明——智能体在这个仓库里应该如何工作——请写在 `AGENTS.md` 中。运行 `/init` 即可生成一份。"
@@ -949,27 +949,74 @@
  },
  "docs-mcp": {
    "metaTitle": "用 MCP 连接工具 · Codewhale 文档",
-    "metaDescription": "添加 Model Context Protocol 服务器让 Codewhale 使用更多工具，登录远程服务器，把 Codewhale 本身作为 MCP 服务器运行，并试用代码模式。",
+    "metaDescription": "连接本地和远程 MCP 服务器，了解认证与插件兼容范围，并排查工具未显示的问题。",
    "bodyClassName": "text-ink-soft leading-[1.9] tracking-wide",
    "title": "用 MCP 连接工具",
-    "lede": "MCP 服务器能为 Codewhale 带来更多工具——数据库、问题跟踪系统、浏览器等。你可以添加一个由 Codewhale 替你启动的本地服务器，也可以通过 URL 添加远程服务器。这些工具与内置工具走同一套审批流程。",
+    "lede": "通过 Model Context Protocol 连接本地工具服务器或远程服务。Codewhale 会发现服务器提供的工具，并在使用时执行你的工具权限和审批规则。",
    "sections": [
      {
        "id": "add",
-        "title": "添加服务器",
+        "title": "试用 Cloudflare Docs 服务器",
        "blocks": [
          {
-            "code": "codewhale mcp add git --command \"uvx\" --arg \"mcp-server-git\"\ncodewhale mcp add docs --url \"https://example.com/mcp\"\ncodewhale mcp list\ncodewhale mcp validate",
+            "p": "公开的 [Cloudflare 文档服务器](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/)提供文档搜索和 Pages 迁移到 Workers 的指南。[查看官方源码](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize)。无需凭据即可添加："
+          },
+          {
+            "code": "codewhale mcp add cloudflare-docs --url \"https://docs.mcp.cloudflare.com/mcp\"\ncodewhale mcp tools cloudflare-docs",
            "lang": "终端"
          },
          {
-            "p": "`--command` 通过 stdio 启动本地服务器，每个参数用一个 `--arg`。`--url` 通过 Streamable HTTP 连接远程服务器，必要时回退到旧版 SSE。`mcp validate` 会检查配置文件以及你标记为必需的服务器。"
+            "p": "工具列表应包含 `search_cloudflare_documentation` 和 `migrate_pages_to_workers_guide`。如果 TUI 会话已在运行，请在其中执行 `/mcp reload`，把新配置加载到该会话。"
+          },
+          {
+            "note": "2026 年 11 月 7 日使用已发布的 CLI v0.10.2 检查：两条命令均成功退出，无需凭据即可列出上述两个工具。这验证了配置和发现流程，没有执行工具。[发布版指南](https://github.com/codewhale-hq/Codewhale/blob/v0.10.2/docs/MCP.md)对应此版本；[main 源码指南](https://github.com/codewhale-hq/Codewhale/blob/main/docs/MCP.md)可能包含尚未发布的变更。"
          },
          {
            "p": "在会话中，`/mcp` 会打开 MCP 管理器：显示每个服务器的状态、传输方式、超时设置、错误信息和已发现的工具。同样的操作在那里也能完成，例如 `/mcp add stdio <name> <command>` 和 `/mcp add http <name> <url>`。"
          },
          {
-            "note": "MCP 服务器以你的权限运行。只添加你信任的服务器，就像只安装你信任的程序一样。"
+            "note": "本地 MCP 服务器以 Codewhale 进程的权限运行；远程调用使用你授予该服务的访问权限。只添加你信任的服务器。"
+          }
+        ]
+      },
+      {
+        "id": "compatibility",
+        "title": "可以连接哪些服务器",
+        "blocks": [
+          {
+            "rows": [
+              [
+                "本地 stdio",
+                "Codewhale 启动 `--command` 指定的程序，每个参数用一个 `--arg`。请先安装服务器及其所需运行时。"
+              ],
+              [
+                "远程 HTTP / SSE",
+                "`--url` 使用 Streamable HTTP，并可回退到旧版 SSE。旧版 SSE 端点可设置 `--transport sse`。远程配置不需要 `command`。"
+              ],
+              [
+                "直接配置的远程认证",
+                "你自己的 MCP 配置可以使用环境变量请求头、bearer token 或 OAuth。OAuth 需要服务器提供兼容的认证元数据和客户端注册方式。"
+              ],
+              [
+                "插件提供的 MCP",
+                "经过审查并启用的插件可以提供 stdio 或远程 MCP 服务器。插件 MCP 支持基于环境变量的认证，但不支持插件提供的 MCP OAuth。"
+              ],
+              [
+                "工具、资源与提示词",
+                "Codewhale 发现服务器实际声明的能力。只有服务器实现了资源、模板或提示词功能，才能使用这些功能。"
+              ],
+              [
+                "可选扩展与 MCP Apps",
+                "尚不提供通用的 MCP Apps 界面支持。支持基本 MCP 传输不等于兼容所有可选扩展或服务器。"
+              ],
+              [
+                "服务器要求",
+                "每个服务器都有自己的操作系统、程序、浏览器、依赖和账号要求。本地服务器运行在承载 Codewhale 的电脑上；Computer Use 有其独立的平台限制。"
+              ]
+            ]
+          },
+          {
+            "p": "直接添加 MCP 不需要插件。[插件](/plugins)可以把 MCP 工具、指令和其他组件打包在一起；各组件仍需要兼容的依赖、审查和权限。"
          }
        ]
      },
@@ -978,12 +1025,15 @@
        "title": "登录远程服务器",
        "blocks": [
          {
-            "p": "使用 OAuth 的服务器，先用 URL 添加再登录。使用 bearer token 的服务器，把令牌放在环境变量里，而不是写进配置文件："
+            "p": "直接配置 OAuth 服务器时，先添加它的真实 URL，再用你设置的服务器名称登录："
          },
          {
-            "code": "codewhale mcp login docs\ncodewhale mcp add tracker --url \"https://example.com/mcp\" --bearer-token-env-var TRACKER_TOKEN",
+            "code": "codewhale mcp login <server>\ncodewhale mcp logout <server>",
            "lang": "终端"
          },
+          {
+            "p": "使用 bearer token 时，添加服务器时指定 `--bearer-token-env-var TOKEN_NAME`，并在启动 Codewhale 的环境中设置该变量。`env_headers` 把请求头名称映射到环境变量名。字面量 `headers` 不会展开 `${TOKEN_NAME}`。插件 MCP 不能使用 OAuth；需要 OAuth 时，请直接配置该服务器。"
+          },
          {
            "p": "显式设置的 Authorization 请求头始终优先：先应用配置中的请求头，其次是 bearer token 环境变量，最后才是已保存的 OAuth 登录。`codewhale mcp logout <name>` 会删除本机保存的登录信息；提供商那边的授权可能仍然有效，需要到提供商处撤销。"
          }
@@ -994,14 +1044,20 @@
        "title": "编辑配置文件",
        "blocks": [
          {
-            "p": "服务器配置保存在 `~/.codewhale/mcp.json`，`codewhale mcp init` 会生成一个初始文件。其他客户端使用的 `mcpServers` 键同样可用，现成的配置可以直接粘贴进来。"
+            "p": "全局服务器配置保存在 `~/.codewhale/mcp.json`；如果该文件不存在，仍会读取旧版 `~/.deepseek/mcp.json`。`codewhale mcp init` 会生成初始文件。可用绝对路径 `mcp_config_path` 或 `CODEWHALE_MCP_CONFIG` 覆盖默认位置。环境变量也接受 `DEEPSEEK_MCP_CONFIG`；两者都设置时，Codewhale 名称优先。"
          },
          {
-            "code": "{\n  \"servers\": {\n    \"example\": {\n      \"command\": \"node\",\n      \"args\": [\"./path/to/your-mcp-server.js\"],\n      \"env\": {},\n      \"disabled\": false\n    }\n  }\n}",
+            "code": "{\n  \"servers\": {\n    \"cloudflare-docs\": {\n      \"url\": \"https://docs.mcp.cloudflare.com/mcp\"\n    }\n  }\n}",
            "lang": "mcp.json"
          },
          {
-            "p": "修改文件后，在会话中运行 `/mcp reload` 即可，无需重启。服务器只在某个回合需要它的工具时才启动；如果希望它在启动时就连接，把它标记为 `\"required\": true`。"
+            "p": "`servers` 和别名 `mcpServers` 二选一，不要在同一文件中同时使用。`env_http_headers` 是 `env_headers` 的别名。请按服务器文档调整命令、参数和认证字段，不要假定所有客户端的配置格式都能直接互换。"
+          },
+          {
+            "p": "受信任的工作区可以提供 `.codewhale/mcp.json`，其中同名服务器会覆盖全局配置；仓库不能自行授予信任，也不能覆盖你的全局配置路径。全局或受信任项目中的显式配置，优先于标识冲突的插件服务器。"
+          },
+          {
+            "p": "修改后在 TUI 中运行 `/mcp reload` 即可，无需重启。默认情况下，已启用且获准的服务器会在会话启动时连接。用户配置的服务器可设置 `\"lazy\": true` 按需连接；设置 `\"required\": true` 后仍会在启动时连接。插件 MCP 清单没有 lazy 选项。无界面的运行时在配置变更后需要重启。"
          }
        ]
      },
@@ -1010,10 +1066,44 @@
        "title": "找到这些工具",
        "blocks": [
          {
-            "p": "每个工具在模型眼中的名字是 `mcp_<server>_<tool>`：名为 `git` 的服务器提供的 `status` 工具，就叫 `mcp_git_status`。`codewhale mcp tools <server>` 会列出某个服务器提供的工具。连接失败或已禁用的服务器，其工具永远不会显示为可用。"
+            "p": "每个工具在模型眼中的名字是 `mcp_<server>_<tool>`。本例中的文档搜索是 `mcp_cloudflare-docs_search_cloudflare_documentation`。`codewhale mcp tools <server>` 在自己的进程中列出发现的工具，不会把连接附加到正在运行的会话。"
          },
          {
-            "p": "MCP 工具遵循你的[审批设置](/docs/modes)：在策略允许时，列出和读取服务器的资源与提示词无需确认；有副作用的工具会先征求你的同意。Full Access 也不会绕过仓库规则或托管策略。"
+            "p": "MCP 工具遵循你的[审批设置](/docs/modes)、允许/拒绝规则及网络策略。调用前是否询问，取决于策略与权限姿态。Full Access 不会绕过仓库规则或托管策略。"
+          }
+        ]
+      },
+      {
+        "id": "troubleshooting",
+        "title": "工具没有出现时",
+        "blocks": [
+          {
+            "rows": [
+              [
+                "检查配置",
+                "`codewhale doctor` 提供静态路径和配置诊断。终端中的 `codewhale mcp validate` 会在独立进程中连接已启用且获准的服务器，属于实际连接检查。"
+              ],
+              [
+                "刷新当前会话",
+                "TUI 中的 `/mcp validate` 只显示上次快照，不会重新连接。配置变更后使用 `/mcp reload`；单个服务器可用 `/mcp retry <name>`。"
+              ],
+              [
+                "已连接但缺少工具",
+                "检查 `codewhale mcp tools <server>`、服务器声明的工具、`enabled_tools` / `disabled_tools`，以及会话的允许/拒绝规则。传输已连接不代表某个工具可用或已获准。"
+              ],
+              [
+                "需要认证",
+                "直接配置的 OAuth 服务器可运行 `/mcp login <name>`。令牌认证请检查变量是否存在于 Codewhale 的启动环境中。在一个进程中登录成功，不会把该进程的连接附加到另一个进程。"
+              ],
+              [
+                "本地命令失败",
+                "检查服务器程序、参数、工作目录和运行时。Windows 上的包运行器可能需要使用 `.cmd` 名称。请遵循服务器提供方的操作系统和依赖说明。"
+              ],
+              [
+                "插件服务器缺失",
+                "检查所属插件的审查、信任和启用状态。MCP 设置不能激活不受信任的插件，也不能绕过被拒绝的清单。"
+              ]
+            ]
          }
        ]
      },
@@ -1022,14 +1112,14 @@
        "title": "把 Codewhale 作为 MCP 服务器运行",
        "blocks": [
          {
-            "p": "其他 MCP 客户端可以把 Codewhale 作为工具服务器。默认仅暴露只读的 `file_read` 和 `search` 工具。"
+            "p": "支持 Codewhale 声明的 MCP 协议版本的客户端，可以把它作为 stdio 工具服务器启动。默认仅暴露只读的 `file_read` 和 `search` 工具。"
          },
          {
            "code": "codewhale mcp add-self\ncodewhale mcp tools codewhale",
            "lang": "终端"
          },
          {
-            "p": "`add-self` 注册通过 stdio 运行的 `codewhale serve --mcp`；`codewhale mcp-server` 是等价入口。除非操作者在服务器配置中明确允许，否则不会提供写入工具。[Runtime API](/docs/runtime-api) HTTP 是单独的传输方式。"
+            "p": "`add-self` 注册 `codewhale serve --mcp`；`codewhale mcp-server` 是等价入口。这个服务器从旧版路径 `~/.deepseek/mcp_server.toml` 读取独立的 `[server]` 设置，而不是客户端的 `mcp.json`。写入或 shell 工具需要显式列出，并设置 `require_approval = false`；这里没有交互式审批通道。[Runtime API](/docs/runtime-api) HTTP 与 MCP 分开。"
          }
        ]
      },
@@ -1037,6 +1127,9 @@
        "id": "code-mode",
        "title": "用代码模式组合工具调用（实验性）",
        "blocks": [
+          {
+            "note": "本节依据 main 候选版本的源码，可能包含比已发布 v0.10.2 更新的行为。"
+          },
          {
            "p": "代码模式让模型写一段简短的 JavaScript 程序，在其中调用多个工具、循环和筛选结果，而不必把每次调用都作为单独的一步。只有程序的最终结果会返回给模型，长时间的查找因此更紧凑。它默认开启——`execute_tools` 从第一条请求起就会提供——MCP 和插件工具与内置工具一样可以在程序中组合调用。关闭它并不会移除代码模式：`execute_tools` 会恢复为延迟加载，模型仍可通过 `tool_search` 找到它。要关闭它，可以只在一次会话中关闭，也可以在配置中关闭："
          },
@@ -2075,7 +2168,7 @@
      },
      {
        "title": "连接智能体",
-        "body": "在 Codewhale 中运行 /plugin marketplace install codewhale computer-use，审阅并启用插件。其他兼容 MCP 的宿主可按设置指南连接助手。"
+        "body": "选择下方适用于你的 CLI 版本的 Codewhale 设置方式。其他兼容 MCP 的宿主请参阅仓库中的设置指南。"
      }
    ],
    "controlsTitle": "随时掌握控制权",
@@ -2085,7 +2178,19 @@
    "help": "设置与故障排查",
    "notes": "版本说明",
    "demo": "查看后台检查演示",
-    "source": "其他宿主与平台",
-    "platforms": "Mac 助手为测试版，市场插件支持 Mac。已发布版本另含未签名的 Windows x64 实验性预览包；Linux 需要实验性源码或 Docker 设置。Windows 和 Linux 的输入使用共享桌面。"
+    "source": "在 GitHub 上查看",
+    "platforms": "Mac 助手为测试版，市场插件支持 Mac。已发布版本另含未签名的 Windows x64 实验性预览包；Linux 需要实验性源码或 Docker 设置。Windows 和 Linux 的输入使用共享桌面。",
+    "connectTitle": "连接 Codewhale",
+    "connectVersion": "Codewhale 0.10.2 内置较旧的 Computer Use 插件，安装目录中的同名条目不会将其升级。请通过 MCP 直接连接已安装的 Mac 助手。",
+    "connectLimit": "直接连接 MCP 只添加工具，不包含插件技能。请勿与旧版内置插件同时使用；如果该插件已启用，请先运行 /plugin disable computer-use。",
+    "connectRuntime": "应用自带 Node，无需另行安装。如果应用安装在其他位置，请将 APP 设为实际应用包路径。",
+    "connectReload": "在正在运行的终端会话中执行 /mcp reload，切换到 Operate，然后输入：",
+    "connectPrompt": "使用 request_access 检查 Computer Use 权限。不要发送任何输入。",
+    "connectExpected": "检查回复中的 via: app、助手版本及缺少的权限。如果找不到助手，请停止并按设置提示操作。此步骤仅检查连接和权限。",
+    "connectGuide": "MCP 设置指南",
+    "contributeTitle": "一起改进 Computer Use",
+    "contributeBody": "完善文档，或测试应用操作流程并分享可复现的结果。",
+    "contributeGuide": "贡献指南",
+    "contributeIssue": "报告问题"
  }
 }
@@ -1,16 +1,16 @@
 import type { LocalizedText } from "./vocabulary";

 export const PLUGINS_COPY = {
-  metaTitle: { en: "Plugins and marketplace · Codewhale", zh: "插件与市场 · Codewhale" },
+  metaTitle: { en: "Plugins, skills and MCP servers · Codewhale", zh: "插件与市场 · Codewhale" },
  metaDescription: {
-    en: "Let the agent operate the desktop apps you choose with Computer Use, and install reviewed plugins from the Codewhale catalog, a GitHub repository, or a tarball.",
-    zh: "用 Computer Use 让代理操作你选定的桌面应用，并从 Codewhale 目录、GitHub 仓库或压缩包安装经过审阅的插件。",
+    en: "Connect local and remote MCP servers, add reusable skills, and install reviewed plugins for browser work, documentation, code review and desktop apps.",
+    zh: "连接本地与远程 MCP 服务器、加载可复用的技能，并安装用于浏览器、文档、代码审阅和桌面应用的已审阅插件。",
  },
  kicker: { en: "Plugins and marketplace", zh: "插件与市场" },
-  title: { en: "Add tools and skills with plugins", zh: "通过插件添加工具和技能" },
+  title: { en: "Connect your tools to Codewhale", zh: "将你的工具连接到 Codewhale" },
  lead: {
-    en: "Add skills and tools from the Codewhale catalog, a GitHub repository or a tarball. Review, trust and enable each plugin before use.",
-    zh: "从 Codewhale 目录、GitHub 仓库或压缩包添加技能和工具。使用前，先审阅、确认信任并启用插件。",
+    en: "Connect an MCP server for tools, load a skill for instructions, or install a plugin that packages both. You choose which integrations run.",
+    zh: "连接 MCP 服务器来添加工具，加载技能来复用指令，或安装将两者打包的插件。由你决定运行哪些集成。",
  },
  marketplaceCta: { en: "Browse the Codewhale catalog", zh: "浏览 Codewhale 目录" },
  docsCta: { en: "Plugin authoring guide", zh: "插件编写指南" },
@@ -22,7 +22,6 @@ export const PLUGINS_COPY = {
    en: "Let an agent work in Mac apps while you keep using your computer. Connect the Computer Use helper and plugin to Codewhale or another compatible MCP host.",
    zh: "智能体在 Mac 应用中后台操作，你可以继续使用电脑。将 Computer Use 助手和插件连接到 Codewhale 或其他兼容 MCP 的宿主。",
  },
-  cuInstall: { en: "/plugin marketplace install codewhale computer-use", zh: "/plugin marketplace install codewhale computer-use" },
  cuFeatures: [
    {
      title: { en: "Works in the background", zh: "后台工作" },
@@ -89,53 +88,27 @@ export const PLUGINS_COPY = {
  catalogLabel: { en: "First-party catalog", zh: "官方目录" },
  catalogTitle: { en: "Browse Codewhale plugins", zh: "浏览 Codewhale 插件" },
  catalogLead: {
-    en: "An offline snapshot of the Codewhale catalog ships with the terminal, so browsing never fetches or runs anything. Install from it with one command.",
-    zh: "终端内置 Codewhale 目录的离线快照，浏览时不会拉取或运行任何内容。一条命令即可安装。",
+    en: "These are examples from the public Codewhale catalog. The terminal ships an offline snapshot: available entries and pinned versions depend on your CLI release. Browsing the catalog runs nothing.",
+    zh: "以下是公开 Codewhale 目录中的部分示例。终端内置离线快照，条目及固定版本取决于 CLI 版本；浏览目录不会运行任何内容。",
  },
  catalogBrowse: { en: "/plugin marketplace list", zh: "/plugin marketplace list" },
-  catalogEntries: [
-    {
-      title: { en: "WhaleWiki", zh: "WhaleWiki" },
-      detail: {
-        en: "Repository and concept documentation the agent can consult while it works.",
-        zh: "供代理在工作时查阅的仓库与概念文档。",
-      },
-      reference: "/plugin marketplace install codewhale whalewiki",
-    },
-    {
-      title: { en: "Cloudflare Docs", zh: "Cloudflare 文档" },
-      detail: {
-        en: "Cloudflare documentation lookup inside a session.",
-        zh: "在会话内查询 Cloudflare 文档。",
-      },
-      reference: "/plugin marketplace install codewhale cloudflare-docs",
-    },
-    {
-      title: { en: "Skill bundle", zh: "技能包" },
-      detail: {
-        en: "The bundled Codewhale skills the terminal ships with, kept in sync with the catalog.",
-        zh: "终端内置的 Codewhale 技能集，与目录保持同步。",
-      },
-      reference: "#path=skills",
-    },
-  ],
  catalogNote: {
    en: "Catalog source: github.com/codewhale-hq/codewhale-plugin-marketplace. A local catalog named codewhale takes precedence over the bundled snapshot.",
    zh: "目录来源：github.com/codewhale-hq/codewhale-plugin-marketplace。名为 codewhale 的本地目录优先于内置快照。",
  },

  sourcesLabel: { en: "Install sources", zh: "安装来源" },
-  sourcesTitle: { en: "Install from a repository, folder, or tarball.", zh: "从仓库、文件夹或压缩包安装。" },
+  sourcesTitle: { en: "Install a bundle from its source", zh: "从来源安装插件包" },
  sourcesLead: {
-    en: "Point /plugin install at a directory, a repository, or a tarball. The fetched tree must hold exactly one bundle root: a plugin.json, a compatible kimi.plugin.json or .claude-plugin/plugin.json, or a legacy plugin.toml.",
-    zh: "/plugin install 可以指向目录、仓库或压缩包。获取的目录树必须恰好包含一个 bundle 根：plugin.json、兼容的 kimi.plugin.json 或 .claude-plugin/plugin.json，或旧版 plugin.toml。",
+    en: "Point /plugin install at a directory, a GitHub repository, a tarball, or an exact-version npm package. The fetched tree must hold exactly one bundle root: a plugin.json, a compatible kimi.plugin.json or .claude-plugin/plugin.json, or a legacy plugin.toml.",
+    zh: "/plugin install 可以指向目录、GitHub 仓库、压缩包或指定版本的 npm 包。获取的目录树必须恰好包含一个 bundle 根：plugin.json、兼容的 kimi.plugin.json 或 .claude-plugin/plugin.json，或旧版 plugin.toml。",
  },
  sources: [
    {
      title: { en: "GitHub repository", zh: "GitHub 仓库" },
      detail: {
-        en: "Fetches an archive of the default branch, the same mechanism the marketplace catalog uses.",
-        zh: "获取默认分支的归档，市场目录也使用这一机制。",
+        en: "Fetches a repository archive. Pin a commit for repeatable installs.",
+        zh: "获取仓库归档。固定提交可实现可重复安装。",
      },
      reference: "/plugin install github:owner/repo",
    },
@@ -155,6 +128,11 @@ export const PLUGINS_COPY = {
      },
      reference: "/plugin install https://example.com/x.tar.gz",
    },
+    {
+      title: { en: "Version-pinned npm package", zh: "固定版本的 npm 包" },
+      detail: { en: "Fetches the exact tarball without lifecycle scripts or dependency installation. It must contain a supported native plugin manifest.", zh: "获取指定版本的压缩包，不运行生命周期脚本或安装依赖。包中须包含受支持的原生插件清单。" },
+      reference: "/plugin install npm:@example/[email protected]",
+    },
  ],

  trustLabel: { en: "Trust lifecycle", zh: "信任生命周期" },
@@ -181,8 +159,8 @@ export const PLUGINS_COPY = {
    {
      title: { en: "Enable", zh: "启用" },
      detail: {
-        en: "/plugin enable <name> activates the bundle. Plugin-contributed MCP servers run under namespaced <plugin>-<server> identities with the stricter boundary.",
-        zh: "/plugin enable <name> 激活 bundle。插件提供的 MCP 服务以 <plugin>-<server> 命名空间身份运行，适用更严格的边界。",
+        en: "/plugin enable <name> activates the bundle. Plugin-contributed MCP servers use namespaced identities and the plugin’s reviewed permissions.",
+        zh: "/plugin enable <name> 激活 bundle。插件提供的 MCP 服务器使用带命名空间的身份，受已审阅的插件权限约束。",
      },
    },
  ],
@@ -215,3 +193,39 @@ export const PLUGIN_COMMANDS = [
  "/plugin update <name>",
  "/plugin suggest <task>",
 ] as const;
+
+export const INTEGRATIONS_COPY = {
+  chooseTitle: { en: "Plugin, skill, or MCP server?", zh: "插件、技能，还是 MCP 服务器？" },
+  chooseLead: { en: "Start with what you want to add.", zh: "根据你想添加的能力选择。" },
+  mcpTitle: { en: "Connect an MCP server directly", zh: "直接连接 MCP 服务器" },
+  mcpLead: { en: "Use local tools over stdio or a remote service over Streamable HTTP. Direct remote connections can use OAuth or environment-backed tokens. A plugin is optional.", zh: "通过 stdio 使用本地工具，或通过 Streamable HTTP 连接远程服务。直接连接的远程服务器可使用 OAuth 或环境变量令牌，无需安装插件。" },
+  mcpLink: { en: "MCP setup, authentication and troubleshooting", zh: "MCP 设置、认证与故障排查" },
+  compatibilityTitle: { en: "Which plugin formats work?", zh: "支持哪些插件格式？" },
+  compatibilityLead: { en: "Compatibility depends on the capabilities inside a bundle. A recognized manifest does not mean every feature from another host will run.", zh: "兼容性取决于插件包含的能力。能识别清单，并不代表其他宿主的每项功能都能运行。" },
+  contributeTitle: { en: "Share an integration", zh: "分享你的集成" },
+  contributeLead: { en: "Package a useful workflow, document its dependencies, and show what you verified. The authoring guide covers a local bundle; the catalog repository is where to propose an entry or improve an existing one.", zh: "将实用工作流打包，说明依赖并提供验证结果。编写指南介绍本地插件包；新增目录条目或改进现有条目，请前往目录仓库。" },
+  catalogLink: { en: "Contribute to the catalog", zh: "参与目录贡献" },
+  cuSetupNote: { en: "The published CLI v0.10.2 includes an older Computer Use bundle. Installing the catalog entry does not upgrade that built-in copy. Follow the version-specific setup before connecting the current Mac helper.", zh: "已发布的 CLI v0.10.2 内置较旧的 Computer Use 插件。安装目录条目不会升级内置副本。连接当前 Mac 助手前，请按对应版本的指南设置。" },
+} satisfies Record<string, LocalizedText>;
+
+export const INTEGRATION_CHOICES = [
+  { title: { en: "Skill", zh: "技能" }, detail: { en: "Reusable Markdown instructions for a task. Uses the tools already available; it does not create a new service connection.", zh: "可复用的 Markdown 任务指令。使用已有工具，不会自行创建服务连接。" }, href: "/docs/skills" },
+  { title: { en: "MCP server", zh: "MCP 服务器" }, detail: { en: "An external program or service that exposes tools, resources or prompts. Configure its command or URL and authentication.", zh: "提供工具、资源或提示词的外部程序或服务。配置命令或 URL 以及认证方式。" }, href: "/docs/mcp" },
+  { title: { en: "Plugin", zh: "插件" }, detail: { en: "A reviewed bundle of skills, commands, agent profiles, hooks, MCP servers or provider declarations. Install, review, trust, then enable.", zh: "将技能、命令、代理配置、钩子、MCP 服务器或模型提供商声明打包。安装、审阅、信任后再启用。" }, href: "#trust-title" },
+];
+
+export const PLUGIN_EXAMPLES = [
+  { name: "cloudflare-docs", title: "Cloudflare Docs", detail: { en: "Look up Cloudflare documentation with a remote MCP server and skill. No credentials required.", zh: "通过远程 MCP 服务器与技能查阅 Cloudflare 文档，无需凭据。" } },
+  { name: "chromewhale", title: "Codewhale for Chrome", detail: { en: "Work in signed-in Chrome through local MCP. Requires Node and the separate browser extension, with per-site grants.", zh: "通过本地 MCP 操作已登录的 Chrome。需要 Node 和独立浏览器扩展，并按站点授权。" } },
+  { name: "github-workflow", title: "GitHub Workflow", detail: { en: "Review issues and pull requests with skills, commands and GitHub’s remote MCP. Requires your GitHub token; review its scopes.", zh: "使用技能、命令及 GitHub 远程 MCP 审阅问题与拉取请求。需要 GitHub 令牌，请审阅其权限范围。" } },
+  { name: "linear-workflow", title: "Linear Workflow", detail: { en: "Turn issue context into a plan with skills, commands and remote MCP. Requires a Linear API key.", zh: "通过技能、命令及远程 MCP 根据问题上下文制定计划。需要 Linear API 密钥。" } },
+  { name: "review-toolkit", title: "Review Toolkit", detail: { en: "Use focused review agent profiles, a command and a skill. Adds no MCP server or service login.", zh: "使用专门的审阅代理配置、命令和技能。不添加 MCP 服务器，也无需服务登录。" } },
+  { name: "whalewiki", title: "WhaleWiki", detail: { en: "Research a repository with a skill, command, agent profile and local MCP. Requires Node.", zh: "通过技能、命令、代理配置及本地 MCP 研究仓库。需要 Node。" } },
+];
+
+export const PLUGIN_COMPATIBILITY = [
+  { title: { en: "Codewhale / Agent Plugins v1", zh: "Codewhale / Agent Plugins v1" }, detail: { en: "Declarative skills, commands, agent profiles, hooks, MCP and provider declarations. Native TypeScript extensions are experimental and require extension_host; declaring LSP or filesystem roots does not activate them.", zh: "支持声明式技能、命令、代理配置、钩子、MCP 及模型提供商声明。原生 TypeScript 扩展为实验功能，需启用 extension_host；声明 LSP 或文件系统根目录不会启用对应能力。" }, href: "https://github.com/codewhale-hq/Codewhale/blob/main/docs/PLUGIN_AUTHORING.md" },
+  { title: { en: "Claude Code and Kimi bundles", zh: "Claude Code 与 Kimi 插件包" }, detail: { en: "Compatible skills, commands, agent profiles and MCP declarations can be imported. Claude hooks, LSP, custom MCP paths and plugin-root expansion are rejected. Review the imported capabilities.", zh: "可导入兼容的技能、命令、代理配置及 MCP 声明。Claude 钩子、LSP、自定义 MCP 路径及插件根路径展开会被拒绝。请审阅导入的能力。" }, href: "/docs/claude-code" },
+  { title: { en: "DeepSeek Harness (DSH)", zh: "DeepSeek Harness（DSH）" }, detail: { en: "Import work is in progress. Full published-plugin workflows and interactive views are not release-qualified; do not assume a DSH package runs unchanged.", zh: "导入兼容工作进行中。已发布插件的完整工作流及交互视图尚未通过发布验证，请勿假定 DSH 包可直接运行。" }, href: "https://github.com/codewhale-hq/Codewhale/blob/main/docs/DSH_PLUGIN_COMPAT.md" },
+  { title: { en: "MCP authentication and UI", zh: "MCP 认证与界面" }, detail: { en: "Plugin-bundled MCP does not support OAuth: configure that server directly instead. MCP Apps UI and every optional protocol feature are not generally supported.", zh: "插件内的 MCP 不支持 OAuth，请改为直接配置服务器。MCP Apps 界面及所有可选协议功能并非普遍受支持。" }, href: "/docs/mcp#compatibility" },
+];
@@ -251,11 +251,12 @@ export const DOC_TOPICS: DocTopic[] = [
    slug: "plugins",
    label: { en: "Add plugins", zh: "添加插件" },
    description: {
-      en: "Find, install, review, and trust plugin bundles.",
-      zh: "查找、安装、审查并信任插件包。",
+      en: "Choose plugin formats, browse catalog examples, and review, trust and enable bundles.",
+      zh: "选择插件格式，浏览目录示例，并审阅、信任和启用插件包。",
    },
-    repoSource: ["docs/PLUGINS.md", "docs/PLUGIN_BUNDLES.md", "docs/EXTENSIONS.md"],
-    hasPage: false,
+    repoSource: ["docs/PLUGINS.md", "docs/PLUGIN_BUNDLES.md", "docs/PLUGIN_MARKETPLACE.md", "docs/EXTENSIONS.md"],
+    hasPage: true,
+    sitePath: "plugins",
    category: "extending",
  },
  {
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "ثبّت التطبيق", body: "افتح صورة القرص واسحب Codewhale Computer Use إلى مجلد «التطبيقات». افتحه من «التطبيقات»، ثم اختر Computer Use من أيقونة الحوت في شريط القوائم." },
    { title: "راجع الأذونات", body: "استخدم أزرار الإعداد لفتح «تسهيلات الاستخدام» و«تسجيل الشاشة» في إعدادات النظام. أنت من يقرر الأذونات التي تمنحها." },
-    { title: "اربط وكيلك", body: "في Codewhale، ثبّت Computer Use بالأمر /plugin marketplace install codewhale computer-use، ثم راجع الإضافة وفعّلها. يُثبّت المساعد بشكل منفصل. يمكن لمضيفي MCP المتوافقين الآخرين الاتصال به باتباع دليل الإعداد." },
+    { title: "اربط وكيلك", body: "اختر إعداد Codewhale أدناه المناسب لإصدار CLI لديك. أما مضيفات MCP الأخرى المتوافقة فتستخدم دليل الإعداد في المستودع." },
  ],
  controlsTitle: "التحكم بيدك",
  controlsBody: "بعد منح أذونات macOS، يعمل الوضع القياسي دون طلب إذن لكل تطبيق. تظل التطبيقات التي تحظرها خارج نطاق الوصول؛ يعلّق Pause استخدام الكمبيوتر، وينهي Stop computer use الجلسات الحالية. وضع الموافقة الصارم اختياري. اطلب معاينة مباشرة عندما تريد متابعة العمل.",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "الإعداد واستكشاف الأخطاء وإصلاحها",
  notes: "ملاحظات الإصدار",
  demo: "شاهد فحص الخلفية",
-  source: "المصدر والمنصات الأخرى",
+  source: "عرض على GitHub",
  platforms: "مساعد Mac في مرحلة بيتا، وإضافة السوق متاحة لنظام Mac فقط. تتضمن الإصدارات المنشورة أيضًا معاينة تجريبية غير موقّعة لنظام Windows x64؛ ويتطلب Linux إعدادًا تجريبيًا من المصدر أو عبر Docker. يستخدم الإدخال في Windows وLinux سطح المكتب المشترك.",
+  connectTitle: "ربط Codewhale",
+  connectVersion: "يتضمن Codewhale 0.10.2 إضافة Computer Use قديمة. تثبيت مدخل الكتالوج لا يحدّثها. اتصل بمساعد Mac المثبّت مباشرة عبر MCP.",
+  connectLimit: "يضيف اتصال MCP المباشر أدوات دون مهارات الإضافة. لا تستخدمه بالتزامن مع الإضافة المدمجة القديمة. إذا كانت مفعّلة، فنفّذ /plugin disable computer-use أولاً.",
+  connectRuntime: "يتضمن التطبيق Node؛ لا حاجة إلى تثبيته بشكل منفصل. إذا كان التطبيق مثبّتاً في مكان آخر، فاضبط APP على المسار الفعلي لحزمة التطبيق.",
+  connectReload: "في جلسة طرفية قيد التشغيل، نفّذ /mcp reload، ثم انتقل إلى Operate واطلب:",
+  connectPrompt: "تحقّق من أذونات Computer Use باستخدام request_access. لا ترسل أي إدخال.",
+  connectExpected: "تحقّق من via: app وإصدار المساعد والأذونات الناقصة في الرد. إذا كان المساعد غير موجود، فتوقّف واتبع إرشادات الإعداد. يتحقّق هذا من الاتصال والأذونات فقط.",
+  connectGuide: "دليل إعداد MCP",
+  contributeTitle: "ساهم في تحسين Computer Use",
+  contributeBody: "حسّن التوثيق أو اختبر سير عمل في أحد التطبيقات وشارك نتائج قابلة لإعادة الإنتاج.",
+  contributeGuide: "دليل المساهمة",
+  contributeIssue: "الإبلاغ عن مشكلة",
 };
@@ -27,7 +27,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Instal·la l’aplicació", body: "Obre la imatge de disc i arrossega Codewhale Computer Use a «Aplicacions». Obre-la des d’«Aplicacions» i tria Computer Use a la icona de la balena de la barra de menús." },
    { title: "Revisa els permisos", body: "Fes servir els botons de configuració per obrir «Accessibilitat» i «Gravació de pantalla» a Configuració del Sistema. Tu decideixes quins permisos concedeixes." },
-    { title: "Connecta el teu agent", body: "A Codewhale, instal·la Computer Use amb /plugin marketplace install codewhale computer-use i, després, revisa i activa el connector. L’ajudant s’instal·la per separat. Altres amfitrions MCP compatibles s’hi connecten seguint la guia de configuració." },
+    { title: "Connecta el teu agent", body: "Tria a continuació la configuració de Codewhale per a la teva versió de la CLI. Els altres clients MCP compatibles poden fer servir la guia de configuració del repositori." },
  ],
  controlsTitle: "Mantén el control",
  controlsBody: "Després de concedir els permisos de macOS, el mode estàndard funciona sense demanar permís per a cada app. Les apps que bloquegis continuen fora de l’abast; Pause suspèn l’ús de l’ordinador i Stop computer use finalitza les sessions actuals. L’aprovació estricta és opcional. Demana una previsualització en directe quan vulguis veure què fa.",
@@ -36,6 +36,18 @@ export const computerUse: ComputerUseDict = {
  help: "Configuració i resolució de problemes",
  notes: "Notes de la versió",
  demo: "Mira la comprovació en segon pla",
-  source: "Codi font i altres plataformes",
+  source: "Veure a GitHub",
  platforms: "L’ajudant del Mac és una beta i el connector del catàleg només admet Mac. Les versions publicades també inclouen una previsualització experimental sense signar per a Windows x64; Linux requereix una configuració experimental des del codi font o amb Docker. L’entrada a Windows i Linux utilitza l’escriptori compartit.",
+  connectTitle: "Connecta Codewhale",
+  connectVersion: "Codewhale 0.10.2 inclou un connector Computer Use antic. Instal·lar l’entrada del catàleg no l’actualitza. Connecta directament l’auxiliar de Mac instal·lat mitjançant MCP.",
+  connectLimit: "La connexió MCP directa afegeix eines sense les habilitats del connector. No la facis servir alhora que el connector integrat antic. Si està activat, executa primer /plugin disable computer-use.",
+  connectRuntime: "L’aplicació inclou Node; no cal instal·lar-lo per separat. Si està instal·lada en una altra ubicació, assigna a APP el camí real del paquet de l’aplicació.",
+  connectReload: "En una sessió de terminal en execució, executa /mcp reload, canvia a Operate i demana:",
+  connectPrompt: "Comprova els permisos de Computer Use amb request_access. No enviïs cap entrada.",
+  connectExpected: "Comprova via: app, la versió de l’auxiliar i els permisos que faltin a la resposta. Si no es troba l’auxiliar, atura’t i segueix la indicació de configuració. Això només comprova la connexió i els permisos.",
+  connectGuide: "Guia de configuració MCP",
+  contributeTitle: "Ajuda a millorar Computer Use",
+  contributeBody: "Millora la documentació o prova un flux de treball en una aplicació i comparteix resultats reproduïbles.",
+  contributeGuide: "Guia de contribució",
+  contributeIssue: "Informar d’un problema",
 };
@@ -27,7 +27,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "App installieren", body: "Öffne das Disk-Image und ziehe Codewhale Computer Use in den Ordner „Programme“. Öffne die App aus „Programme“ und wähle dann Computer Use über das Wal-Symbol in deiner Menüleiste." },
    { title: "Berechtigungen prüfen", body: "Über die Einrichtungsschaltflächen öffnest du „Bedienungshilfen“ und „Bildschirmaufnahme“ in den Systemeinstellungen. Welche Berechtigungen du erteilst, entscheidest du." },
-    { title: "Deinen Agenten verbinden", body: "Installiere Computer Use in Codewhale mit /plugin marketplace install codewhale computer-use, prüfe das Plugin und aktiviere es. Der Helfer wird separat installiert. Andere kompatible MCP-Hosts verbinden sich über die Einrichtungsanleitung mit ihm." },
+    { title: "Deinen Agenten verbinden", body: "Wähle unten die Codewhale-Einrichtung für deine CLI-Version. Andere kompatible MCP-Clients nutzen die Einrichtungsanleitung im Repository." },
  ],
  controlsTitle: "Du behältst die Kontrolle",
  controlsBody: "Nach Erteilung der macOS-Berechtigungen arbeitet der Standardmodus ohne Rückfragen für jede App. Von dir gesperrte Apps bleiben gesperrt; Pause unterbricht die Computernutzung und Stop computer use beendet laufende Sitzungen. Strenge Genehmigungen sind optional. Bitte um eine Live-Vorschau, wenn du zusehen möchtest.",
@@ -36,6 +36,18 @@ export const computerUse: ComputerUseDict = {
  help: "Einrichtung und Fehlerbehebung",
  notes: "Versionshinweise",
  demo: "Hintergrundprüfung ansehen",
-  source: "Quellcode und weitere Plattformen",
+  source: "Auf GitHub ansehen",
  platforms: "Der Mac-Helfer ist eine Beta; das Marketplace-Plugin unterstützt nur Mac. Veröffentlichte Versionen enthalten auch eine unsignierte experimentelle Vorschau für Windows x64; Linux erfordert eine experimentelle Einrichtung aus dem Quellcode oder mit Docker. Eingaben unter Windows und Linux nutzen den gemeinsamen Desktop.",
+  connectTitle: "Codewhale verbinden",
+  connectVersion: "Codewhale 0.10.2 enthält ein älteres Computer-Use-Plugin. Die Installation des Katalogeintrags aktualisiert es nicht. Verbinde den installierten Mac-Helfer direkt über MCP.",
+  connectLimit: "Die direkte MCP-Verbindung fügt Werkzeuge ohne Plugin-Skills hinzu. Nutze sie nicht parallel zum älteren integrierten Plugin. Falls dieses aktiviert ist, führe zuerst /plugin disable computer-use aus.",
+  connectRuntime: "Die App enthält Node; eine separate Installation ist nicht nötig. Falls sie woanders installiert ist, setze APP auf den tatsächlichen Pfad des App-Bundles.",
+  connectReload: "Führe in einer laufenden Terminalsitzung /mcp reload aus, wechsle zu Operate und frage:",
+  connectPrompt: "Prüfe die Computer-Use-Berechtigungen mit request_access. Sende keine Eingaben.",
+  connectExpected: "Prüfe die Antwort auf via: app, die Helferversion und fehlende Berechtigungen. Falls der Helfer fehlt, halte an und folge dem Einrichtungshinweis. Das prüft nur Verbindung und Berechtigungen.",
+  connectGuide: "MCP-Einrichtungsanleitung",
+  contributeTitle: "Computer Use mitgestalten",
+  contributeBody: "Verbessere die Dokumentation oder teste einen Ablauf in einer App und teile reproduzierbare Ergebnisse.",
+  contributeGuide: "Leitfaden zum Mitwirken",
+  contributeIssue: "Problem melden",
 };
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Install the app", body: "Open the disk image and drag Codewhale Computer Use into Applications. Open it from Applications, then choose Computer Use from the whale icon in your menu bar." },
    { title: "Review permissions", body: "Use the setup buttons to open Accessibility and Screen Recording in System Settings. You choose which permissions to grant." },
-    { title: "Connect your agent", body: "In Codewhale, install Computer Use with /plugin marketplace install codewhale computer-use, then review and enable the plugin. Other compatible MCP hosts connect to the helper using the setup guide." },
+    { title: "Connect your agent", body: "Choose the Codewhale setup below for your CLI version. Other compatible MCP hosts use the repository setup guide." },
  ],
  controlsTitle: "Stay in control",
  controlsBody: "After you grant the macOS permissions, standard mode works without per-app prompts. Apps you deny stay off limits; Pause suspends computer use and Stop computer use ends current sessions. Strict approval is optional. Request a live preview when you want to watch.",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "Setup and troubleshooting",
  notes: "Release notes",
  demo: "See the background check",
-  source: "Other hosts and platforms",
+  source: "View on GitHub",
  platforms: "The Mac helper is a beta, and the marketplace plugin supports Mac. Published releases also include an unsigned experimental Windows x64 preview; Linux requires experimental source or Docker setup. Windows and Linux input uses the shared desktop.",
+  connectTitle: "Connect Codewhale",
+  connectVersion: "Codewhale 0.10.2 includes an older Computer Use plugin. Installing the catalog entry does not upgrade it. Use the installed Mac helper directly over MCP.",
+  connectLimit: "Direct MCP adds tools without plugin skills. Do not use it alongside the older built-in plugin. If that plugin is enabled, run /plugin disable computer-use first.",
+  connectRuntime: "The app includes Node; no separate Node install is needed. If installed elsewhere, set APP to the actual app bundle path.",
+  connectReload: "In a running terminal session, run /mcp reload, switch to Operate, and ask:",
+  connectPrompt: "Check Computer Use permissions with request_access. Do not send input.",
+  connectExpected: "Check for via: app, the helper version and any missing permissions. If the helper is missing, stop and follow the setup hint. This checks the connection and permissions only.",
+  connectGuide: "MCP setup guide",
+  contributeTitle: "Help improve Computer Use",
+  contributeBody: "Improve the docs or test an app workflow and share reproducible results.",
+  contributeGuide: "Contribution guide",
+  contributeIssue: "Report an issue",
 };
@@ -81,7 +81,7 @@ codewhale config doctor     # unknown keys, empty secrets, malformed URLs`,
          codeTerms: true,
        },
        {
-          p: "Keys, endpoints, provider choice, MCP servers, hooks, skills, and extra instruction files always come from your own config, so a cloned repository cannot point Codewhale at its own server or files. Start with `--no-project-config` to ignore a repository's file for one launch.",
+          p: "Provider keys, endpoints and provider choice come from your own config. MCP servers can also come from `.codewhale/mcp.json` after you trust the workspace in user-owned settings; project entries override same-named global entries. Review that executable authority before trusting a repository. See [MCP configuration](/docs/mcp#config).",
        },
        {
          p: "Project instructions — how an agent should work in this repository — belong in `AGENTS.md` instead. Run `/init` to create one.",
@@ -10,31 +10,55 @@ import type { DocsMcpDict } from "../types";
 export const docsMcp: DocsMcpDict = {
  metaTitle: "Connect tools with MCP · Codewhale Docs",
  metaDescription:
-    "Add Model Context Protocol servers so Codewhale can use more tools, sign in to remote servers, run Codewhale itself as an MCP server, and try code mode.",
+    "Connect local and remote MCP servers, understand authentication and plugin compatibility, and troubleshoot missing tools.",
  bodyClassName: "text-ink-soft leading-relaxed",
  title: "Connect tools with MCP",
  lede:
-    "MCP servers give Codewhale more tools — a database, an issue tracker, a browser. Add a local server that Codewhale starts for you, or a remote server by URL. Its tools then go through the same approvals as built-in ones.",
+    "Connect a local tool server or a remote service through Model Context Protocol. Codewhale discovers its tools and applies your tool permissions and approvals when you use them.",
  sections: [
    {
      id: "add",
-      title: "Add a server",
+      title: "Try the Cloudflare Docs server",
      blocks: [
        {
-          code: `codewhale mcp add git --command "uvx" --arg "mcp-server-git"
-codewhale mcp add docs --url "https://example.com/mcp"
-codewhale mcp list
-codewhale mcp validate`,
+          p: "The public [Cloudflare Documentation server](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/) provides documentation search and a Pages-to-Workers migration guide. [View its official source](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize). Add it without credentials:",
+        },
+        {
+          code: `codewhale mcp add cloudflare-docs --url "https://docs.mcp.cloudflare.com/mcp"
+codewhale mcp tools cloudflare-docs`,
          lang: "Terminal",
        },
        {
-          p: "`--command` starts a local server over stdio; repeat `--arg` for each argument. `--url` connects to a remote server over Streamable HTTP, with legacy SSE as a fallback. `mcp validate` checks the config and the servers you require.",
+          p: "The tool list should include `search_cloudflare_documentation` and `migrate_pages_to_workers_guide`. In an existing TUI session, run `/mcp reload` to load the new configuration into that session.",
+        },
+        {
+          note: "Checked on November 7, 2026 with published CLI v0.10.2: both commands exited successfully and listed those two tools without credentials. This checked setup and discovery, not tool execution. The [released guide](https://github.com/codewhale-hq/Codewhale/blob/v0.10.2/docs/MCP.md) describes that version; the [main source guide](https://github.com/codewhale-hq/Codewhale/blob/main/docs/MCP.md) may include unreleased changes.",
        },
        {
          p: "Inside a session, `/mcp` opens the MCP manager: each server's state, transport, timeouts, errors, and discovered tools. The same actions are available there, for example `/mcp add stdio <name> <command>` and `/mcp add http <name> <url>`.",
        },
        {
-          note: "An MCP server runs with your permissions. Add only servers you trust, as you would any program you install.",
+          note: "Local MCP servers run with the permissions of the Codewhale process; remote calls use the access you grant that service. Add only servers you trust.",
+        },
+      ],
+    },
+    {
+      id: "compatibility",
+      title: "What can connect",
+      blocks: [
+        {
+          rows: [
+            ["Local stdio", "Codewhale starts the executable you configure with `--command`; repeat `--arg` for its arguments. Install the server and its required runtime first."],
+            ["Remote HTTP / SSE", "Use `--url` for Streamable HTTP, with legacy SSE fallback. A legacy SSE endpoint can use `--transport sse`. A remote entry does not need `command`."],
+            ["Direct remote authentication", "Your own MCP configuration can use environment-backed headers, bearer tokens or OAuth. OAuth needs compatible server metadata and client registration."],
+            ["Plugin-contributed MCP", "A reviewed, enabled plugin can supply stdio or remote MCP servers. Plugin MCP supports environment-backed authentication, but plugin-contributed MCP OAuth is unsupported."],
+            ["Tools, resources and prompts", "Codewhale discovers what the server actually advertises. Resources, templates and prompts are available when the server implements them."],
+            ["Optional extensions and MCP Apps", "General MCP Apps UI support is not available. Basic MCP transport support does not guarantee support for every optional extension or server."],
+            ["Server requirements", "Each server keeps its own OS, executable, browser, dependency and account requirements. A local server runs on the computer hosting Codewhale; Computer Use has its own platform limits."],
+          ],
+        },
+        {
+          p: "A direct MCP entry does not require a plugin. [Plugins](/plugins) can package MCP tools with instructions and other components; each component still needs compatible dependencies, review and permissions.",
        },
      ],
    },
@@ -43,13 +67,16 @@ codewhale mcp validate`,
      title: "Sign in to a remote server",
      blocks: [
        {
-          p: "For a server that uses OAuth, add it by URL and log in. For a bearer token, keep the token in an environment variable instead of the config file:",
+          p: "For a directly configured OAuth server, add its real URL, then log in using the name you gave it:",
        },
        {
-          code: `codewhale mcp login docs
-codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var TRACKER_TOKEN`,
+          code: `codewhale mcp login <server>
+codewhale mcp logout <server>`,
          lang: "Terminal",
        },
+        {
+          p: "For a bearer token, use `--bearer-token-env-var TOKEN_NAME` when adding the server, and set that variable in the environment launching Codewhale. `env_headers` maps header names to environment variable names. Literal `headers` values do not expand `${TOKEN_NAME}`. Plugin MCP entries cannot use OAuth; configure that server directly instead.",
+        },
        {
          p: "An explicit Authorization header always wins: headers from config apply first, then the bearer-token variable, then a stored OAuth login. `codewhale mcp logout <name>` removes the stored login on this machine; the provider may keep its own grant until you revoke it there.",
        },
@@ -60,23 +87,26 @@ codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var
      title: "Edit the config file",
      blocks: [
        {
-          p: "Servers live in `~/.codewhale/mcp.json`. `codewhale mcp init` writes a starter file. The `mcpServers` key used by other clients works too, so you can paste an existing entry.",
+          p: "Global servers live in `~/.codewhale/mcp.json`; the legacy `~/.deepseek/mcp.json` is read when the Codewhale file is absent. `codewhale mcp init` writes a starter file. Use an absolute `mcp_config_path` or `CODEWHALE_MCP_CONFIG` to override it. The environment also accepts `DEEPSEEK_MCP_CONFIG`; the Codewhale name wins when both are set.",
        },
        {
          code: `{
  "servers": {
-    "example": {
-      "command": "node",
-      "args": ["./path/to/your-mcp-server.js"],
-      "env": {},
-      "disabled": false
+    "cloudflare-docs": {
+      "url": "https://docs.mcp.cloudflare.com/mcp"
    }
  }
 }`,
          lang: "mcp.json",
        },
        {
-          p: "After editing the file, run `/mcp reload` in the session; no restart is needed. A server starts only when a turn needs one of its tools, unless you mark it `\"required\": true` to connect at startup.",
+          p: "Use either `servers` or its `mcpServers` alias, never both in one file. `env_http_headers` is an alias for `env_headers`. Adapt the server's documented command, arguments and auth fields rather than assuming every client's configuration format is interchangeable.",
+        },
+        {
+          p: "A trusted workspace can add `.codewhale/mcp.json`. Its entries override same-named global servers; the repository cannot grant itself that trust or override your global config path. Explicit global or trusted-project entries win over a colliding plugin server identity.",
+        },
+        {
+          p: "After editing, run `/mcp reload` in the TUI; no restart is needed. Enabled, allowed servers connect at session start by default. Set `\"lazy\": true` on a user-configured server to connect on demand; `\"required\": true` still connects it at startup. Plugin MCP servers have no lazy manifest option. Headless runtimes need a restart after config changes.",
        },
      ],
    },
@@ -85,10 +115,26 @@ codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var
      title: "Find the tools",
      blocks: [
        {
-          p: "Each tool appears to the model as `mcp_<server>_<tool>`: a server named `git` with a `status` tool becomes `mcp_git_status`. `codewhale mcp tools <server>` lists what a server offers. A server that fails to connect or is disabled never shows up as an available tool.",
+          p: "Each tool appears to the model as `mcp_<server>_<tool>`. For this example, documentation search is `mcp_cloudflare-docs_search_cloudflare_documentation`. `codewhale mcp tools <server>` lists discovered tools in its own process; it does not attach those connections to a running session.",
        },
        {
-          p: "MCP tools follow your [approval setting](/docs/modes): listing and reading a server's resources and prompts can run without a prompt when policy allows, and tools with side effects ask first. Full Access does not override repository rules or managed policy.",
+          p: "MCP tools follow your [approval setting](/docs/modes), allow/deny rules and network policy. Whether a call asks first depends on that policy and posture. Full Access does not override repository rules or managed policy.",
+        },
+      ],
+    },
+    {
+      id: "troubleshooting",
+      title: "When tools do not appear",
+      blocks: [
+        {
+          rows: [
+            ["Check configuration", "Run `codewhale doctor` for static path and configuration diagnostics. Shell `codewhale mcp validate` connects enabled, allowed servers in a separate process; it is a live check."],
+            ["Refresh this session", "TUI `/mcp validate` shows its last snapshot without reconnecting. Use `/mcp reload` after config changes, or `/mcp retry <name>` for one server."],
+            ["Connected, but missing a tool", "Check `codewhale mcp tools <server>`, the server's advertised tools, `enabled_tools` / `disabled_tools`, and the session's allow/deny rules. A connected transport alone does not mean a tool is available or permitted."],
+            ["Authentication required", "For a direct OAuth server, run `/mcp login <name>`. For token auth, check that the variable is present in Codewhale's launch environment. A successful login in one process does not attach its transport to another."],
+            ["Local command fails", "Check the server's executable, arguments, working directory and runtime. On Windows, package runners may need their `.cmd` name. Follow the server vendor's OS and dependency instructions."],
+            ["Plugin server is absent", "Check the owning plugin's review, trust and enabled state. MCP settings cannot activate an untrusted plugin or bypass a rejected manifest."],
+          ],
        },
      ],
    },
@@ -97,7 +143,7 @@ codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var
      title: "Run Codewhale as an MCP server",
      blocks: [
        {
-          p: "Other MCP clients can use Codewhale as a tool server. By default, it exposes only read-only `file_read` and `search` tools.",
+          p: "A client supporting Codewhale's advertised MCP protocol revisions can launch it as a stdio tool server. By default, it exposes only read-only `file_read` and `search` tools.",
        },
        {
          code: `codewhale mcp add-self
@@ -105,7 +151,7 @@ codewhale mcp tools codewhale`,
          lang: "Terminal",
        },
        {
-          p: "`add-self` registers `codewhale serve --mcp` over stdio; `codewhale mcp-server` is the equivalent entry point. Write tools stay withheld unless the operator explicitly permits them in server configuration. [Runtime API](/docs/runtime-api) HTTP is a separate transport.",
+          p: "`add-self` registers `codewhale serve --mcp`; `codewhale mcp-server` is the equivalent entry point. This server reads its separate `[server]` settings from the legacy `~/.deepseek/mcp_server.toml`, not the client `mcp.json`. Write or shell tools require explicit exposure and `require_approval = false`; there is no interactive approval channel. [Runtime API](/docs/runtime-api) HTTP is separate from MCP.",
        },
      ],
    },
@@ -113,6 +159,9 @@ codewhale mcp tools codewhale`,
      id: "code-mode",
      title: "Compose tool calls with code mode (experimental)",
      blocks: [
+        {
+          note: "This section follows the main candidate's source and can include behavior newer than published v0.10.2.",
+        },
        {
          p: "Code mode lets the model write one short JavaScript program that calls several tools, loops, and filters results, instead of making each call as a separate step. Only the program's final value goes back to the model, which keeps long lookups compact. It is on by default — `execute_tools` is advertised from the first request — and MCP and plugin tools compose inside a program the same way built-in ones do. Turning it off does not remove code mode: `execute_tools` goes back to being deferred, and the model can still find it through `tool_search`. To turn it off for one session, or in config:",
        },
@@ -28,7 +28,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Instala la aplicación", body: "Abre la imagen de disco y arrastra Codewhale Computer Use a «Aplicaciones». Ábrela desde «Aplicaciones» y luego elige Computer Use en el icono de la ballena de la barra de menús." },
    { title: "Revisa los permisos", body: "Usa los botones de configuración para abrir «Accesibilidad» y «Grabación de pantalla» en Ajustes del Sistema. Tú decides qué permisos conceder." },
-    { title: "Conecta tu agente", body: "En Codewhale, instala Computer Use con /plugin marketplace install codewhale computer-use y después revisa y activa el plugin. El asistente se instala por separado. Otros hosts MCP compatibles se conectan al asistente siguiendo la guía de configuración." },
+    { title: "Conecta tu agente", body: "Elige a continuación la configuración de Codewhale para tu versión de la CLI. Otros clientes MCP compatibles pueden usar la guía de configuración del repositorio." },
  ],
  controlsTitle: "Mantén el control",
  controlsBody: "Tras conceder los permisos de macOS, el modo estándar funciona sin pedir permiso para cada app. Las apps que bloquees siguen fuera de su alcance; Pause suspende el uso del ordenador y Stop computer use termina las sesiones actuales. La aprobación estricta es opcional. Pide una vista previa en directo cuando quieras ver lo que hace.",
@@ -37,6 +37,18 @@ export const computerUse: ComputerUseDict = {
  help: "Configuración y solución de problemas",
  notes: "Notas de la versión",
  demo: "Ver la comprobación en segundo plano",
-  source: "Código fuente y otras plataformas",
+  source: "Ver en GitHub",
  platforms: "El asistente para Mac está en beta y el plugin del catálogo solo admite Mac. Las versiones publicadas también incluyen una vista previa experimental sin firmar para Windows x64; Linux requiere una configuración experimental desde el código fuente o con Docker. La entrada en Windows y Linux utiliza el escritorio compartido.",
+  connectTitle: "Conecta Codewhale",
+  connectVersion: "Codewhale 0.10.2 incluye un plugin Computer Use antiguo. Instalar la entrada del catálogo no lo actualiza. Conecta directamente el asistente de Mac instalado mediante MCP.",
+  connectLimit: "La conexión MCP directa añade herramientas sin las habilidades del plugin. No la uses junto con el plugin integrado antiguo. Si está activado, ejecuta primero /plugin disable computer-use.",
+  connectRuntime: "La aplicación incluye Node; no hace falta instalarlo por separado. Si está instalada en otra ubicación, asigna a APP la ruta real del paquete de la aplicación.",
+  connectReload: "En una sesión de terminal en ejecución, ejecuta /mcp reload, cambia a Operate y pide:",
+  connectPrompt: "Comprueba los permisos de Computer Use con request_access. No envíes ninguna entrada.",
+  connectExpected: "Comprueba que la respuesta indique via: app, la versión del asistente y los permisos que falten. Si no se encuentra el asistente, detente y sigue la indicación de configuración. Esto solo comprueba la conexión y los permisos.",
+  connectGuide: "Guía de configuración de MCP",
+  contributeTitle: "Ayuda a mejorar Computer Use",
+  contributeBody: "Mejora la documentación o prueba un flujo de trabajo en una aplicación y comparte resultados reproducibles.",
+  contributeGuide: "Guía de contribución",
+  contributeIssue: "Informar de un problema",
 };
@@ -27,7 +27,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Installer l’app", body: "Ouvrez l’image disque et faites glisser Codewhale Computer Use dans « Applications ». Lancez-la depuis « Applications », puis choisissez Computer Use dans l’icône de baleine de votre barre des menus." },
    { title: "Vérifier les autorisations", body: "Les boutons de configuration ouvrent « Accessibilité » et « Enregistrement de l’écran » dans Réglages Système. C’est vous qui décidez des autorisations à accorder." },
-    { title: "Connecter votre agent", body: "Dans Codewhale, installez Computer Use avec /plugin marketplace install codewhale computer-use, puis examinez et activez le plugin. L’assistant s’installe séparément. Les autres hôtes MCP compatibles s’y connectent en suivant le guide de configuration." },
+    { title: "Connecter votre agent", body: "Choisissez ci-dessous la configuration de Codewhale adaptée à votre version de la CLI. Les autres clients MCP compatibles utilisent le guide de configuration du dépôt." },
  ],
  controlsTitle: "Gardez la main",
  controlsBody: "Après l’octroi des autorisations macOS, le mode standard fonctionne sans demander une autorisation pour chaque app. Les apps que vous bloquez restent inaccessibles ; Pause suspend l’utilisation de l’ordinateur et Stop computer use termine les sessions en cours. L’approbation stricte est facultative. Demandez un aperçu en direct pour suivre les opérations.",
@@ -36,6 +36,18 @@ export const computerUse: ComputerUseDict = {
  help: "Configuration et dépannage",
  notes: "Notes de version",
  demo: "Voir la vérification en arrière-plan",
-  source: "Code source et autres plateformes",
+  source: "Voir sur GitHub",
  platforms: "L’assistant Mac est en bêta et le plugin du catalogue ne prend en charge que Mac. Les versions publiées comprennent aussi un aperçu expérimental non signé pour Windows x64 ; Linux nécessite une configuration expérimentale depuis les sources ou avec Docker. Les entrées sous Windows et Linux utilisent le bureau partagé.",
+  connectTitle: "Connecter Codewhale",
+  connectVersion: "Codewhale 0.10.2 intègre une ancienne version du plugin Computer Use. Installer son entrée dans le catalogue ne la met pas à jour. Connectez directement l’application auxiliaire Mac installée via MCP.",
+  connectLimit: "La connexion MCP directe ajoute des outils sans les compétences du plugin. Ne l’utilisez pas avec l’ancien plugin intégré. S’il est activé, exécutez d’abord /plugin disable computer-use.",
+  connectRuntime: "L’application inclut Node ; aucune installation séparée n’est nécessaire. Si elle est installée ailleurs, attribuez à APP le chemin réel du paquet de l’application.",
+  connectReload: "Dans une session de terminal en cours, exécutez /mcp reload, passez à Operate, puis demandez :",
+  connectPrompt: "Vérifie les autorisations de Computer Use avec request_access. N’envoie aucune saisie.",
+  connectExpected: "Vérifiez via: app, la version de l’application auxiliaire et les autorisations manquantes dans la réponse. Si l’application auxiliaire est absente, arrêtez-vous et suivez l’indication de configuration. Ce test vérifie uniquement la connexion et les autorisations.",
+  connectGuide: "Guide de configuration MCP",
+  contributeTitle: "Contribuez à améliorer Computer Use",
+  contributeBody: "Améliorez la documentation ou testez un scénario dans une application et partagez des résultats reproductibles.",
+  contributeGuide: "Guide de contribution",
+  contributeIssue: "Signaler un problème",
 };
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "ऐप इंस्टॉल करें", body: "डिस्क इमेज खोलें और Codewhale Computer Use को “ऐप्लिकेशन” में खींचकर छोड़ें। इसे “ऐप्लिकेशन” से खोलें, फिर मेनू बार में व्हेल के आइकन से Computer Use चुनें।" },
    { title: "अनुमतियों की समीक्षा करें", body: "सेटअप बटनों से सिस्टम सेटिंग्ज़ में “ऐक्सेसिबिलिटी” और “स्क्रीन रिकॉर्डिंग” खोलें। कौन-सी अनुमतियाँ देनी हैं, यह आप तय करते हैं।" },
-    { title: "अपना एजेंट कनेक्ट करें", body: "Codewhale में /plugin marketplace install codewhale computer-use से Computer Use इंस्टॉल करें, फिर प्लगइन की समीक्षा करके उसे सक्षम करें। हेल्पर अलग से इंस्टॉल होता है। अन्य संगत MCP होस्ट सेटअप गाइड के अनुसार उससे जुड़ते हैं।" },
+    { title: "अपना एजेंट कनेक्ट करें", body: "अपने CLI संस्करण के लिए नीचे दिया गया Codewhale सेटअप चुनें। अन्य संगत MCP होस्ट के लिए रिपॉज़िटरी की सेटअप मार्गदर्शिका देखें।" },
  ],
  controlsTitle: "नियंत्रण आपके हाथ में",
  controlsBody: "macOS की अनुमतियाँ देने के बाद मानक मोड हर ऐप के लिए अनुमति माँगे बिना काम करता है। आपके प्रतिबंधित ऐप पहुँच से बाहर रहते हैं; Pause कंप्यूटर का इस्तेमाल रोकता है और Stop computer use मौजूदा सेशन समाप्त करता है। सख्त स्वीकृति मोड वैकल्पिक है। काम देखना चाहें, तो लाइव प्रीव्यू माँगें।",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "सेटअप और समस्या-समाधान",
  notes: "रिलीज़ नोट्स",
  demo: "बैकग्राउंड जाँच देखें",
-  source: "सोर्स और अन्य प्लेटफ़ॉर्म",
+  source: "GitHub पर देखें",
  platforms: "Mac हेल्पर बीटा में है और मार्केटप्लेस प्लगइन केवल Mac का समर्थन करता है। प्रकाशित संस्करणों में Windows x64 का बिना हस्ताक्षर वाला प्रयोगात्मक प्रीव्यू भी है; Linux के लिए सोर्स या Docker से प्रयोगात्मक सेटअप चाहिए। Windows और Linux पर इनपुट साझा डेस्कटॉप का उपयोग करता है।",
+  connectTitle: "Codewhale कनेक्ट करें",
+  connectVersion: "Codewhale 0.10.2 में Computer Use का पुराना प्लगइन शामिल है। कैटलॉग की प्रविष्टि इंस्टॉल करने से वह अपडेट नहीं होता। इंस्टॉल किए गए Mac सहायक से सीधे MCP के ज़रिए कनेक्ट करें।",
+  connectLimit: "सीधा MCP कनेक्शन टूल जोड़ता है, प्लगइन स्किल नहीं। इसे पुराने अंतर्निर्मित प्लगइन के साथ न चलाएँ। यदि वह सक्षम है, तो पहले /plugin disable computer-use चलाएँ।",
+  connectRuntime: "ऐप में Node शामिल है; उसे अलग से इंस्टॉल करने की ज़रूरत नहीं है। यदि ऐप कहीं और इंस्टॉल है, तो APP में ऐप बंडल का वास्तविक पथ दें।",
+  connectReload: "चल रहे टर्मिनल सत्र में /mcp reload चलाएँ, Operate पर जाएँ और यह कहें:",
+  connectPrompt: "request_access से Computer Use की अनुमतियाँ जाँचें। कोई इनपुट न भेजें।",
+  connectExpected: "जवाब में via: app, सहायक का संस्करण और अनुपलब्ध अनुमतियाँ देखें। यदि सहायक नहीं मिलता, तो रुकें और सेटअप संकेत का पालन करें। इससे केवल कनेक्शन और अनुमतियाँ जाँची जाती हैं।",
+  connectGuide: "MCP सेटअप मार्गदर्शिका",
+  contributeTitle: "Computer Use को बेहतर बनाने में मदद करें",
+  contributeBody: "दस्तावेज़ सुधारें या किसी ऐप की कार्यप्रणाली जाँचें और दोहराए जा सकने वाले परिणाम साझा करें।",
+  contributeGuide: "योगदान मार्गदर्शिका",
+  contributeIssue: "समस्या रिपोर्ट करें",
 };
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Instal aplikasi", body: "Buka disk image, lalu seret Codewhale Computer Use ke folder “Aplikasi”. Buka aplikasinya dari “Aplikasi”, kemudian pilih Computer Use dari ikon paus di bar menu Anda." },
    { title: "Tinjau izin", body: "Gunakan tombol penyiapan untuk membuka “Aksesibilitas” dan “Perekaman Layar” di Pengaturan Sistem. Anda yang menentukan izin mana yang diberikan." },
-    { title: "Hubungkan agen Anda", body: "Di Codewhale, instal Computer Use dengan /plugin marketplace install codewhale computer-use, lalu tinjau dan aktifkan plugin. Aplikasi pembantu diinstal secara terpisah. Host MCP lain yang kompatibel menghubungkannya melalui panduan penyiapan." },
+    { title: "Hubungkan agen Anda", body: "Pilih pengaturan Codewhale di bawah yang sesuai dengan versi CLI Anda. Host MCP lain yang kompatibel dapat mengikuti panduan pengaturan di repositori." },
  ],
  controlsTitle: "Kendali tetap di tangan Anda",
  controlsBody: "Setelah izin macOS diberikan, mode standar bekerja tanpa meminta izin untuk setiap aplikasi. Aplikasi yang Anda blokir tetap tidak dapat diakses; Pause menjeda penggunaan komputer dan Stop computer use mengakhiri sesi saat ini. Persetujuan ketat bersifat opsional. Minta pratinjau langsung saat Anda ingin melihat prosesnya.",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "Penyiapan dan pemecahan masalah",
  notes: "Catatan rilis",
  demo: "Lihat pemeriksaan latar belakang",
-  source: "Kode sumber dan platform lain",
+  source: "Lihat di GitHub",
  platforms: "Aplikasi pembantu Mac masih beta dan plugin katalog hanya mendukung Mac. Rilis yang diterbitkan juga menyediakan pratinjau eksperimental tanpa tanda tangan untuk Windows x64; Linux memerlukan penyiapan eksperimental dari kode sumber atau Docker. Input pada Windows dan Linux menggunakan desktop bersama.",
+  connectTitle: "Hubungkan Codewhale",
+  connectVersion: "Codewhale 0.10.2 menyertakan plugin Computer Use versi lama. Memasang entri katalog tidak memperbaruinya. Hubungkan langsung aplikasi pembantu Mac yang terpasang melalui MCP.",
+  connectLimit: "Koneksi MCP langsung menambahkan alat tanpa keterampilan plugin. Jangan gunakan bersamaan dengan plugin bawaan lama. Jika plugin itu aktif, jalankan /plugin disable computer-use terlebih dahulu.",
+  connectRuntime: "Aplikasi sudah menyertakan Node; tidak perlu pemasangan terpisah. Jika terpasang di lokasi lain, isi APP dengan jalur bundel aplikasi yang sebenarnya.",
+  connectReload: "Dalam sesi terminal yang sedang berjalan, jalankan /mcp reload, beralih ke Operate, lalu minta:",
+  connectPrompt: "Periksa izin Computer Use dengan request_access. Jangan kirim input.",
+  connectExpected: "Periksa via: app, versi aplikasi pembantu, dan izin yang belum diberikan dalam respons. Jika aplikasi pembantu tidak ditemukan, berhenti dan ikuti petunjuk pengaturan. Ini hanya memeriksa koneksi dan izin.",
+  connectGuide: "Panduan pengaturan MCP",
+  contributeTitle: "Bantu tingkatkan Computer Use",
+  contributeBody: "Perbaiki dokumentasi atau uji alur kerja aplikasi dan bagikan hasil yang dapat direproduksi.",
+  contributeGuide: "Panduan kontribusi",
+  contributeIssue: "Laporkan masalah",
 };
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Installa l’app", body: "Apri l’immagine disco e trascina Codewhale Computer Use in “Applicazioni”. Aprila da “Applicazioni”, poi scegli Computer Use dall’icona della balena nella barra dei menu." },
    { title: "Controlla i permessi", body: "Usa i pulsanti di configurazione per aprire “Accessibilità” e “Registrazione schermo” nelle Impostazioni di Sistema. Decidi tu quali permessi concedere." },
-    { title: "Collega il tuo agente", body: "In Codewhale, installa Computer Use con /plugin marketplace install codewhale computer-use, poi esamina e attiva il plugin. L’helper si installa separatamente. Gli altri host MCP compatibili si collegano all’helper seguendo la guida di configurazione." },
+    { title: "Collega il tuo agente", body: "Scegli qui sotto la configurazione di Codewhale per la tua versione della CLI. Gli altri client MCP compatibili possono usare la guida di configurazione del repository." },
  ],
  controlsTitle: "Mantieni il controllo",
  controlsBody: "Dopo aver concesso i permessi macOS, la modalità standard funziona senza chiedere l’autorizzazione per ogni app. Le app che blocchi restano inaccessibili; Pause sospende l’uso del computer e Stop computer use termina le sessioni attuali. L’approvazione rigorosa è facoltativa. Chiedi un’anteprima dal vivo per seguire le operazioni.",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "Configurazione e risoluzione dei problemi",
  notes: "Note di rilascio",
  demo: "Guarda il test in background",
-  source: "Codice sorgente e altre piattaforme",
+  source: "Visualizza su GitHub",
  platforms: "L’helper per Mac è in beta e il plugin del catalogo supporta solo Mac. Le versioni pubblicate includono anche un’anteprima sperimentale non firmata per Windows x64; Linux richiede una configurazione sperimentale dai sorgenti o con Docker. L’input su Windows e Linux usa il desktop condiviso.",
+  connectTitle: "Collega Codewhale",
+  connectVersion: "Codewhale 0.10.2 include una vecchia versione del plugin Computer Use. Installare la voce del catalogo non lo aggiorna. Collega direttamente l’app di supporto Mac installata tramite MCP.",
+  connectLimit: "La connessione MCP diretta aggiunge strumenti senza le skill del plugin. Non usarla insieme al vecchio plugin integrato. Se è attivo, esegui prima /plugin disable computer-use.",
+  connectRuntime: "L’app include Node; non serve installarlo separatamente. Se è installata altrove, imposta APP sul percorso effettivo del bundle dell’app.",
+  connectReload: "In una sessione del terminale in esecuzione, esegui /mcp reload, passa a Operate e chiedi:",
+  connectPrompt: "Controlla le autorizzazioni di Computer Use con request_access. Non inviare alcun input.",
+  connectExpected: "Controlla via: app, la versione dell’app di supporto e le autorizzazioni mancanti nella risposta. Se l’app di supporto non è presente, fermati e segui le indicazioni di configurazione. Questo verifica solo la connessione e le autorizzazioni.",
+  connectGuide: "Guida alla configurazione MCP",
+  contributeTitle: "Aiuta a migliorare Computer Use",
+  contributeBody: "Migliora la documentazione o prova un flusso di lavoro in un’app e condividi risultati riproducibili.",
+  contributeGuide: "Guida ai contributi",
+  contributeIssue: "Segnala un problema",
 };
@@ -27,7 +27,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "アプリをインストールする", body: "ディスクイメージを開き、Codewhale Computer Use を「アプリケーション」フォルダにドラッグします。「アプリケーション」から起動し、メニューバーのクジラのアイコンから Computer Use を選択してください。" },
    { title: "権限を確認する", body: "セットアップのボタンから、システム設定の「アクセシビリティ」と「画面収録」を開きます。どの権限を許可するかはあなたが決めます。" },
-    { title: "エージェントを接続する", body: "Codewhale で /plugin marketplace install codewhale computer-use を実行し、プラグインを確認して有効にします。ヘルパーは別途インストールします。ほかの対応 MCP ホストは、セットアップガイドに従ってヘルパーに接続します。" },
+    { title: "エージェントを接続する", body: "CLI のバージョンに合う Codewhale の設定を下から選んでください。ほかの対応 MCP ホストでは、リポジトリの設定ガイドを参照してください。" },
  ],
  controlsTitle: "いつでも操作を管理",
  controlsBody: "macOS の権限を許可すると、標準モードではアプリごとの確認なしで動作します。拒否したアプリにはアクセスできません。Pause は操作を一時停止し、Stop computer use は現在のセッションを終了します。厳格な承認モードも選べます。作業を見たいときはライブプレビューを依頼してください。",
@@ -36,6 +36,18 @@ export const computerUse: ComputerUseDict = {
  help: "セットアップとトラブルシューティング",
  notes: "リリースノート",
  demo: "バックグラウンドチェックを見る",
-  source: "ソースコードとその他のプラットフォーム",
+  source: "GitHub で見る",
  platforms: "Mac ヘルパーはベータ版で、マーケットプレイスのプラグインは Mac のみに対応しています。公開リリースには署名のない実験的な Windows x64 プレビューもあります。Linux はソースまたは Docker による実験的なセットアップが必要です。Windows と Linux の入力は共有デスクトップを使用します。",
+  connectTitle: "Codewhale に接続",
+  connectVersion: "Codewhale 0.10.2 には旧版の Computer Use プラグインが内蔵されています。カタログからインストールしても更新されません。インストール済みの Mac ヘルパーに MCP で直接接続してください。",
+  connectLimit: "MCP での直接接続はツールを追加しますが、プラグインのスキルは含みません。旧版の内蔵プラグインと併用しないでください。有効なら、先に /plugin disable computer-use を実行してください。",
+  connectRuntime: "アプリには Node が含まれるため、別途インストールする必要はありません。別の場所にインストールした場合は、APP を実際のアプリバンドルのパスに設定してください。",
+  connectReload: "実行中のターミナルセッションで /mcp reload を実行し、Operate に切り替えて次のように依頼します：",
+  connectPrompt: "request_access で Computer Use の権限を確認してください。入力操作は行わないでください。",
+  connectExpected: "応答の via: app、ヘルパーのバージョン、不足している権限を確認してください。ヘルパーが見つからない場合は停止し、設定の案内に従ってください。これは接続と権限のみの確認です。",
+  connectGuide: "MCP 設定ガイド",
+  contributeTitle: "Computer Use の改善に参加",
+  contributeBody: "ドキュメントの改善や、アプリの操作手順のテストと再現可能な結果の共有で協力できます。",
+  contributeGuide: "貢献ガイド",
+  contributeIssue: "問題を報告",
 };
@@ -27,7 +27,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "앱 설치", body: "디스크 이미지를 열고 Codewhale Computer Use를 “응용 프로그램”으로 드래그하세요. “응용 프로그램”에서 앱을 연 다음 메뉴 막대의 고래 아이콘에서 Computer Use를 선택합니다." },
    { title: "권한 검토", body: "설정 버튼으로 시스템 설정의 “손쉬운 사용”과 “화면 기록”을 여세요. 어떤 권한을 허용할지는 당신이 결정합니다." },
-    { title: "에이전트 연결", body: "Codewhale에서 /plugin marketplace install codewhale computer-use로 Computer Use를 설치한 뒤 플러그인을 검토하고 활성화하세요. 도우미는 별도로 설치합니다. 다른 호환 MCP 호스트는 설정 가이드에 따라 도우미에 연결합니다." },
+    { title: "에이전트 연결", body: "CLI 버전에 맞는 Codewhale 설정을 아래에서 선택하세요. 다른 호환 MCP 호스트는 저장소의 설정 안내를 따르세요." },
  ],
  controlsTitle: "언제든 직접 제어",
  controlsBody: "macOS 권한을 허용하면 표준 모드는 앱마다 허용 여부를 묻지 않고 작동합니다. 차단한 앱에는 접근할 수 없습니다. Pause는 컴퓨터 사용을 일시 중지하고 Stop computer use는 현재 세션을 종료합니다. 엄격한 승인 모드도 선택할 수 있습니다. 작업을 지켜보고 싶을 때 실시간 미리보기를 요청하세요.",
@@ -36,6 +36,18 @@ export const computerUse: ComputerUseDict = {
  help: "설정 및 문제 해결",
  notes: "릴리스 노트",
  demo: "백그라운드 검사 보기",
-  source: "소스 및 다른 플랫폼",
+  source: "GitHub에서 보기",
  platforms: "Mac 도우미는 베타이며 마켓플레이스 플러그인은 Mac만 지원합니다. 공개 릴리스에는 서명되지 않은 실험용 Windows x64 프리뷰도 있습니다. Linux는 소스 또는 Docker를 통한 실험적 설정이 필요합니다. Windows와 Linux의 입력은 공유 데스크톱을 사용합니다.",
+  connectTitle: "Codewhale 연결",
+  connectVersion: "Codewhale 0.10.2에는 이전 Computer Use 플러그인이 내장되어 있습니다. 카탈로그 항목을 설치해도 이 플러그인은 업데이트되지 않습니다. 설치된 Mac 도우미에 MCP로 직접 연결하세요.",
+  connectLimit: "MCP 직접 연결은 도구만 추가하며 플러그인 스킬은 포함하지 않습니다. 이전 내장 플러그인과 함께 사용하지 마세요. 해당 플러그인이 켜져 있다면 먼저 /plugin disable computer-use를 실행하세요.",
+  connectRuntime: "앱에 Node가 포함되어 있어 별도 설치가 필요 없습니다. 다른 위치에 설치했다면 APP를 실제 앱 번들 경로로 설정하세요.",
+  connectReload: "실행 중인 터미널 세션에서 /mcp reload를 실행하고 Operate로 전환한 뒤 다음과 같이 요청하세요:",
+  connectPrompt: "request_access로 Computer Use 권한을 확인하세요. 입력은 보내지 마세요.",
+  connectExpected: "응답에서 via: app, 도우미 버전, 누락된 권한을 확인하세요. 도우미가 없다면 중단하고 설정 안내를 따르세요. 이 단계는 연결과 권한만 확인합니다.",
+  connectGuide: "MCP 설정 안내",
+  contributeTitle: "Computer Use 개선에 참여하기",
+  contributeBody: "문서를 개선하거나 앱 작업 흐름을 테스트하고 재현 가능한 결과를 공유해 주세요.",
+  contributeGuide: "기여 안내",
+  contributeIssue: "문제 신고",
 };
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Zainstaluj aplikację", body: "Otwórz obraz dysku i przeciągnij Codewhale Computer Use do folderu „Programy”. Uruchom aplikację z folderu „Programy”, a następnie wybierz Computer Use z menu pod ikoną wieloryba w pasku menu." },
    { title: "Sprawdź uprawnienia", body: "Przyciski konfiguracji otwierają sekcje „Dostępność” i „Nagrywanie ekranu” w Ustawieniach systemowych. To Ty decydujesz, które uprawnienia przyznać." },
-    { title: "Połącz swojego agenta", body: "W Codewhale zainstaluj Computer Use poleceniem /plugin marketplace install codewhale computer-use, a następnie przejrzyj i włącz wtyczkę. Pomocnik jest instalowany osobno. Inne zgodne hosty MCP łączą się z nim zgodnie z instrukcją konfiguracji." },
+    { title: "Połącz swojego agenta", body: "Wybierz poniżej konfigurację Codewhale dla swojej wersji CLI. Dla innych zgodnych klientów MCP skorzystaj z instrukcji konfiguracji w repozytorium." },
  ],
  controlsTitle: "Zachowaj kontrolę",
  controlsBody: "Po przyznaniu uprawnień macOS tryb standardowy działa bez pytania o zgodę dla każdej aplikacji. Zablokowane przez Ciebie aplikacje pozostają niedostępne; Pause wstrzymuje korzystanie z komputera, a Stop computer use kończy bieżące sesje. Ścisłe zatwierdzanie jest opcjonalne. Poproś o podgląd na żywo, gdy chcesz śledzić pracę.",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "Konfiguracja i rozwiązywanie problemów",
  notes: "Informacje o wydaniu",
  demo: "Zobacz test w tle",
-  source: "Kod źródłowy i inne platformy",
+  source: "Zobacz na GitHubie",
  platforms: "Pomocnik na Maca jest w wersji beta, a wtyczka z katalogu obsługuje tylko Maca. Opublikowane wydania zawierają też niepodpisaną eksperymentalną wersję podglądową dla Windows x64; Linux wymaga eksperymentalnej konfiguracji ze źródeł lub przez Docker. Wprowadzanie danych w Windows i Linuksie korzysta ze wspólnego pulpitu.",
+  connectTitle: "Połącz Codewhale",
+  connectVersion: "Codewhale 0.10.2 zawiera starszą wtyczkę Computer Use. Instalacja pozycji z katalogu jej nie aktualizuje. Połącz zainstalowaną aplikację pomocniczą Mac bezpośrednio przez MCP.",
+  connectLimit: "Bezpośrednie połączenie MCP dodaje narzędzia bez umiejętności wtyczki. Nie używaj go równocześnie ze starszą wbudowaną wtyczką. Jeśli jest włączona, najpierw uruchom /plugin disable computer-use.",
+  connectRuntime: "Aplikacja zawiera Node; osobna instalacja nie jest potrzebna. Jeśli jest zainstalowana gdzie indziej, ustaw APP na rzeczywistą ścieżkę pakietu aplikacji.",
+  connectReload: "W działającej sesji terminala uruchom /mcp reload, przełącz na Operate i poproś:",
+  connectPrompt: "Sprawdź uprawnienia Computer Use za pomocą request_access. Nie wysyłaj żadnych danych wejściowych.",
+  connectExpected: "Sprawdź w odpowiedzi via: app, wersję aplikacji pomocniczej i brakujące uprawnienia. Jeśli aplikacji pomocniczej nie ma, zatrzymaj się i postępuj zgodnie ze wskazówką konfiguracji. To sprawdza tylko połączenie i uprawnienia.",
+  connectGuide: "Instrukcja konfiguracji MCP",
+  contributeTitle: "Pomóż ulepszyć Computer Use",
+  contributeBody: "Popraw dokumentację lub przetestuj przebieg pracy w aplikacji i podziel się powtarzalnymi wynikami.",
+  contributeGuide: "Przewodnik dla współtwórców",
+  contributeIssue: "Zgłoś problem",
 };
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Instale o app", body: "Abra a imagem de disco e arraste o Codewhale Computer Use para a pasta Aplicativos. Abra-o a partir de Aplicativos e escolha Computer Use no ícone da baleia na barra de menus." },
    { title: "Revise as permissões", body: "Use os botões de configuração para abrir Acessibilidade e Gravação de Tela nos Ajustes do Sistema. Você decide quais permissões conceder." },
-    { title: "Conecte seu agente", body: "No Codewhale, instale o Computer Use com /plugin marketplace install codewhale computer-use, depois revise e ative o plugin. O assistente é instalado separadamente. Outros hosts MCP compatíveis se conectam a ele seguindo o guia de configuração." },
+    { title: "Conecte seu agente", body: "Escolha abaixo a configuração do Codewhale para sua versão da CLI. Outros clientes MCP compatíveis usam o guia de configuração do repositório." },
  ],
  controlsTitle: "Mantenha o controle",
  controlsBody: "Após conceder as permissões do macOS, o modo padrão funciona sem pedir autorização para cada app. Os apps que você bloquear continuam inacessíveis; Pause suspende o uso do computador e Stop computer use encerra as sessões atuais. A aprovação estrita é opcional. Peça uma prévia ao vivo quando quiser acompanhar o trabalho.",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "Configuração e solução de problemas",
  notes: "Notas de lançamento",
  demo: "Veja a verificação em segundo plano",
-  source: "Código-fonte e outras plataformas",
+  source: "Ver no GitHub",
  platforms: "O assistente para Mac está em beta e o plugin do catálogo oferece suporte apenas a Mac. As versões publicadas também incluem uma prévia experimental sem assinatura para Windows x64; o Linux exige uma configuração experimental pelo código-fonte ou com Docker. A entrada no Windows e no Linux usa a área de trabalho compartilhada.",
+  connectTitle: "Conecte o Codewhale",
+  connectVersion: "O Codewhale 0.10.2 inclui um plugin Computer Use antigo. Instalar a entrada do catálogo não o atualiza. Conecte o assistente de Mac instalado diretamente por MCP.",
+  connectLimit: "A conexão MCP direta adiciona ferramentas sem as habilidades do plugin. Não a use junto com o plugin integrado antigo. Se ele estiver ativado, execute /plugin disable computer-use primeiro.",
+  connectRuntime: "O aplicativo inclui Node; não é preciso instalá-lo separadamente. Se estiver instalado em outro local, defina APP com o caminho real do pacote do aplicativo.",
+  connectReload: "Em uma sessão de terminal em execução, execute /mcp reload, mude para Operate e peça:",
+  connectPrompt: "Verifique as permissões do Computer Use com request_access. Não envie nenhuma entrada.",
+  connectExpected: "Confira via: app, a versão do assistente e as permissões ausentes na resposta. Se o assistente não for encontrado, pare e siga a orientação de configuração. Isso verifica apenas a conexão e as permissões.",
+  connectGuide: "Guia de configuração do MCP",
+  contributeTitle: "Ajude a melhorar o Computer Use",
+  contributeBody: "Melhore a documentação ou teste um fluxo de trabalho em um aplicativo e compartilhe resultados reproduzíveis.",
+  contributeGuide: "Guia de contribuição",
+  contributeIssue: "Relatar um problema",
 };
@@ -27,7 +27,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Установите приложение", body: "Откройте образ диска и перетащите Codewhale Computer Use в папку «Программы». Запустите его из папки «Программы», затем нажмите значок кита в строке меню и выберите Computer Use." },
    { title: "Проверьте разрешения", body: "Кнопки настройки открывают разделы «Универсальный доступ» и «Запись экрана» в Системных настройках. Какие разрешения выдать — решаете вы." },
-    { title: "Подключите агента", body: "В Codewhale установите Computer Use командой /plugin marketplace install codewhale computer-use, затем проверьте и включите плагин. Помощник устанавливается отдельно. Другие совместимые MCP-хосты подключаются к нему по инструкции настройки." },
+    { title: "Подключите агента", body: "Выберите ниже настройку Codewhale для вашей версии CLI. Для других совместимых MCP-клиентов используйте руководство по настройке в репозитории." },
  ],
  controlsTitle: "Контроль остаётся у вас",
  controlsBody: "После выдачи разрешений macOS стандартный режим работает без запроса для каждого приложения. Заблокированные вами приложения недоступны агенту; Pause приостанавливает работу с компьютером, а Stop computer use завершает текущие сеансы. Строгое подтверждение действий можно включить отдельно. Для наблюдения за работой запросите предпросмотр в реальном времени.",
@@ -36,6 +36,18 @@ export const computerUse: ComputerUseDict = {
  help: "Настройка и устранение неполадок",
  notes: "Примечания к выпуску",
  demo: "Посмотреть фоновую проверку",
-  source: "Исходный код и другие платформы",
+  source: "Открыть на GitHub",
  platforms: "Помощник для Mac находится в бета-версии, а плагин каталога поддерживает только Mac. Опубликованные выпуски также содержат неподписанную экспериментальную предварительную версию для Windows x64; Linux требует экспериментальной настройки из исходников или через Docker. Ввод в Windows и Linux использует общий рабочий стол.",
+  connectTitle: "Подключите Codewhale",
+  connectVersion: "В Codewhale 0.10.2 встроена старая версия плагина Computer Use. Установка записи из каталога её не обновляет. Подключите установленное приложение-помощник Mac напрямую через MCP.",
+  connectLimit: "Прямое подключение MCP добавляет инструменты без навыков плагина. Не используйте его одновременно со старым встроенным плагином. Если тот включён, сначала выполните /plugin disable computer-use.",
+  connectRuntime: "Node входит в приложение; отдельная установка не нужна. Если приложение находится в другом месте, задайте APP фактический путь к пакету приложения.",
+  connectReload: "В работающем терминальном сеансе выполните /mcp reload, переключитесь в Operate и попросите:",
+  connectPrompt: "Проверь разрешения Computer Use с помощью request_access. Не отправляй ввод.",
+  connectExpected: "Проверьте в ответе via: app, версию помощника и недостающие разрешения. Если помощник отсутствует, остановитесь и следуйте подсказке по настройке. Это проверка только подключения и разрешений.",
+  connectGuide: "Руководство по настройке MCP",
+  contributeTitle: "Помогите улучшить Computer Use",
+  contributeBody: "Улучшайте документацию или проверяйте сценарии работы в приложениях и делитесь воспроизводимыми результатами.",
+  contributeGuide: "Руководство для участников",
+  contributeIssue: "Сообщить о проблеме",
 };
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Uygulamayı kur", body: "Disk görüntüsünü aç ve Codewhale Computer Use'u Uygulamalar klasörüne sürükle. Uygulamalar'dan aç, ardından menü çubuğundaki balina simgesinden Computer Use'u seç." },
    { title: "İzinleri gözden geçir", body: "Kurulum düğmeleriyle Sistem Ayarları'nda Erişilebilirlik ve Ekran Kaydı bölümlerini aç. Hangi izinleri vereceğine sen karar verirsin." },
-    { title: "Ajanınızı bağlayın", body: "Codewhale’de /plugin marketplace install codewhale computer-use ile Computer Use’u yükleyin, ardından eklentiyi inceleyip etkinleştirin. Yardımcı ayrı olarak yüklenir. Diğer uyumlu MCP uygulamaları, kurulum kılavuzunu izleyerek yardımcıya bağlanır." },
+    { title: "Ajanınızı bağlayın", body: "CLI sürümünüz için aşağıdaki Codewhale kurulumunu seçin. Diğer uyumlu MCP istemcileri için depodaki kurulum rehberini kullanın." },
  ],
  controlsTitle: "Kontrol sende kalsın",
  controlsBody: "macOS izinleri verildikten sonra standart mod, her uygulama için izin istemeden çalışır. Engellediğiniz uygulamalar erişime kapalı kalır; Pause bilgisayar kullanımını duraklatır, Stop computer use mevcut oturumları sonlandırır. Sıkı onay modu isteğe bağlıdır. Çalışmayı izlemek istediğinizde canlı önizleme isteyin.",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "Kurulum ve sorun giderme",
  notes: "Sürüm notları",
  demo: "Arka plan kontrolünü izle",
-  source: "Kaynak kodu ve diğer platformlar",
+  source: "GitHub’da görüntüle",
  platforms: "Mac yardımcısı beta sürümündedir ve pazar yeri eklentisi yalnızca Mac’i destekler. Yayımlanan sürümlerde imzasız, deneysel bir Windows x64 önizlemesi de bulunur; Linux için kaynak koddan veya Docker ile deneysel kurulum gerekir. Windows ve Linux girdileri ortak masaüstünü kullanır.",
+  connectTitle: "Codewhale’i bağlayın",
+  connectVersion: "Codewhale 0.10.2 eski bir Computer Use eklentisi içerir. Katalog girdisini yüklemek bunu güncellemez. Yüklü Mac yardımcısına MCP üzerinden doğrudan bağlanın.",
+  connectLimit: "Doğrudan MCP bağlantısı, eklenti becerileri olmadan araçlar ekler. Eski yerleşik eklentiyle birlikte kullanmayın. Bu eklenti etkinse önce /plugin disable computer-use çalıştırın.",
+  connectRuntime: "Uygulama Node içerir; ayrıca yüklemeniz gerekmez. Başka bir konuma yüklendiyse APP değerini gerçek uygulama paketi yoluna ayarlayın.",
+  connectReload: "Açık bir terminal oturumunda /mcp reload çalıştırın, Operate moduna geçin ve şunu isteyin:",
+  connectPrompt: "Computer Use izinlerini request_access ile kontrol et. Hiçbir giriş gönderme.",
+  connectExpected: "Yanıtta via: app, yardımcı sürümü ve eksik izinleri kontrol edin. Yardımcı bulunamazsa durun ve kurulum ipucunu izleyin. Bu yalnızca bağlantıyı ve izinleri kontrol eder.",
+  connectGuide: "MCP kurulum rehberi",
+  contributeTitle: "Computer Use’u geliştirmeye katılın",
+  contributeBody: "Belgeleri iyileştirin veya bir uygulama iş akışını test edip tekrarlanabilir sonuçları paylaşın.",
+  contributeGuide: "Katkı rehberi",
+  contributeIssue: "Sorun bildirin",
 };
@@ -735,4 +735,16 @@ export interface ComputerUseDict {
  demo: string;
  source: string;
  platforms: string;
+  connectTitle: string;
+  connectVersion: string;
+  connectLimit: string;
+  connectRuntime: string;
+  connectReload: string;
+  connectPrompt: string;
+  connectExpected: string;
+  connectGuide: string;
+  contributeTitle: string;
+  contributeBody: string;
+  contributeGuide: string;
+  contributeIssue: string;
 }
@@ -27,7 +27,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Установіть застосунок", body: "Відкрийте образ диска й перетягніть Codewhale Computer Use у папку «Програми». Відкрийте його з папки «Програми», а потім виберіть Computer Use у меню з іконкою кита в смузі меню." },
    { title: "Перегляньте дозволи", body: "За допомогою кнопок налаштування відкрийте розділи «Доступність» і «Запис екрана» в Системних параметрах. Які дозволи надати — вирішуєте ви." },
-    { title: "Підключіть агента", body: "У Codewhale встановіть Computer Use командою /plugin marketplace install codewhale computer-use, потім перегляньте й увімкніть плагін. Помічник встановлюється окремо. Інші сумісні MCP-хости підключаються до нього за посібником із налаштування." },
+    { title: "Підключіть агента", body: "Виберіть нижче налаштування Codewhale для вашої версії CLI. Для інших сумісних MCP-клієнтів скористайтеся посібником із налаштування в репозиторії." },
  ],
  controlsTitle: "Контроль залишається у вас",
  controlsBody: "Після надання дозволів macOS стандартний режим працює без запитів для кожного застосунку. Заблоковані вами застосунки недоступні агенту; Pause призупиняє роботу з комп’ютером, а Stop computer use завершує поточні сеанси. Суворе підтвердження дій можна ввімкнути окремо. Щоб стежити за роботою, попросіть попередній перегляд наживо.",
@@ -36,6 +36,18 @@ export const computerUse: ComputerUseDict = {
  help: "Налаштування й усунення несправностей",
  notes: "Примітки до випуску",
  demo: "Подивитися фонову перевірку",
-  source: "Вихідний код та інші платформи",
+  source: "Переглянути на GitHub",
  platforms: "Помічник для Mac має статус бета, а плагін каталогу підтримує лише Mac. Опубліковані випуски також містять непідписану експериментальну попередню версію для Windows x64; Linux потребує експериментального налаштування з вихідного коду або через Docker. Введення у Windows і Linux використовує спільний робочий стіл.",
+  connectTitle: "Підключіть Codewhale",
+  connectVersion: "Codewhale 0.10.2 містить старішу версію плагіна Computer Use. Встановлення запису з каталогу її не оновлює. Підключіть встановлений Mac-помічник безпосередньо через MCP.",
+  connectLimit: "Пряме підключення MCP додає інструменти без навичок плагіна. Не використовуйте його разом зі старим вбудованим плагіном. Якщо той увімкнений, спочатку виконайте /plugin disable computer-use.",
+  connectRuntime: "Node входить до складу застосунку, окремо встановлювати його не потрібно. Якщо застосунок встановлено деінде, задайте APP фактичний шлях до пакета застосунку.",
+  connectReload: "У запущеному термінальному сеансі виконайте /mcp reload, перейдіть у Operate та попросіть:",
+  connectPrompt: "Перевір дозволи Computer Use за допомогою request_access. Не надсилай ввід.",
+  connectExpected: "Перевірте у відповіді via: app, версію помічника й відсутні дозволи. Якщо помічника немає, зупиніться та дотримуйтеся підказки з налаштування. Це перевірка лише підключення та дозволів.",
+  connectGuide: "Посібник із налаштування MCP",
+  contributeTitle: "Допоможіть покращити Computer Use",
+  contributeBody: "Покращуйте документацію або перевіряйте сценарії роботи в застосунках і діліться відтворюваними результатами.",
+  contributeGuide: "Посібник для учасників",
+  contributeIssue: "Повідомити про проблему",
 };
@@ -27,7 +27,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "Cài đặt ứng dụng", body: "Mở ảnh đĩa và kéo Codewhale Computer Use vào thư mục “Ứng dụng”. Mở ứng dụng từ “Ứng dụng”, rồi chọn Computer Use từ biểu tượng cá voi trên thanh menu." },
    { title: "Xem lại quyền truy cập", body: "Dùng các nút thiết lập để mở “Trợ năng” và “Ghi màn hình” trong Cài đặt Hệ thống. Bạn tự quyết định cấp những quyền nào." },
-    { title: "Kết nối tác nhân của bạn", body: "Trong Codewhale, cài Computer Use bằng /plugin marketplace install codewhale computer-use, rồi xem lại và bật plugin. Ứng dụng hỗ trợ được cài riêng. Các host MCP tương thích khác kết nối với ứng dụng theo hướng dẫn thiết lập." },
+    { title: "Kết nối tác nhân của bạn", body: "Chọn cách thiết lập Codewhale bên dưới phù hợp với phiên bản CLI của bạn. Các ứng dụng chủ MCP tương thích khác dùng hướng dẫn thiết lập trong kho mã." },
  ],
  controlsTitle: "Bạn luôn nắm quyền kiểm soát",
  controlsBody: "Sau khi cấp quyền macOS, chế độ tiêu chuẩn hoạt động mà không hỏi quyền cho từng ứng dụng. Các ứng dụng bạn chặn vẫn không thể truy cập; Pause tạm dừng thao tác máy tính và Stop computer use kết thúc các phiên hiện tại. Chế độ phê duyệt nghiêm ngặt là tùy chọn. Yêu cầu xem trước trực tiếp khi bạn muốn theo dõi công việc.",
@@ -36,6 +36,18 @@ export const computerUse: ComputerUseDict = {
  help: "Thiết lập và khắc phục sự cố",
  notes: "Ghi chú phát hành",
  demo: "Xem kiểm tra nền",
-  source: "Mã nguồn và các nền tảng khác",
+  source: "Xem trên GitHub",
  platforms: "Ứng dụng hỗ trợ trên Mac đang ở bản beta và plugin trong danh mục chỉ hỗ trợ Mac. Các bản phát hành cũng có bản xem trước thử nghiệm chưa được ký cho Windows x64; Linux cần thiết lập thử nghiệm từ mã nguồn hoặc qua Docker. Thao tác nhập trên Windows và Linux sử dụng màn hình nền dùng chung.",
+  connectTitle: "Kết nối Codewhale",
+  connectVersion: "Codewhale 0.10.2 tích hợp một plugin Computer Use cũ. Cài mục trong danh mục không nâng cấp plugin đó. Hãy kết nối trực tiếp với ứng dụng trợ giúp Mac đã cài qua MCP.",
+  connectLimit: "Kết nối MCP trực tiếp thêm công cụ nhưng không thêm kỹ năng của plugin. Không dùng đồng thời với plugin tích hợp cũ. Nếu plugin đó đang bật, hãy chạy /plugin disable computer-use trước.",
+  connectRuntime: "Ứng dụng có sẵn Node, không cần cài riêng. Nếu cài ở nơi khác, đặt APP thành đường dẫn thực tế của gói ứng dụng.",
+  connectReload: "Trong phiên terminal đang chạy, chạy /mcp reload, chuyển sang Operate rồi yêu cầu:",
+  connectPrompt: "Kiểm tra quyền Computer Use bằng request_access. Không gửi thao tác nhập liệu.",
+  connectExpected: "Kiểm tra via: app, phiên bản ứng dụng trợ giúp và các quyền còn thiếu trong phản hồi. Nếu thiếu ứng dụng trợ giúp, hãy dừng lại và làm theo hướng dẫn thiết lập. Bước này chỉ kiểm tra kết nối và quyền.",
+  connectGuide: "Hướng dẫn thiết lập MCP",
+  contributeTitle: "Góp phần cải thiện Computer Use",
+  contributeBody: "Cải thiện tài liệu hoặc thử một quy trình trong ứng dụng và chia sẻ kết quả có thể tái hiện.",
+  contributeGuide: "Hướng dẫn đóng góp",
+  contributeIssue: "Báo cáo sự cố",
 };
@@ -26,7 +26,7 @@ export const computerUse: ComputerUseDict = {
  steps: [
    { title: "安装应用", body: "打开下载的磁盘映像，将 Codewhale Computer Use 拖入“应用程序”。从“应用程序”中打开它，然后点击菜单栏中的鲸鱼图标，选择 Computer Use。" },
    { title: "检查权限", body: "通过设置按钮打开系统设置中的“辅助功能”和“屏幕录制”。由你决定授予哪些权限。" },
-    { title: "连接智能体", body: "在 Codewhale 中运行 /plugin marketplace install codewhale computer-use，审阅并启用插件。其他兼容 MCP 的宿主可按设置指南连接助手。" },
+    { title: "连接智能体", body: "选择下方适用于你的 CLI 版本的 Codewhale 设置方式。其他兼容 MCP 的宿主请参阅仓库中的设置指南。" },
  ],
  controlsTitle: "随时掌握控制权",
  controlsBody: "授予 macOS 权限后，标准模式无需逐个应用询问。你禁用的应用仍不可访问；Pause 暂停电脑操作，Stop computer use 结束当前会话。也可选择严格审批模式。想观看操作过程时，再请求打开实时预览。",
@@ -35,6 +35,18 @@ export const computerUse: ComputerUseDict = {
  help: "设置与故障排查",
  notes: "版本说明",
  demo: "查看后台检查演示",
-  source: "其他宿主与平台",
+  source: "在 GitHub 上查看",
  platforms: "Mac 助手为测试版，市场插件支持 Mac。已发布版本另含未签名的 Windows x64 实验性预览包；Linux 需要实验性源码或 Docker 设置。Windows 和 Linux 的输入使用共享桌面。",
+  connectTitle: "连接 Codewhale",
+  connectVersion: "Codewhale 0.10.2 内置较旧的 Computer Use 插件，安装目录中的同名条目不会将其升级。请通过 MCP 直接连接已安装的 Mac 助手。",
+  connectLimit: "直接连接 MCP 只添加工具，不包含插件技能。请勿与旧版内置插件同时使用；如果该插件已启用，请先运行 /plugin disable computer-use。",
+  connectRuntime: "应用自带 Node，无需另行安装。如果应用安装在其他位置，请将 APP 设为实际应用包路径。",
+  connectReload: "在正在运行的终端会话中执行 /mcp reload，切换到 Operate，然后输入：",
+  connectPrompt: "使用 request_access 检查 Computer Use 权限。不要发送任何输入。",
+  connectExpected: "检查回复中的 via: app、助手版本及缺少的权限。如果找不到助手，请停止并按设置提示操作。此步骤仅检查连接和权限。",
+  connectGuide: "MCP 设置指南",
+  contributeTitle: "一起改进 Computer Use",
+  contributeBody: "完善文档，或测试应用操作流程并分享可复现的结果。",
+  contributeGuide: "贡献指南",
+  contributeIssue: "报告问题",
 };
@@ -71,7 +71,7 @@ codewhale config doctor     # unknown keys, empty secrets, malformed URLs`,
          codeTerms: true,
        },
        {
-          p: "密钥、服务端点、提供商选择、MCP 服务器、钩子、技能和额外的说明文件，始终来自你自己的配置，因此克隆下来的仓库无法让 Codewhale 指向它自己的服务器或文件。启动时加上 `--no-project-config`，可以在这一次运行中忽略仓库的配置文件。",
+          p: "提供商密钥、服务端点及提供商选择来自你自己的配置。在用户设置中信任工作区后，MCP 服务器也可来自 `.codewhale/mcp.json`；项目条目覆盖同名的全局条目。信任仓库前，请审阅这些可执行权限。参阅 [MCP 配置](/docs/mcp#config)。",
        },
        {
          p: "项目说明——智能体在这个仓库里应该如何工作——请写在 `AGENTS.md` 中。运行 `/init` 即可生成一份。",
@@ -4,31 +4,55 @@ import type { DocsMcpDict } from "../types";
 export const docsMcp: DocsMcpDict = {
  metaTitle: "用 MCP 连接工具 · Codewhale 文档",
  metaDescription:
-    "添加 Model Context Protocol 服务器让 Codewhale 使用更多工具，登录远程服务器，把 Codewhale 本身作为 MCP 服务器运行，并试用代码模式。",
+    "连接本地和远程 MCP 服务器，了解认证与插件兼容范围，并排查工具未显示的问题。",
  bodyClassName: "text-ink-soft leading-[1.9] tracking-wide",
  title: "用 MCP 连接工具",
  lede:
-    "MCP 服务器能为 Codewhale 带来更多工具——数据库、问题跟踪系统、浏览器等。你可以添加一个由 Codewhale 替你启动的本地服务器，也可以通过 URL 添加远程服务器。这些工具与内置工具走同一套审批流程。",
+    "通过 Model Context Protocol 连接本地工具服务器或远程服务。Codewhale 会发现服务器提供的工具，并在使用时执行你的工具权限和审批规则。",
  sections: [
    {
      id: "add",
-      title: "添加服务器",
+      title: "试用 Cloudflare Docs 服务器",
      blocks: [
        {
-          code: `codewhale mcp add git --command "uvx" --arg "mcp-server-git"
-codewhale mcp add docs --url "https://example.com/mcp"
-codewhale mcp list
-codewhale mcp validate`,
+          p: "公开的 [Cloudflare 文档服务器](https://developers.cloudflare.com/agents/model-context-protocol/cloudflare/servers-for-cloudflare/)提供文档搜索和 Pages 迁移到 Workers 的指南。[查看官方源码](https://github.com/cloudflare/mcp-server-cloudflare/tree/main/apps/docs-vectorize)。无需凭据即可添加：",
+        },
+        {
+          code: `codewhale mcp add cloudflare-docs --url "https://docs.mcp.cloudflare.com/mcp"
+codewhale mcp tools cloudflare-docs`,
          lang: "终端",
        },
        {
-          p: "`--command` 通过 stdio 启动本地服务器，每个参数用一个 `--arg`。`--url` 通过 Streamable HTTP 连接远程服务器，必要时回退到旧版 SSE。`mcp validate` 会检查配置文件以及你标记为必需的服务器。",
+          p: "工具列表应包含 `search_cloudflare_documentation` 和 `migrate_pages_to_workers_guide`。如果 TUI 会话已在运行，请在其中执行 `/mcp reload`，把新配置加载到该会话。",
+        },
+        {
+          note: "2026 年 11 月 7 日使用已发布的 CLI v0.10.2 检查：两条命令均成功退出，无需凭据即可列出上述两个工具。这验证了配置和发现流程，没有执行工具。[发布版指南](https://github.com/codewhale-hq/Codewhale/blob/v0.10.2/docs/MCP.md)对应此版本；[main 源码指南](https://github.com/codewhale-hq/Codewhale/blob/main/docs/MCP.md)可能包含尚未发布的变更。",
        },
        {
          p: "在会话中，`/mcp` 会打开 MCP 管理器：显示每个服务器的状态、传输方式、超时设置、错误信息和已发现的工具。同样的操作在那里也能完成，例如 `/mcp add stdio <name> <command>` 和 `/mcp add http <name> <url>`。",
        },
        {
-          note: "MCP 服务器以你的权限运行。只添加你信任的服务器，就像只安装你信任的程序一样。",
+          note: "本地 MCP 服务器以 Codewhale 进程的权限运行；远程调用使用你授予该服务的访问权限。只添加你信任的服务器。",
+        },
+      ],
+    },
+    {
+      id: "compatibility",
+      title: "可以连接哪些服务器",
+      blocks: [
+        {
+          rows: [
+            ["本地 stdio", "Codewhale 启动 `--command` 指定的程序，每个参数用一个 `--arg`。请先安装服务器及其所需运行时。"],
+            ["远程 HTTP / SSE", "`--url` 使用 Streamable HTTP，并可回退到旧版 SSE。旧版 SSE 端点可设置 `--transport sse`。远程配置不需要 `command`。"],
+            ["直接配置的远程认证", "你自己的 MCP 配置可以使用环境变量请求头、bearer token 或 OAuth。OAuth 需要服务器提供兼容的认证元数据和客户端注册方式。"],
+            ["插件提供的 MCP", "经过审查并启用的插件可以提供 stdio 或远程 MCP 服务器。插件 MCP 支持基于环境变量的认证，但不支持插件提供的 MCP OAuth。"],
+            ["工具、资源与提示词", "Codewhale 发现服务器实际声明的能力。只有服务器实现了资源、模板或提示词功能，才能使用这些功能。"],
+            ["可选扩展与 MCP Apps", "尚不提供通用的 MCP Apps 界面支持。支持基本 MCP 传输不等于兼容所有可选扩展或服务器。"],
+            ["服务器要求", "每个服务器都有自己的操作系统、程序、浏览器、依赖和账号要求。本地服务器运行在承载 Codewhale 的电脑上；Computer Use 有其独立的平台限制。"],
+          ],
+        },
+        {
+          p: "直接添加 MCP 不需要插件。[插件](/plugins)可以把 MCP 工具、指令和其他组件打包在一起；各组件仍需要兼容的依赖、审查和权限。",
        },
      ],
    },
@@ -37,13 +61,16 @@ codewhale mcp validate`,
      title: "登录远程服务器",
      blocks: [
        {
-          p: "使用 OAuth 的服务器，先用 URL 添加再登录。使用 bearer token 的服务器，把令牌放在环境变量里，而不是写进配置文件：",
+          p: "直接配置 OAuth 服务器时，先添加它的真实 URL，再用你设置的服务器名称登录：",
        },
        {
-          code: `codewhale mcp login docs
-codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var TRACKER_TOKEN`,
+          code: `codewhale mcp login <server>
+codewhale mcp logout <server>`,
          lang: "终端",
        },
+        {
+          p: "使用 bearer token 时，添加服务器时指定 `--bearer-token-env-var TOKEN_NAME`，并在启动 Codewhale 的环境中设置该变量。`env_headers` 把请求头名称映射到环境变量名。字面量 `headers` 不会展开 `${TOKEN_NAME}`。插件 MCP 不能使用 OAuth；需要 OAuth 时，请直接配置该服务器。",
+        },
        {
          p: "显式设置的 Authorization 请求头始终优先：先应用配置中的请求头，其次是 bearer token 环境变量，最后才是已保存的 OAuth 登录。`codewhale mcp logout <name>` 会删除本机保存的登录信息；提供商那边的授权可能仍然有效，需要到提供商处撤销。",
        },
@@ -54,23 +81,26 @@ codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var
      title: "编辑配置文件",
      blocks: [
        {
-          p: "服务器配置保存在 `~/.codewhale/mcp.json`，`codewhale mcp init` 会生成一个初始文件。其他客户端使用的 `mcpServers` 键同样可用，现成的配置可以直接粘贴进来。",
+          p: "全局服务器配置保存在 `~/.codewhale/mcp.json`；如果该文件不存在，仍会读取旧版 `~/.deepseek/mcp.json`。`codewhale mcp init` 会生成初始文件。可用绝对路径 `mcp_config_path` 或 `CODEWHALE_MCP_CONFIG` 覆盖默认位置。环境变量也接受 `DEEPSEEK_MCP_CONFIG`；两者都设置时，Codewhale 名称优先。",
        },
        {
          code: `{
  "servers": {
-    "example": {
-      "command": "node",
-      "args": ["./path/to/your-mcp-server.js"],
-      "env": {},
-      "disabled": false
+    "cloudflare-docs": {
+      "url": "https://docs.mcp.cloudflare.com/mcp"
    }
  }
 }`,
          lang: "mcp.json",
        },
        {
-          p: "修改文件后，在会话中运行 `/mcp reload` 即可，无需重启。服务器只在某个回合需要它的工具时才启动；如果希望它在启动时就连接，把它标记为 `\"required\": true`。",
+          p: "`servers` 和别名 `mcpServers` 二选一，不要在同一文件中同时使用。`env_http_headers` 是 `env_headers` 的别名。请按服务器文档调整命令、参数和认证字段，不要假定所有客户端的配置格式都能直接互换。",
+        },
+        {
+          p: "受信任的工作区可以提供 `.codewhale/mcp.json`，其中同名服务器会覆盖全局配置；仓库不能自行授予信任，也不能覆盖你的全局配置路径。全局或受信任项目中的显式配置，优先于标识冲突的插件服务器。",
+        },
+        {
+          p: "修改后在 TUI 中运行 `/mcp reload` 即可，无需重启。默认情况下，已启用且获准的服务器会在会话启动时连接。用户配置的服务器可设置 `\"lazy\": true` 按需连接；设置 `\"required\": true` 后仍会在启动时连接。插件 MCP 清单没有 lazy 选项。无界面的运行时在配置变更后需要重启。",
        },
      ],
    },
@@ -79,10 +109,26 @@ codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var
      title: "找到这些工具",
      blocks: [
        {
-          p: "每个工具在模型眼中的名字是 `mcp_<server>_<tool>`：名为 `git` 的服务器提供的 `status` 工具，就叫 `mcp_git_status`。`codewhale mcp tools <server>` 会列出某个服务器提供的工具。连接失败或已禁用的服务器，其工具永远不会显示为可用。",
+          p: "每个工具在模型眼中的名字是 `mcp_<server>_<tool>`。本例中的文档搜索是 `mcp_cloudflare-docs_search_cloudflare_documentation`。`codewhale mcp tools <server>` 在自己的进程中列出发现的工具，不会把连接附加到正在运行的会话。",
        },
        {
-          p: "MCP 工具遵循你的[审批设置](/docs/modes)：在策略允许时，列出和读取服务器的资源与提示词无需确认；有副作用的工具会先征求你的同意。Full Access 也不会绕过仓库规则或托管策略。",
+          p: "MCP 工具遵循你的[审批设置](/docs/modes)、允许/拒绝规则及网络策略。调用前是否询问，取决于策略与权限姿态。Full Access 不会绕过仓库规则或托管策略。",
+        },
+      ],
+    },
+    {
+      id: "troubleshooting",
+      title: "工具没有出现时",
+      blocks: [
+        {
+          rows: [
+            ["检查配置", "`codewhale doctor` 提供静态路径和配置诊断。终端中的 `codewhale mcp validate` 会在独立进程中连接已启用且获准的服务器，属于实际连接检查。"],
+            ["刷新当前会话", "TUI 中的 `/mcp validate` 只显示上次快照，不会重新连接。配置变更后使用 `/mcp reload`；单个服务器可用 `/mcp retry <name>`。"],
+            ["已连接但缺少工具", "检查 `codewhale mcp tools <server>`、服务器声明的工具、`enabled_tools` / `disabled_tools`，以及会话的允许/拒绝规则。传输已连接不代表某个工具可用或已获准。"],
+            ["需要认证", "直接配置的 OAuth 服务器可运行 `/mcp login <name>`。令牌认证请检查变量是否存在于 Codewhale 的启动环境中。在一个进程中登录成功，不会把该进程的连接附加到另一个进程。"],
+            ["本地命令失败", "检查服务器程序、参数、工作目录和运行时。Windows 上的包运行器可能需要使用 `.cmd` 名称。请遵循服务器提供方的操作系统和依赖说明。"],
+            ["插件服务器缺失", "检查所属插件的审查、信任和启用状态。MCP 设置不能激活不受信任的插件，也不能绕过被拒绝的清单。"],
+          ],
        },
      ],
    },
@@ -91,7 +137,7 @@ codewhale mcp add tracker --url "https://example.com/mcp" --bearer-token-env-var
      title: "把 Codewhale 作为 MCP 服务器运行",
      blocks: [
        {
-          p: "其他 MCP 客户端可以把 Codewhale 作为工具服务器。默认仅暴露只读的 `file_read` 和 `search` 工具。",
+          p: "支持 Codewhale 声明的 MCP 协议版本的客户端，可以把它作为 stdio 工具服务器启动。默认仅暴露只读的 `file_read` 和 `search` 工具。",
        },
        {
          code: `codewhale mcp add-self
@@ -99,7 +145,7 @@ codewhale mcp tools codewhale`,
          lang: "终端",
        },
        {
-          p: "`add-self` 注册通过 stdio 运行的 `codewhale serve --mcp`；`codewhale mcp-server` 是等价入口。除非操作者在服务器配置中明确允许，否则不会提供写入工具。[Runtime API](/docs/runtime-api) HTTP 是单独的传输方式。",
+          p: "`add-self` 注册 `codewhale serve --mcp`；`codewhale mcp-server` 是等价入口。这个服务器从旧版路径 `~/.deepseek/mcp_server.toml` 读取独立的 `[server]` 设置，而不是客户端的 `mcp.json`。写入或 shell 工具需要显式列出，并设置 `require_approval = false`；这里没有交互式审批通道。[Runtime API](/docs/runtime-api) HTTP 与 MCP 分开。",
        },
      ],
    },
@@ -107,6 +153,9 @@ codewhale mcp tools codewhale`,
      id: "code-mode",
      title: "用代码模式组合工具调用（实验性）",
      blocks: [
+        {
+          note: "本节依据 main 候选版本的源码，可能包含比已发布 v0.10.2 更新的行为。",
+        },
        {
          p: "代码模式让模型写一段简短的 JavaScript 程序，在其中调用多个工具、循环和筛选结果，而不必把每次调用都作为单独的一步。只有程序的最终结果会返回给模型，长时间的查找因此更紧凑。它默认开启——`execute_tools` 从第一条请求起就会提供——MCP 和插件工具与内置工具一样可以在程序中组合调用。关闭它并不会移除代码模式：`execute_tools` 会恢复为延迟加载，模型仍可通过 `tool_search` 找到它。要关闭它，可以只在一次会话中关闭，也可以在配置中关闭：",
        },
@@ -78,12 +78,6 @@ const EXTRA_PAGES: readonly { path: string; title: string; description: string }
    description:
      "Codewhale release record: the latest published release, the unreleased source candidate, and the notes for each version, drawn from CHANGELOG.md in the repository.",
  },
-  {
-    path: "/plugins",
-    title: "Plugins and marketplace",
-    description:
-      "Preview Computer Use for selected desktop apps, and install reviewed plugins from the Codewhale catalog, a GitHub repository, or a tarball.",
-  },
  {
    path: "/ratatui",
    title: "Codewhale Ratatui",
@@ -174,6 +168,11 @@ export function buildLlmsTxt(): string {
    `- [Full documentation](${SITE_URL}/llms-full.txt): Every documentation topic as plain text.`,
    `- [Runtime API](${SITE_URL}/docs-markdown/runtime-api.md): HTTP/SSE API and ACP integration.`,
    `- [MCP](${SITE_URL}/docs-markdown/mcp.md): Connect tools or run codewhale mcp-server / codewhale serve --mcp. Default server tools are read-only file_read and search.`,
+    "", "## Plugins and MCP", "",
+    `- [Choose an integration](${SITE_URL}/en/plugins): Skills are instructions; plugins package reviewed capabilities; MCP servers supply external tools, resources and prompts.`,
+    `- [Connect MCP servers](${SITE_URL}/en/docs/mcp): Local stdio and remote Streamable HTTP, legacy SSE, environment-backed tokens and direct-server OAuth. Plugin-bundled MCP does not support OAuth.`,
+    `- [Computer Use](${SITE_URL}/en/computer-use): Mac helper setup, CLI-version limitations and its separate open-source repository.`,
+    `- [Public plugin catalog](https://github.com/codewhale-hq/codewhale-plugin-marketplace): Installed CLI releases bundle a dated snapshot; current catalog entries are not proof of installed versions or end-to-end qualification.`,
    "", "## Documentation", "",
  );
  for (const topic of DOC_TOPICS) {