browser-pilot 0.0.15 → 0.0.17

package/README.md

@@ -12,6 +12,7 @@ Browser Pilot now teaches one workflow model:
 
 - inspect the page
 - act in the browser
+- review structured business state
 - record a manual workflow
 - trace behavior over time
 - exercise voice/media and browser conditions
@@ -26,7 +27,20 @@ bun add browser-pilot
 npm install browser-pilot
 ```
 
-For local Chrome:
+For local Chrome on Chrome 144+:
+
+```bash
+# 1. Start Chrome normally
+# 2. Open chrome://inspect/#remote-debugging
+# 3. Enable remote debugging, then run:
+bp connect
+```
+
+Tip: try plain `bp connect` first. Only add `--channel` or `--user-data-dir` if auto-discovery finds more than one eligible profile.
+
+Use `bp connect --channel beta` or `bp connect --user-data-dir <path>` when more than one Chrome profile is eligible.
+
+Legacy/manual fallback still works with a separate debug profile:
 
 ```bash
 /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
@@ -39,16 +53,22 @@ For local Chrome:
 | Job | Primary commands |
 | --- | --- |
 | Inspect page state | `snapshot`, `page`, `forms`, `text`, `targets`, `diagnose` |
+| Review structured state | `review` |
 | Act in the browser | `exec`, `run` |
 | Capture a human demo | `record` |
 | Investigate behavior over time | `trace` |
 | Exercise voice/media | `audio` |
 | Change browser conditions | `env` |
 
+Start with `bp --help` to see the routed command tree and `bp --version` to confirm the CLI build.
+
+Use `bp snapshot -i` to find clickable/fillable refs, `bp text` for long-form copy, `bp review` for structured business outcomes, and `bp diagnose` when targeting fails. Use `bp eval` only as an escape hatch.
+
 ## Golden path 1: automate a page
 
 ```bash
-bp connect --provider generic --name dev
+bp connect --name dev
+bp exec -s dev '{"action":"goto","url":"https://example.com"}'
 bp snapshot -i -s dev
 bp exec -s dev '[
   {"action":"fill","selector":"ref:e5","value":"user@example.com"},
@@ -59,6 +79,21 @@ bp exec -s dev '[
 
 Use `bp snapshot -i` first. Refs are the default targeting strategy.
 
+For reading or verification after actions:
+
+```bash
+bp text -s dev --selector main
+bp review -s dev --json
+bp diagnose -s dev 'submit'
+```
+
+Best practices from real usage:
+
+- `bp page` is a compact overview. It caches the refs it shows, but use `bp snapshot -i` when you need the full actionable list.
+- On commerce and content-heavy sites, scope reading with `bp text --selector main` to avoid nav, drawers, and footer noise.
+- `bp review` works best on confirmations, detail pages, tables, alerts, and key-value layouts. It is usually the wrong first read on catalog grids.
+- After `bp trace start`, begin with `bp trace summary --view session` before narrower views like `console` or `ws`.
+
 ## Golden path 2: capture a manual workflow and derive automation
 
 ```bash
@@ -74,7 +109,7 @@ Do not start by opening the raw artifact. Use `record summary`, `record inspect`
 ## Golden path 3: debug a realtime or voice session
 
 ```bash
-bp connect --provider generic --name realtime
+bp connect --name realtime
 bp trace start -s realtime --timeout 20000
 # reproduce the issue in the app
 bp trace summary -s realtime --view ws