docs(skills): polish BROWSER.md Way 1 and Way 2 from harness install.md

[Alezander9]

What

Bring canonical Way 1 / Way 2 connection facts from browser-use/browser-harness:install.md into BROWSER.md, translated to the session.connect() API. Surfaced during v0.1.0 Windows testing where the agent was failing to connect locally with both Way 1 and Way 2.

Why

The previous BROWSER.md condensed the harness's connection reference down to a few sentences each, dropping facts that the harness team treats as the source of truth — including at least one instruction that was wrong (ws://127.0.0.1:9222/devtools/browser without the UUID suffix does not work on Chrome's browser-level endpoint). The harness install.md is the canonical reference and is held to a verifiable-against-Chrome-source standard; the agent should be reading from that quality of doc, not a lossy paraphrase.

Way 1 changes

• Explicit per-profile + sticky framing for the chrome://inspect/#remote-debugging checkbox. Tick once, persists across every future Chrome launch of that profile.
• Chrome 144+ popup-may-reappear caveat with concrete causes (daemon restart, browser restart, time elapsed, "Allow for N hours"). Tells the agent to expect this rather than treating a 403 on a previously-working connection as a hard failure.
• Failure-mode list mapping the two distinct error strings ("No running browser with remote debugging detected" vs. "403 / permission / WS closed before open") to the right user instruction.

Way 2 changes

• Per-platform launch command (Linux, macOS, Windows cmd.exe, Windows PowerShell) so the agent can pick the right shell on the user's OS without guessing.
• Default profileDir-based connect (which reads DevToolsActivePort) instead of the wsUrl form, since profileDir works on every Chrome version including 144+ which doesn't serve /json/version.
• Two precisions verbatim from harness install.md:
  1. --user-data-dir must not be Chrome's platform default; Chrome 136+ silently no-ops the port flag in that case. Platform-default paths listed for all three OSes.
  2. Cookie encryption is bound to the original profile dir; copying the user's profile to a custom dir transfers bookmarks and extensions but not logins. Explicitly tells the agent to fall back to Way 1 instead of attempting the copy.
• Fix the broken wsUrl example: bare ws://host:port/devtools/browser (no UUID suffix) does not work — Chrome's browser-level endpoint includes a per-process UUID. The wsUrl form is now scoped as an escape hatch with a working example.

Top of Connecting

The decision rule now appears before the three Way blocks: Way 1 for real-browser tasks, Way 2 for unattended automation, cloud opt-in only.

Verification

• bun run typecheck clean (no code touched).
• bun test from packages/bcode-browser/: 8 pass + 5 chrome-gated skip.
• End-to-end resolveSkillsDir against tmpdir: zero literal {{SKILLS_DIR}} matches; new content survives substitution and lands intact (verified "cookie encrypted", "Chrome 144+ popup", "per-process UUID" markers in materialized output).

+32 lines net (BROWSER.md 162 -> 194). Single-file change, skills documentation only.

Source

https://github.com/browser-use/browser-harness/blob/main/install.md (Browser connection reference section).

[cubic-dev-ai]

No issues found across 1 file