Revise Remote Browser Connection documentation for clarity and conciseness

Author: hannesrudolph

docs/advanced-usage/remote-browser-connection.md

@@ -1,124 +1,108 @@
 ---
 title: Remote Browser Connection
 description: Connect to an existing Chrome browser for containerized development, custom profiles, and remote workflows
-sidebar_position: 11
 ---
 
 # Remote Browser Connection
 
-## What Is Remote Browser Connection?
+Connect Roo to an existing Chrome browser instead of launching a new one. This feature bypasses Roo's default browser process creation, allowing Roo to work in containerized environments, with custom browser profiles, and across remote development workflows.
 
-Connect Roo to an existing Chrome browser instead of launching a new one. This powerful feature bypasses Roo's default browser process creation, enabling you to use Roo in containerized environments, with custom browser profiles, and across remote development workflows.
+> **Key Benefit:** Separates the browser process from the VS Code environment, solving common challenges in containerized development and remote workflows.
 
-> **Key Benefit:** Remote browser connection solves common challenges with containerized development and remote workflows by separating the browser process from the VS Code environment.
+## Use Cases
 
-### When To Use Remote Browser Connection
+- **DevContainers:** Connect from containerized VS Code to host Chrome browser
+- **Remote Development:** Use local Chrome with remote VS Code server
+- **Custom Chrome Profiles:** Use profiles with specific extensions and settings
+- **Shared Sessions:** Connect multiple Roo instances to one browser
 
-- **DevContainers:** Connect from containerized VS Code to a Chrome browser running on your host system
-- **Remote Development:** Use Chrome on a local development machine while working on a remote server
-- **Custom Chrome Profiles:** Leverage specific profiles with your preferred extensions and settings
-- **Shared Browser Sessions:** Allow multiple Roo instances to connect to the same browser session
+## Setup
 
-## Setting Up Remote Browser Connection
-
-To use the remote browser connection feature, you'll need to complete three simple steps: launch Chrome with remote debugging enabled, configure Roo settings, and (if using containers) set up network access.
+Connect to a remote browser in three steps:
 
 ### 1. Launch Chrome with Remote Debugging
 
-Launch Chrome with the remote debugging port enabled:
+Start Chrome with debugging enabled:
 
-**On macOS:**
+**macOS**:
 ```bash
 /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
 ```
 
-**On Windows:**
+**Windows**:
 ```bash
 "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\chrome-debug
 ```
 
-**On Linux:**
+**Linux**:
 ```bash
 google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
 ```
 
-> **Note:** The `--user-data-dir` parameter creates a separate Chrome profile that won't interfere with your regular browsing.
-
-### 2. Configuring Roo Settings
+> **Note:** The `--user-data-dir` parameter creates an isolated Chrome profile that doesn't affect your regular browsing.
 
-Once Chrome is running with remote debugging, configure Roo:
+### 2. Configure Roo Settings
 
-1. Open VS Code settings and search for "Roo browser"
-2. Enable "Use remote browser connection"
-3. Optionally enter a custom Chrome DevTools Protocol URL (for non-standard setups)
-4. Click "Test Connection" to verify connectivity
+To access these settings:
 
-![Remote Browser Connection UI](../../static/img/remote-browser-connection/remote-browser-connection.png)
+1. Click ⚙️ in the top-right corner
+2. Navigate to `Browser / Computer Use` settings
+3. Check "Enable browser tool"
+4. Check "Use remote browser connection"
+5. Enter custom Chrome DevTools Protocol URL (optional)
+6. Click "Test Connection" to verify
 
+<img src={require('@site/static/img/remote-browser-connection/remote-browser-connection.png').default} alt="Remote Browser Connection Settings" width="700" />
 
-### 3. Setting Up DevContainer Integration
+### 3. Configure DevContainer Network (If Applicable)
 
