[UX] Chrome remote debugging is a hidden prerequisite — not mentioned in README Quick Start

[ythx-101]

Summary

The README Quick Start does not mention that Chrome must be launched with remote debugging enabled before running browser-harness. First-time users encounter a confusing error that only hints at the requirement indirectly.

Current Flow

1. User follows README: installs uv → clones repo → uv tool install -e .
2. Runs browser-harness → error listing Chrome paths → must infer that remote debugging is needed
3. Searches chrome://inspect/#remote-debugging — not mentioned in Quick Start

The only mention of "enable remote debugging" is inside a screenshot in the setup prompt section, not Quick Start.

Suggested Fix

Add to Quick Start:

3. Launch Chrome with remote debugging enabled:
   # macOS
   open -a 'Google Chrome' --args --remote-debugging-port=9222
   # Linux
   google-chrome --remote-debugging-port=9222

   Then visit chrome://inspect/#remote-debugging and enable "Discover network targets"

Notes

• The error message itself is good — it lists which Chrome paths were checked and mentions chrome://inspect. But Quick Start users shouldn't need an error to find a prerequisite.
• uv is also an unlisted prerequisite (separate issue worth filing).

---

Reported by test-factory walk-through audit, 2026-04-20

[honor2030]

I took a pass over the current docs before opening a PR.

Current state on main:

• README.md now has a setup-prompt flow that sends agents to install.md and shows chrome://inspect/#remote-debugging with the checkbox screenshot.
• install.md now has the more complete source of truth under Browser connection reference / First time setup, including the two local-browser paths:
  • Way 1: use the running real Chrome profile and tick the chrome://inspect/#remote-debugging checkbox.
  • Way 2: launch Chrome with --remote-debugging-port=9222 --user-data-dir=<non-default path> and set BU_CDP_URL=http://127.0.0.1:9222.

I think the original issue is still partially valid for readers who do a manual install from the README rather than delegating setup to an agent: the README points at the setup flow, but it still does not have a small, explicit “first run requires a browser connection” note in the main path.

Before opening a tiny docs PR, I want to confirm the desired scope. Would you prefer a short README addition that keeps install.md as the canonical reference, roughly like this?

### Manual first run

After installing `browser-harness`, connect a browser before the first command:

- For your normal Chrome profile, open `chrome://inspect/#remote-debugging` in Chrome and tick “Allow remote debugging for this browser instance”.
- For an isolated automation profile, launch Chrome with `--remote-debugging-port=9222 --user-data-dir=<non-default path>` and run `browser-harness` with `BU_CDP_URL=http://127.0.0.1:9222`.

See `install.md#browser-connection-reference` for the full setup and troubleshooting flow.

I would avoid adding the original bare --remote-debugging-port=9222 snippet by itself, because the current install.md calls out the Chrome 136+ behavior where that flag is no-op’d against the default profile. Linking to the two-path explanation should avoid making the README quick start misleading while still surfacing the hidden prerequisite.

[ythx-101]

Yes, I’d prefer the short README note that keeps install.md as the canonical reference.

The important bit for first-time/manual users is making the hidden prerequisite visible in the main path: before running browser-harness, they need a connected browser.

I agree we should avoid adding the bare --remote-debugging-port=9222 snippet by itself. With the Chrome 136+ default-profile behavior, the two-path explanation is safer:

• normal Chrome profile → chrome://inspect/#remote-debugging + allow remote debugging
• isolated automation profile → --remote-debugging-port=9222 --user-data-dir=<non-default path> + BU_CDP_URL=http://127.0.0.1:9222

So your proposed small “Manual first run” README section sounds right to me. Thanks for checking the current docs before opening the PR.