From 21fb18b5fcce12bc3ce508e61c8ee22121c0fb51 Mon Sep 17 00:00:00 2001
From: Neil <bn0010100@gmail.com>
Date: Sun, 23 Aug 2026 14:42:53 +0800
Subject: [PATCH 1/4] chore(docs): synchronize renderer guidance

---
 README.md                     | 37 +++++++++++++++++++++++++----------
 packages/dsh-web/README.md    |  8 ++++++--
 packages/dsh-web/package.json |  2 +-
 packages/dsh-web/src/tools.ts |  2 +-
 packages/pi-web/package.json  |  2 +-
 packages/pi-web/src/tool.ts   |  2 +-
 packages/web/package.json     |  2 +-
 packages/web/src/mcp.ts       |  2 +-
 8 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index b4a377c..5270cb4 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,11 @@
 # Guion Web
 
 Guion Web is a Node.js web research toolkit. It provides Exa or Brave search,
-browserless HTML-to-Markdown extraction, Context7 library documentation lookup,
-and Sourcegraph public code search through a CLI, stdio MCP server, Pi extension,
-and DeepSeek Harness (DSH) integration.
+browserless-first HTML-to-Markdown extraction, Context7 library documentation
+lookup, and Sourcegraph public code search through a CLI, stdio MCP server, Pi
+extension, and DeepSeek Harness (DSH) integration. An explicit optional
+`agent-browser` retry can render client-side pages on supported hosts; it is not
+a bundled browser or an automatic fallback.
 
 ## Install and configure
 
@@ -64,7 +66,9 @@ web mcp --provider brave
 
 The server exposes five read-only tools: `search`, `fetch`, `docs_resolve`,
 `docs_fetch`, and `sgraph_search`. Its stdout is reserved for MCP protocol
-messages; diagnostics go to stderr.
+messages; diagnostics go to stderr. For a client-rendered page, explicitly call
+`fetch` with `render: "agent-browser"` and an integer `waitMs`; this optional
+retry requires a host-installed executable and never happens automatically.
 
 ## Pi
 
@@ -76,7 +80,9 @@ pi install npm:@guionai/pi-web
 
 It registers `web_search`, `web_fetch`, `web_docs`, and `web_sgraph` and calls
 the bundled core in-process. Pi and TypeBox are peer dependencies supplied by
-the host; no CLI executable or MCP configuration is required.
+the host; no CLI executable or MCP configuration is required. `web_fetch` is
+browserless by default; explicitly pass `render: "agent-browser"` and an
+integer `waitMs` only when its host provides that optional executable.
 
 ## DSH
 
@@ -90,6 +96,9 @@ The included profile patch routes stock PTC web search through the selected Exa
 or Brave provider. Its settings UI stores provider selection and manages
 namespaced write-only credentials. Fetch, documentation, and Sourcegraph tools
 also run in-process. The host DSH packages and React are peers supplied by DSH.
+`web_fetch` is browserless by default; use `render: "agent-browser"` with an
+integer `waitMs` only for an explicit retry on a host that supplies the optional
+executable.
 
 ## Optional JavaScript rendering
 
@@ -112,11 +121,19 @@ must not provide `--wait`. The same `render: "agent-browser"` and required
 `javascript_rendering_may_be_required` hint with the 2,000 ms suggestion; the
 agent decides whether to retry with a longer wait or abandon the page.
 
