From 6f3ab9898692ef4a20105ee8771a89b327abc255 Mon Sep 17 00:00:00 2001
From: Mohamed Boudra <boudra.moha@gmail.com>
Date: Wed, 8 Jul 2026 13:56:49 +0200
Subject: [PATCH] docs: restructure browser IA, add 'when to use' page

---
 public-docs/browser-tools.md |  2 +-
 public-docs/browser-when.md  | 21 +++++++++++++++++++++
 public-docs/browser.md       |  2 +-
 3 files changed, 23 insertions(+), 2 deletions(-)
 create mode 100644 public-docs/browser-when.md

diff --git a/public-docs/browser-tools.md b/public-docs/browser-tools.md
index 4d5b7a3f4..b97669e37 100644
--- a/public-docs/browser-tools.md
+++ b/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
 ---
 
diff --git a/public-docs/browser-when.md b/public-docs/browser-when.md
new file mode 100644
index 000000000..bc3600dc8
--- /dev/null
+++ b/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).
diff --git a/public-docs/browser.md b/public-docs/browser.md
index 4117730d2..6201069c7 100644
--- a/public-docs/browser.md
+++ b/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
 ---