From ec26ad81be908aec06d03bde0b352cf5d5987edb Mon Sep 17 00:00:00 2001
From: Julian Engel <julian@codeero.com>
Date: Mon, 5 Jan 2026 15:16:00 +0000
Subject: [PATCH] docs: add cross-references to Linux browser troubleshooting

---
 docs/browser.md         |  4 ++++
 docs/troubleshooting.md | 23 +++++++++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/docs/browser.md b/docs/browser.md
index fe00ac91d..5684d7c17 100644
--- a/docs/browser.md
+++ b/docs/browser.md
@@ -287,3 +287,7 @@ Notes:
 - Sharing the user's logged-in Chrome sessions automatically.
 - General-purpose web scraping; this is primarily for "close-the-loop" verification
   and interaction.
+
+## Troubleshooting
+
+For Linux-specific issues (especially Ubuntu with snap Chromium), see [browser-linux-troubleshooting.md](./browser-linux-troubleshooting.md).
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index baaac0e7a..357d8b5ee 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -225,3 +225,26 @@ clawdbot gateway        # start the Gateway again
 *"Have you tried turning it off and on again?"* — Every IT person ever
 
 🦞🔧
+
+### Browser Not Starting (Linux)
+
+If you see `"Failed to start Chrome CDP on port 18800"`:
+
+**Most likely cause:** Snap-packaged Chromium on Ubuntu.
+
+**Quick fix:** Install Google Chrome instead:
+```bash
+wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
+sudo dpkg -i google-chrome-stable_current_amd64.deb
+```
+
+Then set in config:
+```json
+{
+  "browser": {
+    "executablePath": "/usr/bin/google-chrome-stable"
+  }
+}
+```
+
+**Full guide:** See [browser-linux-troubleshooting.md](./browser-linux-troubleshooting.md)