-Rendering is an optional host capability. The host must already have a
-compatible `agent-browser` executable directly runnable from `PATH`; this
-project does not install it, download Chromium, or reuse browser credentials.
-The renderer is supported on macOS and Linux hosts. The three npm packages
-remain browserless and installable when `agent-browser` is absent.
+Rendering is an optional host capability. If you choose to use it, install
+[agent-browser](https://github.com/vercel-labs/agent-browser) separately on the
+host:
+
+```bash
+npm install --global agent-browser
+agent-browser install
+```
+
+`agent-browser install` manages its own browser runtime; Guion packages never
+run it, bundle it, or reuse browser credentials. The renderer is supported on
+macOS and Linux hosts. The three npm packages remain browserless and installable
+when `agent-browser` is absent.
 
 A rendered session is fresh and non-persistent. Before launch, the target must
 be an HTTP(S) public hostname or address. The browser allowlist then contains
diff --git a/packages/dsh-web/README.md b/packages/dsh-web/README.md
index 60482fa..3c5eb2e 100644
--- a/packages/dsh-web/README.md
+++ b/packages/dsh-web/README.md
@@ -23,8 +23,12 @@ and Sourcegraph all run in-process through the bundled Guion Web core.
 `web_fetch` remains browserless by default; an agent may explicitly request
 `render: "agent-browser"` with a required integer `waitMs` from 0 through
 30,000 to render a client-side page through a host-installed `agent-browser`
-executable. The optional renderer is supported on macOS and Linux, is not an
-npm dependency, and never reuses persistent browser state or credentials.
+executable. To enable that optional capability, install
+[agent-browser](https://github.com/vercel-labs/agent-browser) separately with
+`npm install --global agent-browser` followed by `agent-browser install`. Its
+browser runtime is managed outside this package; the renderer is supported on
+macOS and Linux, is not an npm dependency, and never reuses persistent browser
+state or credentials.
 
 Rendered requests are bounded and constrained to the requested hostname,
 `*.<requested-hostname>` (the target and its subdomains), and this fixed common
diff --git a/packages/dsh-web/package.json b/packages/dsh-web/package.json
index 5ec082c..d9a0b0f 100644
--- a/packages/dsh-web/package.json
+++ b/packages/dsh-web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/dsh-web",
   "version": "0.1.0",
-  "description": "Guion Web provider and settings for DeepSeek Harness rc.8.",
+  "description": "Guion Web provider and settings for DeepSeek Harness rc.8 with optional host rendering.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"
diff --git a/packages/dsh-web/src/tools.ts b/packages/dsh-web/src/tools.ts
index 1144e5a..9da5f8f 100644
--- a/packages/dsh-web/src/tools.ts
+++ b/packages/dsh-web/src/tools.ts
@@ -278,7 +278,7 @@ function webFetchTool(
     defineTool({
       name: "web_fetch",
       description:
-        "Fetch and read an HTTP or HTTPS web page as Markdown with heading-tree and section navigation.",
+        "Fetch a browserless HTTP or HTTPS page as Markdown with heading-tree and section navigation; explicitly choose host-installed agent-browser rendering with required waitMs for client-rendered pages.",
       parameters: fetchParameters,
       output: fetchOutput,
       isConcurrencySafe: () => true,
diff --git a/packages/pi-web/package.json b/packages/pi-web/package.json
index a57bf7d..f49c34f 100644
--- a/packages/pi-web/package.json
+++ b/packages/pi-web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/pi-web",
   "version": "0.1.0",
-  "description": "Pi extension for in-process web search, page fetch, documentation, and Sourcegraph code search.",
+  "description": "Pi extension for in-process web research with optional host-installed page rendering.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"
diff --git a/packages/pi-web/src/tool.ts b/packages/pi-web/src/tool.ts
index 800df52..5c58b9f 100644
--- a/packages/pi-web/src/tool.ts
+++ b/packages/pi-web/src/tool.ts
@@ -150,7 +150,7 @@ const SEARCH_PROMPT_GUIDELINES = [
 ];
 const FETCH_PROMPT_GUIDELINES = [
   "Use web_fetch to read a web page; large pages are truncated with a continuation notice, so follow up with tree or section_id to navigate.",
-  'Browserless fetching is the default. If the result says JavaScript rendering may be required, retry explicitly with render: "agent-browser" and waitMs from 0 through 30000.',
+  'Browserless fetching is the default. If the result says JavaScript rendering may be required, retry explicitly with render: "agent-browser" and waitMs from 0 through 30000 only when the host has agent-browser installed; there is no automatic fallback.',
 ];
 const DOCS_PROMPT_GUIDELINES = [
   "Use web_docs with action resolve, then action fetch, to read library documentation instead of fetching documentation sites page by page.",
diff --git a/packages/web/package.json b/packages/web/package.json
index 1ebed2e..a1cc88c 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/web",
   "version": "0.1.0",
-  "description": "Browserless web research CLI and stdio MCP server.",
+  "description": "Browserless-first web research CLI and stdio MCP server with optional host rendering.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"
diff --git a/packages/web/src/mcp.ts b/packages/web/src/mcp.ts
index 5fef3da..4919a17 100644
--- a/packages/web/src/mcp.ts
+++ b/packages/web/src/mcp.ts
@@ -244,7 +244,7 @@ export function createMcpServer(dependencies: McpDependencies): McpServer {
     "fetch",
     toolConfig(
       "Fetch a web page",
-      "Fetch a web page and return rendered Markdown content.",
+      "Fetch a browserless web page as Markdown, or explicitly use host-installed agent-browser rendering with required waitMs.",
       fetchInputSchema,
       fetchOutputSchema,
     ),

From f74167c0eb014b41cb782c4d4f050041263f63c9 Mon Sep 17 00:00:00 2001
From: Neil <bn0010100@gmail.com>
Date: Sun, 23 Aug 2026 14:51:24 +0800
Subject: [PATCH 2/4] fix(docs): clarify renderer prerequisite

---
 README.md                     | 3 ++-
 packages/dsh-web/README.md    | 3 ++-
 packages/dsh-web/package.json | 2 +-
 packages/pi-web/package.json  | 2 +-
 packages/web/package.json     | 2 +-
 5 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 5270cb4..557c5ce 100644
--- a/README.md
+++ b/README.md
@@ -131,7 +131,8 @@ agent-browser install
 ```
 
 `agent-browser install` manages its own browser runtime; Guion packages never
-run it, bundle it, or reuse browser credentials. The renderer is supported on
+run it, bundle it, or reuse browser credentials. A compatible executable must be
+directly runnable from `PATH` without a shell. The renderer is supported on
 macOS and Linux hosts. The three npm packages remain browserless and installable
 when `agent-browser` is absent.
 
diff --git a/packages/dsh-web/README.md b/packages/dsh-web/README.md
index 3c5eb2e..be1ce5a 100644
--- a/packages/dsh-web/README.md
+++ b/packages/dsh-web/README.md
@@ -26,7 +26,8 @@ and Sourcegraph all run in-process through the bundled Guion Web core.
 executable. To enable that optional capability, install
 [agent-browser](https://github.com/vercel-labs/agent-browser) separately with
 `npm install --global agent-browser` followed by `agent-browser install`. Its
-browser runtime is managed outside this package; the renderer is supported on
+browser runtime is managed outside this package; the compatible executable must
+be directly runnable from `PATH` without a shell. The renderer is supported on
 macOS and Linux, is not an npm dependency, and never reuses persistent browser
 state or credentials.
 
diff --git a/packages/dsh-web/package.json b/packages/dsh-web/package.json
index d9a0b0f..81292b9 100644
--- a/packages/dsh-web/package.json
+++ b/packages/dsh-web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/dsh-web",
   "version": "0.1.0",
-  "description": "Guion Web provider and settings for DeepSeek Harness rc.8 with optional host rendering.",
+  "description": "DeepSeek Harness rc.8 provider for browserless HTML-to-Markdown web research with optional host rendering.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"
diff --git a/packages/pi-web/package.json b/packages/pi-web/package.json
index f49c34f..8606851 100644
--- a/packages/pi-web/package.json
+++ b/packages/pi-web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/pi-web",
   "version": "0.1.0",
-  "description": "Pi extension for in-process web research with optional host-installed page rendering.",
+  "description": "Pi extension for browserless HTML-to-Markdown web research with optional host rendering.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"
diff --git a/packages/web/package.json b/packages/web/package.json
index a1cc88c..2913bf2 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/web",
   "version": "0.1.0",
-  "description": "Browserless-first web research CLI and stdio MCP server with optional host rendering.",
+  "description": "Browserless clean Markdown web research CLI and stdio MCP server with optional host rendering.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"

From 9272e673ad60a261e7d76d84f959c0d507438b0d Mon Sep 17 00:00:00 2001
From: Neil <bn0010100@gmail.com>
Date: Sun, 23 Aug 2026 15:01:51 +0800
Subject: [PATCH 3/4] refactor(docs): describe fetch backends

---
 README.md                     | 43 ++++++++++++++++++-----------------
 packages/dsh-web/README.md    | 11 +++++----
 packages/dsh-web/package.json |  2 +-
 packages/dsh-web/src/tools.ts |  4 ++--
 packages/pi-web/package.json  |  2 +-
 packages/pi-web/src/tool.ts   |  6 ++---
 packages/web/package.json     |  2 +-
 packages/web/src/mcp.ts       |  4 ++--
 8 files changed, 38 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 557c5ce..80fac49 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,10 @@
 # Guion Web
 
 Guion Web is a Node.js web research toolkit. It provides Exa or Brave search,
-browserless-first HTML-to-Markdown extraction, Context7 library documentation
-lookup, and Sourcegraph public code search through a CLI, stdio MCP server, Pi
-extension, and DeepSeek Harness (DSH) integration. An explicit optional
-`agent-browser` retry can render client-side pages on supported hosts; it is not
-a bundled browser or an automatic fallback.
+Context7 library documentation lookup, Sourcegraph public code search, and two
+page-fetch backends through a CLI, stdio MCP server, Pi extension, and DeepSeek
+Harness (DSH) integration: direct HTML-to-Markdown extraction and explicit
+`agent-browser` rendering for client-rendered pages on supported hosts.
 
 ## Install and configure
 
@@ -80,9 +79,9 @@ pi install npm:@guionai/pi-web
 
 It registers `web_search`, `web_fetch`, `web_docs`, and `web_sgraph` and calls
 the bundled core in-process. Pi and TypeBox are peer dependencies supplied by
-the host; no CLI executable or MCP configuration is required. `web_fetch` is
-browserless by default; explicitly pass `render: "agent-browser"` and an
-integer `waitMs` only when its host provides that optional executable.
+the host; no CLI executable or MCP configuration is required. `web_fetch` uses
+direct fetch by default and can explicitly use `render: "agent-browser"` with
+an integer `waitMs` when its host provides that optional executable.
 
 ## DSH
 
@@ -96,16 +95,18 @@ The included profile patch routes stock PTC web search through the selected Exa
 or Brave provider. Its settings UI stores provider selection and manages
 namespaced write-only credentials. Fetch, documentation, and Sourcegraph tools
 also run in-process. The host DSH packages and React are peers supplied by DSH.
-`web_fetch` is browserless by default; use `render: "agent-browser"` with an
-integer `waitMs` only for an explicit retry on a host that supplies the optional
-executable.
+`web_fetch` uses direct fetch by default and can explicitly use
+`render: "agent-browser"` with an integer `waitMs` on a host that supplies the
+optional executable.
 
-## Optional JavaScript rendering
+## Page-fetch backends
 
-`web fetch` is browserless by default. It uses Node `fetch`, `linkedom`, and
-Defuddle, never launches a subprocess for an ordinary fetch, and does not
-execute page JavaScript. If the response is an application shell, retry
-explicitly; there is no automatic browser fallback:
+`web fetch` has two backends. `fetch` (the default) uses Node `fetch`,
+`linkedom`, and Defuddle for direct HTML-to-Markdown extraction from static,
+SSR, and pre-rendered pages. `agent-browser` renders client-side pages through
+a separately installed host executable. Direct fetch is used by default; choose
+agent-browser explicitly when needed. The implementation never falls back
+automatically:
 
 ```bash
 web fetch https://example.com/app --render=agent-browser --wait=2000
@@ -114,10 +115,10 @@ web fetch https://example.com/app --render=agent-browser --wait=10000
 ```
 
 `--wait` is mandatory with `--render=agent-browser`, including `--wait=0`, and
-accepts only an integer from 0 through 30,000 milliseconds. Browserless fetches
-must not provide `--wait`. The same `render: "agent-browser"` and required
+accepts only an integer from 0 through 30,000 milliseconds. Direct `fetch`
+requests must not provide `--wait`. The same `render: "agent-browser"` and required
 `waitMs` fields are available on the MCP `fetch`, Pi `web_fetch`, and DSH
-`web_fetch` tools. A browserless failure may return the structured
+`web_fetch` tools. A direct-fetch failure may return the structured
 `javascript_rendering_may_be_required` hint with the 2,000 ms suggestion; the
 agent decides whether to retry with a longer wait or abandon the page.
 
@@ -133,8 +134,8 @@ agent-browser install
 `agent-browser install` manages its own browser runtime; Guion packages never
 run it, bundle it, or reuse browser credentials. A compatible executable must be
 directly runnable from `PATH` without a shell. The renderer is supported on
-macOS and Linux hosts. The three npm packages remain browserless and installable
-when `agent-browser` is absent.
+macOS and Linux hosts. Direct fetch remains available, and the three npm
+packages remain installable when `agent-browser` is absent.
 
 A rendered session is fresh and non-persistent. Before launch, the target must
 be an HTTP(S) public hostname or address. The browser allowlist then contains
diff --git a/packages/dsh-web/README.md b/packages/dsh-web/README.md
index be1ce5a..d064aac 100644
--- a/packages/dsh-web/README.md
+++ b/packages/dsh-web/README.md
@@ -18,11 +18,12 @@ settings expose only configured/source/writable metadata.
 
 The published package is a dual host/browser bundle. Its host and client
 artifacts, profile patch, and exact DSH `0.1.0-rc.8` peer contract are included
-in the npm package. Search, browserless page fetch, Context7 documentation,
-and Sourcegraph all run in-process through the bundled Guion Web core.
-`web_fetch` remains browserless by default; an agent may explicitly request
-`render: "agent-browser"` with a required integer `waitMs` from 0 through
-30,000 to render a client-side page through a host-installed `agent-browser`
+in the npm package. Search, direct page fetch, optional agent-browser rendering,
+Context7 documentation, and Sourcegraph all run in-process through the bundled
+Guion Web core. `web_fetch` has two page-fetch backends: direct fetch (the
+default) and explicit `render: "agent-browser"` with required `waitMs` (an
+integer from 0 through 30,000) for client-rendered pages through a host-installed
+`agent-browser`
 executable. To enable that optional capability, install
 [agent-browser](https://github.com/vercel-labs/agent-browser) separately with
 `npm install --global agent-browser` followed by `agent-browser install`. Its
diff --git a/packages/dsh-web/package.json b/packages/dsh-web/package.json
index 81292b9..ab6d47f 100644
--- a/packages/dsh-web/package.json
+++ b/packages/dsh-web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/dsh-web",
   "version": "0.1.0",
-  "description": "DeepSeek Harness rc.8 provider for browserless HTML-to-Markdown web research with optional host rendering.",
+  "description": "DeepSeek Harness rc.8 provider for web research with direct and optional agent-browser page-fetch backends.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"
diff --git a/packages/dsh-web/src/tools.ts b/packages/dsh-web/src/tools.ts
index 9da5f8f..7263531 100644
--- a/packages/dsh-web/src/tools.ts
+++ b/packages/dsh-web/src/tools.ts
@@ -53,7 +53,7 @@ const fetchParameters = {
   render: {
     type: "string",
     enum: ["fetch", "agent-browser"],
-    description: "Rendering backend; defaults to browserless fetch",
+    description: "Page-fetch backend; defaults to direct fetch",
   },
   waitMs: {
     type: "integer",
@@ -278,7 +278,7 @@ function webFetchTool(
     defineTool({
       name: "web_fetch",
       description:
-        "Fetch a browserless HTTP or HTTPS page as Markdown with heading-tree and section navigation; explicitly choose host-installed agent-browser rendering with required waitMs for client-rendered pages.",
+        "Fetch an HTTP or HTTPS page as Markdown with direct fetch or explicit host-installed agent-browser rendering; rendered fetch requires waitMs for client-rendered pages.",
       parameters: fetchParameters,
       output: fetchOutput,
       isConcurrencySafe: () => true,
diff --git a/packages/pi-web/package.json b/packages/pi-web/package.json
index 8606851..c920776 100644
--- a/packages/pi-web/package.json
+++ b/packages/pi-web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/pi-web",
   "version": "0.1.0",
-  "description": "Pi extension for browserless HTML-to-Markdown web research with optional host rendering.",
+  "description": "Pi extension for web research with direct and optional agent-browser page-fetch backends.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"
diff --git a/packages/pi-web/src/tool.ts b/packages/pi-web/src/tool.ts
index 5c58b9f..e53f3f1 100644
--- a/packages/pi-web/src/tool.ts
+++ b/packages/pi-web/src/tool.ts
@@ -59,7 +59,7 @@ export const webFetchSchema = Type.Union([
       ...fetchNavigationProperties,
       render: Type.Optional(
         StringEnum(["fetch"] as const, {
-          description: "Use browserless HTTP fetching (the default)",
+          description: "Use direct HTTP fetching (the default)",
         }),
       ),
     },
@@ -150,7 +150,7 @@ const SEARCH_PROMPT_GUIDELINES = [
 ];
 const FETCH_PROMPT_GUIDELINES = [
   "Use web_fetch to read a web page; large pages are truncated with a continuation notice, so follow up with tree or section_id to navigate.",
-  'Browserless fetching is the default. If the result says JavaScript rendering may be required, retry explicitly with render: "agent-browser" and waitMs from 0 through 30000 only when the host has agent-browser installed; there is no automatic fallback.',
+  'web_fetch has direct fetch (the default) and explicit agent-browser rendering for client-rendered pages. If rendering may be required, choose render: "agent-browser" with waitMs from 0 through 30000 only when the host has agent-browser installed; there is no automatic fallback.',
 ];
 const DOCS_PROMPT_GUIDELINES = [
   "Use web_docs with action resolve, then action fetch, to read library documentation instead of fetching documentation sites page by page.",
@@ -323,7 +323,7 @@ export function webFetchTool(dependencies: WebToolDependencies = {}) {
     name: "web_fetch",
     label: "Web fetch",
     description:
-      "Fetch and read an HTTP or HTTPS web page as Markdown, with heading-tree navigation. Browserless fetching is the default; explicitly choose render agent-browser with waitMs 0 through 30000 for JavaScript pages. Text output is limited to 2,000 lines or 50KB; truncated output is saved to a temporary file.",
+      "Fetch and read an HTTP or HTTPS web page as Markdown, with direct fetch or explicit agent-browser rendering for client-rendered pages. Rendered fetch requires waitMs 0 through 30000. Text output is limited to 2,000 lines or 50KB; truncated output is saved to a temporary file.",
     promptSnippet: "Fetch a web page with web_fetch",
     promptGuidelines: FETCH_PROMPT_GUIDELINES,
     parameters: webFetchSchema,
diff --git a/packages/web/package.json b/packages/web/package.json
index 2913bf2..b59b596 100644
--- a/packages/web/package.json
+++ b/packages/web/package.json
@@ -1,7 +1,7 @@
 {
   "name": "@guionai/web",
   "version": "0.1.0",
-  "description": "Browserless clean Markdown web research CLI and stdio MCP server with optional host rendering.",
+  "description": "Web research CLI and stdio MCP server with direct and optional agent-browser page-fetch backends.",
   "homepage": "https://github.com/guionai/web#readme",
   "bugs": {
     "url": "https://github.com/guionai/web/issues"
diff --git a/packages/web/src/mcp.ts b/packages/web/src/mcp.ts
index 4919a17..d9e5f24 100644
--- a/packages/web/src/mcp.ts
+++ b/packages/web/src/mcp.ts
@@ -75,7 +75,7 @@ const fetchInputSchema = schema<FetchToolInput>({
       type: "string",
       enum: ["fetch", "agent-browser"],
       default: "fetch",
-      description: "optional renderer; browserless fetch is the default",
+      description: "optional page-fetch backend; direct fetch is the default",
     },
     waitMs: {
       type: "integer",
@@ -244,7 +244,7 @@ export function createMcpServer(dependencies: McpDependencies): McpServer {
     "fetch",
     toolConfig(
       "Fetch a web page",
-      "Fetch a browserless web page as Markdown, or explicitly use host-installed agent-browser rendering with required waitMs.",
+      "Fetch a page as Markdown with direct fetch or explicit host-installed agent-browser rendering; rendered fetch requires waitMs.",
       fetchInputSchema,
       fetchOutputSchema,
     ),

From f960ce528ba0767dada3935aeee1a5cbd6cf79d4 Mon Sep 17 00:00:00 2001
From: Neil <bn0010100@gmail.com>
Date: Sun, 23 Aug 2026 15:26:29 +0800
Subject: [PATCH 4/4] fix(prompt): clarify fetch backend selection

---
 packages/dsh-web/src/tools.ts | 2 +-
 packages/pi-web/src/tool.ts   | 4 +++-
 packages/web/src/mcp.ts       | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/packages/dsh-web/src/tools.ts b/packages/dsh-web/src/tools.ts
index 7263531..564a920 100644
--- a/packages/dsh-web/src/tools.ts
+++ b/packages/dsh-web/src/tools.ts
@@ -278,7 +278,7 @@ function webFetchTool(
     defineTool({
       name: "web_fetch",
       description:
-        "Fetch an HTTP or HTTPS page as Markdown with direct fetch or explicit host-installed agent-browser rendering; rendered fetch requires waitMs for client-rendered pages.",
+        "Use direct fetch for static, SSR, and pre-rendered pages. For client-rendered or SPA pages, set render: agent-browser with required waitMs on a host that has agent-browser installed; there is no automatic fallback.",
       parameters: fetchParameters,
       output: fetchOutput,
       isConcurrencySafe: () => true,
diff --git a/packages/pi-web/src/tool.ts b/packages/pi-web/src/tool.ts
index e53f3f1..9f4d73d 100644
--- a/packages/pi-web/src/tool.ts
+++ b/packages/pi-web/src/tool.ts
@@ -150,7 +150,9 @@ const SEARCH_PROMPT_GUIDELINES = [
 ];
 const FETCH_PROMPT_GUIDELINES = [
   "Use web_fetch to read a web page; large pages are truncated with a continuation notice, so follow up with tree or section_id to navigate.",
-  'web_fetch has direct fetch (the default) and explicit agent-browser rendering for client-rendered pages. If rendering may be required, choose render: "agent-browser" with waitMs from 0 through 30000 only when the host has agent-browser installed; there is no automatic fallback.',
+  'web_fetch has two backends: omit render or use render: "fetch" for direct HTML-to-Markdown (the default for static, SSR, and pre-rendered pages).',
+  'For a client-rendered or SPA page, or after javascript_rendering_may_be_required, retry explicitly with render: "agent-browser" and waitMs: 2000 only when the host has agent-browser installed. Increase waitMs explicitly or abandon an incomplete page; there is no automatic fallback.',
+  "Never send waitMs with direct fetch. agent-browser is a host capability, not a package dependency.",
 ];
 const DOCS_PROMPT_GUIDELINES = [
   "Use web_docs with action resolve, then action fetch, to read library documentation instead of fetching documentation sites page by page.",
diff --git a/packages/web/src/mcp.ts b/packages/web/src/mcp.ts
index d9e5f24..4c7b634 100644
--- a/packages/web/src/mcp.ts
+++ b/packages/web/src/mcp.ts
@@ -244,7 +244,7 @@ export function createMcpServer(dependencies: McpDependencies): McpServer {
     "fetch",
     toolConfig(
       "Fetch a web page",
-      "Fetch a page as Markdown with direct fetch or explicit host-installed agent-browser rendering; rendered fetch requires waitMs.",
+      "Use direct fetch (omit render or set render: fetch) for static, SSR, and pre-rendered pages. For client-rendered or SPA pages, set render: agent-browser with required waitMs on a host that has agent-browser installed; there is no automatic fallback.",
       fetchInputSchema,
       fetchOutputSchema,
     ),