docs: add websearch guides

services/www/src/docs/content/config.mdx

@@ -271,8 +271,8 @@ Set the maximum number of lines and bytes retained from a tool result.
 
 ### Search
 
-Use `"random"` to randomly choose a search provider for each session and keep using it until it
-returns HTTP 429. OpenCode then retries the query with another available provider.
+Choose how OpenCode searches the web. Use `"random"` to select an available
+provider automatically.
 
 ```jsonc
 {
@@ -282,12 +282,8 @@ returns HTTP 429. OpenCode then retries the query with another available provide
 }
 ```
 
-- Rate-limited providers cool down for `Retry-After`, or 60 seconds if it is missing or invalid.
-- When every provider is cooling down, the search fails without waiting.
-- Each session remembers its preferred provider; cooldowns are shared within a Location.
-- State is kept in memory. Moving a session or restarting its Location services resets its preference.
-- API and plugin queries without session context share a Location-level preference.
-- Set `provider` to a provider ID to disable automatic switching, or set `websearch` to `false` to disable search.
+See the [websearch guide](/websearch) for providers, credentials, selection,
+rate limits, and disabling search.
 
 ### MCP
 

services/www/src/docs/content/console/websearch.mdx

@@ -0,0 +1,44 @@
+---
+title: "Websearch"
+description: "Hosted websearch for OpenCode through Console."
+---
+
+Console provides hosted Websearch to connected OpenCode v2 users. A workspace owner or admin enables it once for the workspace, without giving members a separate search provider key.
+
+Each successful search costs **$0.01** and counts toward the workspace balance and member spending limits.
+
+## Enable
+
+1. Sign in to the [Console](https://console.opencode.ai) as a workspace owner or admin.
+2. Open **Settings** > **General**.
+3. Turn on **Hosted web search**.
+
+Each member then connects OpenCode to the workspace with `/connect`.
+
+```text
+/connect
+```
+
+OpenCode loads **OpenCode Web Search** from the workspace's managed configuration. Members do not need to set `websearch.provider` or add a provider API key.
+
+## Search
+
+Ask OpenCode for current information in a prompt. Searches run from OpenCode rather than from an interactive page in Console.
+
+```text
+Find the latest Bun release and summarize the changes with source links.
+```
+
+The hosted provider searches the public web and returns up to eight results. OpenCode uses the results to answer the prompt and cite sources.
+
+See the [Websearch guide](/websearch) to configure permissions or disable the tool.
+
+## Billing
+
+Console charges **$0.01** after a search returns a valid result set. Failed and rate-limited searches are not charged.
+
+Websearch appears separately from model usage in **Usage**, **My Activity**, member activity, invoices, and CSV exports. Workspace and member monthly spending limits include Websearch charges.
+
+## Privacy
+
+Hosted Websearch has zero data retention. Console and its hosted search provider process each query and its results without storing their contents.

services/www/src/docs/content/websearch.mdx

@@ -0,0 +1,94 @@
+---
+title: "Websearch"
+---
+
+Ask OpenCode for current information and it can search the web, read the results, and include source links in its response.
+
+```text
+Find the latest Bun release and summarize the changes.
+```
+
+The first search asks you to allow web search and select a provider. OpenCode remembers your choice for later sessions.
+
+## Providers
+
+OpenCode includes four search providers:
+
+| Provider | ID | Environment variable |
+| --- | --- | --- |
+| Exa | `exa` | `EXA_API_KEY` |
+| Firecrawl | `firecrawl` | `FIRECRAWL_API_KEY` |
+| Parallel | `parallel` | `PARALLEL_API_KEY` |
+| Tavily | `tavily` | `TAVILY_API_KEY` |
+
+Connect an account from the TUI with `/connect`, or set the provider's environment variable before starting OpenCode.
+
+```bash
+$ TAVILY_API_KEY=your-key opencode2
+```
+
+## Selection
+
+Set a provider in `opencode.jsonc` to skip the selection prompt.
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "websearch": {
+    "provider": "tavily",
+  },
+}
+```
+
+Use `"random"` to choose an available provider automatically. Each session keeps using its selected provider until that provider is rate limited.
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "websearch": {
+    "provider": "random",
+  },
+}
+```
+
+## Limits
+
+When a provider returns HTTP 429, random selection retries the search with another available provider. The rate-limited provider waits for its `Retry-After` period, or 60 seconds when the response does not include a valid period.
+
+```text
+Exa returns HTTP 429
+→ Exa enters cooldown
+→ OpenCode retries with another provider
+```
+
+If every provider is cooling down, the search fails immediately. Moving a session or restarting its server clears its remembered provider; cooldowns are shared by sessions in the same workspace.
+
+## Permissions
+
+Web searches use the `websearch` permission action and the search query as the resource. Ask before searches that are not explicitly allowed.
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "permissions": [
+    {
+      "action": "websearch",
+      "resource": "*",
+      "effect": "ask",
+    },
+  ],
+}
+```
+
+See [Permissions](/permissions) for rule order and matching.
+
+## Disable
+
+Set `websearch` to `false` to remove the web search tool from model requests.
+
+```jsonc title="opencode.jsonc"
+{
+  "$schema": "https://opencode.ai/config.json",
+  "websearch": false,
+}
+```

services/www/src/docs/lib/navigation.ts

@@ -37,6 +37,7 @@ export const docsSections: DocsSection[] = [
           { title: "Commands", slug: "commands" },
           { title: "Plugins", slug: "plugins" },
           { title: "Providers", slug: "providers" },
+          { title: "Websearch", slug: "websearch" },
           { title: "Snapshots", slug: "snapshots" },
           { title: "Compaction", slug: "compaction" },
           { title: "Formatters", slug: "formatters" },
@@ -136,6 +137,7 @@ export const docsSections: DocsSection[] = [
         items: [
           { title: "Intro", slug: "console" },
           { title: "Models", slug: "console/models" },
+          { title: "Websearch", slug: "console/websearch" },
           { title: "Go", slug: "console/go" },
         ],
       },