-If you're developing inside a container, you'll need to configure network access to reach the host machine:
+For container-based development, configure network access to reach the host machine:
 
 For VS Code devcontainers, add this network configuration to your `devcontainer.json`:
 
 ```json
-"runArgs": [
+{
+  "runArgs": [
     "--network=host"  // Enables access to host's Chrome instance
-]
+  ]
+}
 ```
 
-## Understanding How Connections Work
-
-After configuration, Roo establishes connections with Chrome using a sophisticated multi-step process to ensure reliability.
-
-When enabled, Roo connects to Chrome following this sequence:
-
-1. Attempts connection using your custom URL (if provided)
-2. If unsuccessful, runs auto-discovery on localhost, Docker containers, and local network
-3. Falls back to launching a local browser instance if all remote connection attempts fail
+## Connection Process
 
-## Troubleshooting Connection Problems
+Roo connects to Chrome in this sequence:
 
-If you encounter issues with the remote browser connection, here are solutions to the most common problems:
+1. Tries your custom URL (if provided)
+2. Runs auto-discovery on localhost, containers, and network
+3. Falls back to launching a local browser if all attempts fail
 
-- **Connection Failed:** Verify Chrome is running with the correct debugging flag and port
-- **Port Already in Use:** Change to an alternative port (e.g., `9333`) in both your Chrome launch command and Roo settings
-- **Network Issues:** Ensure your container/VM network settings allow access to the Chrome host machine
-- **Chrome Not Detected:** Check that firewall settings aren't blocking WebSocket connections
-- **Permission Errors:** Make sure you have the necessary permissions to access the specified `--user-data-dir` location
+## Troubleshooting
 
-## Exploring Advanced Capabilities
+| Problem | Solution |
+|---------|----------|
+| Connection Failed | Verify Chrome is running with `--remote-debugging-port=9222` |
+| Port Already in Use | Change to alternative port in both Chrome and Roo settings |
+| Network Issues | Check container/VM can access host machine |
+| Chrome Not Detected | Verify firewalls allow WebSocket connections |
+| Permission Errors | Ensure access to the specified `--user-data-dir` location |
 
-For power users and advanced scenarios, Roo's remote browser connection includes several sophisticated features that enhance flexibility and reliability.
+## Advanced Capabilities
 
-### How Auto-Discovery Works
+### Auto-Discovery
 
-When no specific URL is provided, Roo automatically locates Chrome instances by searching:
-- Standard debugging ports on localhost (9222, 9223)
-- Running containers with debugging-enabled Chrome
-- Network-accessible instances using discovery protocols
+When no URL is specified, Roo searches for Chrome instances across:
+- Standard debugging ports (9222, 9223) on localhost
+- Docker containers with debugging-enabled Chrome
+- Network-accessible instances via discovery protocols
 
-### Understanding Automatic Fallback
+### Automatic Fallback
 
-When remote connection attempts fail, Roo automatically launches a local browser instance, ensuring continuous workflow without manual intervention.
+When remote connections fail, Roo launches a local browser instance automatically to maintain workflow continuity.
 
-### Alternative Setup: Using Chrome DevTools
+### Alternative Setup via Chrome DevTools
 
-For situations where command-line configuration isn't ideal:
+For GUI-based configuration:
 
 1. Open `chrome://inspect` in Chrome
-2. Click "Configure" next to "Discover network targets"
+2. Click "Configure" beside "Discover network targets"
 3. Add `localhost:9222` and click "Done"
-
-## Related Features
-
-Remote browser connection works seamlessly with other Roo features:
-
-- **[Custom Modes](custom-modes)**: Create specialized browser-based modes
-- **[Code Actions](code-actions)**: Execute browser-based actions against remote instances
-- **[Large Projects](large-projects)**: Improve performance by separating browser processes
-
-## Summary
-
-Remote browser connection provides flexibility for containerized development, custom browser profiles, and remote workflows. By following the setup instructions in this guide, you can leverage the power of an existing Chrome instance for your Roo sessions, making your development process more efficient and adaptable to various environments.