docs: restructure browser IA, add 'when to use' page

public-docs/browser-tools.md

@@ -2,7 +2,7 @@
 title: Browser tools
 description: The browser_* MCP tools agents use to drive Paseo browser tabs.
 nav: Tools reference
-order: 36
+order: 37
 category: Browser
 ---
 

public-docs/browser-when.md

@@ -0,0 +1,21 @@
+---
+title: When to use the Paseo browser
+description: When to reach for Paseo's built-in browser instead of Playwright or agent-browser.
+nav: When to use
+order: 36
+category: Browser
+---
+
+# When to use
+
+Paseo gives agents a [real browser inside Paseo](/docs/browser). Standalone tools like Playwright or agent-browser give an agent its own browser in a separate process. They overlap, so which one?
+
+Use the Paseo browser when:
+
+- **You're running agents remotely and want to watch.** You see the same browser the agent is driving, live, from your phone or desktop — not a headless browser on a box you can't see.
+- **You want the browser inside Paseo.** It's a tab in the same session, not a separate agent window to manage.
+- **You don't want to set up extra tools.** It's built in — no separate MCP server or CLI to install and wire up.
+
+Reach for Playwright or agent-browser when the browser work stands on its own — headless CI runs, an existing test suite, or automation that isn't tied to an agent session in Paseo.
+
+The Paseo browser is [desktop only for now](/docs/browser).

public-docs/browser.md

@@ -1,7 +1,7 @@
 ---
 title: Browser automation
 description: Give agents a real browser inside Paseo to open pages, click, type, and verify their work.
-nav: Browser automation
+nav: Overview
 order: 35
 category: Browser
 ---