From 1fe8df85cbb9d4bcd7bb9278ac87add337901c28 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 15 Jan 2026 05:20:56 +0000
Subject: [PATCH] docs: clarify extension tab attachment

---
 docs/start/faq.md              |  1 +
 docs/tools/browser.md          |  2 +-
 docs/tools/chrome-extension.md | 16 ++++++++++++++++
 3 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/docs/start/faq.md b/docs/start/faq.md
index cbffaba0d..543daa482 100644
--- a/docs/start/faq.md
+++ b/docs/start/faq.md
@@ -414,6 +414,7 @@ Then Chrome → `chrome://extensions` → enable “Developer mode” → “Loa
 Full guide (including remote Gateway via Tailscale + security notes): [Chrome extension](/tools/chrome-extension)
 
 If the Gateway runs on the same machine as Chrome (default setup), you usually **do not** need `clawdbot browser serve`.
+You still need to click the extension button on the tab you want to control (it doesn’t auto-attach).
 
 ## Sandboxing and memory
 
diff --git a/docs/tools/browser.md b/docs/tools/browser.md
index 7bb9dc79b..3d8183ef6 100644
--- a/docs/tools/browser.md
+++ b/docs/tools/browser.md
@@ -218,7 +218,7 @@ Full guide: [Chrome extension](/tools/chrome-extension)
 Flow:
 - You run a **browser control server** (Gateway on the same machine, or `clawdbot browser serve`).
 - A local **relay server** listens at a loopback `cdpUrl` (default: `http://127.0.0.1:18792`).
-- You click the **Clawdbot Browser Relay** extension icon on a tab to attach.
+- You click the **Clawdbot Browser Relay** extension icon on a tab to attach (it does not auto-attach).
 - The agent controls that tab via the normal `browser` tool, by selecting the right profile.
 
 If the Gateway runs on the same machine as Chrome (default setup), you usually **do not** need `clawdbot browser serve`.
diff --git a/docs/tools/chrome-extension.md b/docs/tools/chrome-extension.md
index 6eb5a7dc2..c96a45a78 100644
--- a/docs/tools/chrome-extension.md
+++ b/docs/tools/chrome-extension.md
@@ -70,6 +70,22 @@ Then target it:
   - Badge shows `ON` when attached.
 - Click again to detach.
 
+## Which tab does it control?
+
+- It does **not** automatically control “whatever tab you’re looking at”.
+- It controls **only the tab(s) you explicitly attached** by clicking the toolbar button.
+- To switch: open the other tab and click the extension icon there.
+
+## Badge + common errors
+
+- `ON`: attached; Clawdbot can drive that tab.
+- `…`: connecting to the local relay.
+- `!`: relay not reachable (most common: browser relay server isn’t running on this machine).
+
+If you see `!`:
+- Make sure the Gateway is running locally (default setup), or run `clawdbot browser serve` on this machine (remote gateway setup).
+- Open the extension Options page; it shows whether the relay is reachable.
+
 ## Do I need `clawdbot browser serve`?
 
 ### Local Gateway (same machine as Chrome) — usually **no**