feat: add web search hint to onboarding

docs/start/wizard.md

@@ -24,6 +24,10 @@ Follow‑up reconfiguration:
 clawdbot configure
 ```
 
+Recommended: set up a Brave Search API key so the agent can use `web_search`
+(`web_fetch` works without a key). Set `BRAVE_API_KEY` or
+`tools.web.search.apiKey`. Docs: [Web tools](/tools/web).
+
 ## QuickStart vs Advanced
 
 The wizard starts with **QuickStart** (defaults) vs **Advanced** (full control).

docs/tools/web.md

@@ -24,6 +24,15 @@ These are **not** browser automation. For JS-heavy sites or logins, use the
   (HTML → markdown/text). It does **not** execute JavaScript.
 - In sandboxed sessions, `web_fetch` is enabled automatically (unless explicitly disabled).
 
+## Getting a Brave API key
+
+1) Create a Brave Search API account at https://brave.com/search/api/
+2) Generate an API key in the dashboard.
+3) Set `BRAVE_API_KEY` in your environment or paste it into `tools.web.search.apiKey`.
+
+Brave provides a free tier plus paid plans; check the Brave API portal for the
+current limits and pricing.
+
 ## web_search
 
 Search the web with Brave’s API.
@@ -92,12 +101,3 @@ Notes:
 - `web_fetch` is best-effort extraction; some sites will need the browser tool.
 - Responses are cached (default 15 minutes) to reduce repeated fetches.
 - If you use tool profiles/allowlists, add `web_search`/`web_fetch` or `group:web`.
-
-## Getting a Brave API key
-
-1) Create a Brave Search API account at https://brave.com/search/api/
-2) Generate an API key in the dashboard.
-3) Set `BRAVE_API_KEY` in your environment or paste it into `tools.web.search.apiKey`.
-
-Brave provides a free tier plus paid plans; check the Brave API portal for the
-current limits and pricing.

src/commands/onboard-non-interactive/local.ts

@@ -110,4 +110,10 @@ export async function runNonInteractiveOnboardingLocal(params: {
     skipSkills: Boolean(opts.skipSkills),
     skipHealth: Boolean(opts.skipHealth),
   });
+
+  if (!opts.json) {
+    runtime.log(
+      "Tip: set BRAVE_API_KEY (or tools.web.search.apiKey) to enable web_search. Docs: https://docs.clawd.bot/tools/web",
+    );
+  }
 }

src/commands/onboard-non-interactive/remote.ts

@@ -44,5 +44,8 @@ export async function runNonInteractiveOnboardingRemote(params: {
   } else {
     runtime.log(`Remote gateway: ${remoteUrl}`);
     runtime.log(`Auth: ${payload.auth}`);
+    runtime.log(
+      "Tip: set BRAVE_API_KEY (or tools.web.search.apiKey) to enable web_search. Docs: https://docs.clawd.bot/tools/web",
+    );
   }
 }

src/wizard/onboarding.ts

@@ -75,6 +75,14 @@ export async function runOnboardingWizard(
 ) {
   printWizardHeader(runtime);
   await prompter.intro("Clawdbot onboarding");
+  await prompter.note(
+    [
+      "Recommended: get a Brave Search API key to enable web_search.",
+      "Set BRAVE_API_KEY or tools.web.search.apiKey.",
+      "Docs: https://docs.clawd.bot/tools/web",
+    ].join("\n"),
+    "Web search (optional)",
+  );
   await requireRiskAcknowledgement({ opts, prompter });
 
   const snapshot = await readConfigFileSnapshot();