docs(browser): browse env local auto-discovery

skills/browser/REFERENCE.md

@@ -272,16 +272,23 @@ Check whether the daemon is running, its connection details, and current environ
 browse status
 ```
 
-#### `env [local|remote]`
+#### `env [local|remote] [cdpTarget] [--isolated]`
 
 Show or switch the browser environment. Without arguments, prints the current environment. With an argument, stops the running daemon and restarts in the specified environment. The switch is sticky — subsequent commands stay in the chosen environment until you switch again or run `browse stop`.
 
+`browse env local` auto-discovers an already-running Chrome with remote debugging enabled (scans `DevToolsActivePort` files and probes common ports like 9222). Falls back to launching an isolated browser if no debuggable Chrome is found.
+
 ```bash
 browse env                               # print current environment
-browse env local                         # switch to local Chrome
+browse env local                         # auto-discover local Chrome, fallback to isolated
+browse env local --isolated              # force clean isolated browser (skip discovery)
+browse env local 9222                    # attach to CDP target on port 9222
+browse env local ws://host:port/path     # attach to explicit CDP WebSocket URL
 browse env remote                        # switch to Browserbase (requires API keys)
 ```
 
+`browse status` reports `localStrategy`, `localSource`, `resolvedCdpUrl`, and `fallbackReason` when in local mode.
+
 #### `newpage [url]`
 
 Create a new tab, optionally navigating to a URL.

skills/browser/SKILL.md

@@ -33,7 +33,9 @@ which browse || npm install -g @browserbasehq/browse-cli
 The CLI automatically selects between local and remote browser environments based on available configuration:
 
 ### Local mode (default)
-- Uses local Chrome — no API keys needed
+- Auto-discovers an already-running Chrome with remote debugging enabled and attaches to it
+- Falls back to launching an isolated Chrome if no debuggable browser is found
+- No API keys needed
 - Best for: development, simple pages, trusted sites with no bot protection
 
 ### Remote mode (Browserbase)
@@ -92,9 +94,11 @@ browse wait <type> [arg]                 # Wait for: load, selector, timeout
 ### Session management
 ```bash
 browse stop                              # Stop the browser daemon
-browse status                            # Check daemon status (includes env)
+browse status                            # Check daemon status (includes env and local strategy)
 browse env                               # Show current environment (local or remote)
-browse env local                         # Switch to local Chrome
+browse env local                         # Auto-discover local Chrome, fallback to isolated
+browse env local --isolated              # Force clean isolated browser (skip auto-discovery)
+browse env local <port|url>              # Attach to specific CDP target
 browse env remote                        # Switch to Browserbase (requires API keys)
 browse pages                             # List all open tabs
 browse tab_switch <index>                # Switch to tab by index
@@ -154,10 +158,14 @@ Don't switch for simple sites (docs, wikis, public APIs, localhost).
 
 ```bash
 browse env remote            # switch to Browserbase
-browse env local             # switch back to local Chrome
+browse env local             # switch back to local (auto-discovers existing Chrome)
+browse env local --isolated  # force a clean isolated browser
+browse env local 9222        # attach to Chrome on specific port
 ```
 
 The switch is sticky until you run `browse stop` or switch again.
 
+`browse env local` auto-discovers a running Chrome with remote debugging enabled (via `DevToolsActivePort` files and common port probing). If no debuggable Chrome is found, it falls back to launching an isolated browser. Use `--isolated` to skip auto-discovery and always get a clean browser.
+
 For detailed examples, see [EXAMPLES.md](EXAMPLES.md).
 For API reference, see [REFERENCE.md](REFERENCE.md).