Skip to content

Open-source Python library for AI browser agents, plus Browser Use Cloud: stealth browsers and a hosted agent API.

add qa skill

Shawn Pana151a56279817
diff --git a/skills/qa/SKILL.md b/skills/qa/SKILL.md
new file mode 100644
index 000000000..1f1ef2864
--- /dev/null
+++ b/skills/qa/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: qa
+description: QA-test a website or web app and return a 1-5 quality score (5 = flawless, 1 = broken) with evidence. Use when the user wants to test, QA, evaluate, score, or "check how good" a site, page, flow, or app — including a local dev server (e.g. "qa test localhost:5173", "does the checkout work?", "rate this landing page"). Drives a real Browser Use cloud browser, tunneling localhost automatically.
+allowed-tools: Bash, Read, Task
+---
+
+# QA
+
+Drive a website with a real browser, judge how well it does the thing the user asked about, and return a **score from 1 (broken) to 5 (excellent)** with evidence. The deliverable is a verdict, not a screenshot dump.
+
+## Inputs
+
+From the user's invocation (the text after `/qa`, or their message):
+- **Target** — a URL (`https://…`) or a local dev server (`localhost:5173`, `:3000`, "the app on 5173"). **Required** — if absent, ask for it before doing anything else.
+- **What to test** (optional) — a flow or focus ("the signup", "search + filters"). If omitted, test the most obvious happy path and say so in the report.
+
+## Can you see images? (decide this first)
+
+This skill's verdict is **visual** — you judge the app by looking at screenshots. So before anything else, check whether *you* — the agent running this skill — can actually see images:
+
+- **You have vision (multimodal / image input)** → you can judge screenshots yourself. Continue to "Single flow vs. fan-out" below and choose by scale.
+- **You have no vision (text-only model, no image support)** → you **cannot** judge screenshots, and neither can same-model subagents you'd spawn. You **must** hand the visual judgment to **Browser Use v2 cloud agents**, whose own LLM looks at the page server-side and returns a text verdict (`judge` pass/fail + a 1–5 `structuredOutput`). Use v2 for **every** flow — even a single one — per `references/browser-use-v2.md`. Do **not** drive `browser-harness` yourself to read screenshots, and do **not** fan out to your own (equally blind) subagents. The single-flow-vs-fan-out choice below does not apply to you — it's v2 either way.
+
+If you're unsure whether you can see images, assume you can't and use v2.
+
+## Single flow vs. fan-out (only if you can see images)
+
+**Scale the approach to the ask:**
+
+- **Testing one flow / one thing?** Don't bother with subagents — **drive `browser-harness` directly** yourself, following `references/methodology.md`. That's the right, lowest-overhead tool for a single test, and it's how the rest of this skill works.
+- **Testing many flows / a lot at once?** **Fan out to subagents — one per flow — so they run in parallel.** Here the user has a choice of subagent type (ask if unclear; **recommend v2**):
+ - **Browser Use v2 cloud agents — recommended.** Each flow becomes an autonomous v2 task with **`judge`** (pass/fail) + **`structuredOutput`** (1–5 score), running server-side and **in parallel**, returning step-by-step screenshot evidence. **Spends Browser Use credits** (~$0.01/task + ~$0.006/step + $0.02/hr browser). Per-task flow + how to fan out: `references/browser-use-v2.md`.
+ - **Your harness's built-in subagents** — spawn Claude Code subagents (the Agent tool), each driving `browser-harness` through `references/methodology.md`. No Browser Use *task* credits; uses your agent's own usage.
+
+Rule of thumb (**vision agents only** — text-only agents use v2 for everything, see above): **one flow → browser-harness directly; many flows → subagents (v2 recommended).** Either way `browser-harness` is required — as the direct driver, the subagent driver, the v2 key store, and the localhost tunnel.
+
+## Dependency: browser-harness (required)
+
+This skill runs the test through **browser-harness** — a separate plugin + CLI. It is not optional; QA must run on a real Browser Use cloud browser, never the user's local Chrome.
+
+**Before anything else, verify it's available:**
+
+```bash
+command -v browser-harness && browser-harness <<'PY'
+print("browser-harness OK")
+PY
+```
+
+If `browser-harness` is **not** on `PATH`, stop and tell the user to install it, then resume:
+- Plugin: install the `browser-harness` plugin for your agent — `claude plugin install browser-harness@browser-use` (Claude Code) or `codex plugin add browser-harness@browser-use` (Codex)
+- CLI (one-time): see the browser-harness skill's `references/install.md` (it's a `uv`/pip install of the `browser-harness` package). Repo: https://github.com/browser-use/browser-harness
+
+Do not attempt to QA with anything other than browser-harness + a cloud browser.
+
+## Procedure
+
+1. **Confirm the target is reachable** (`curl -s -o /dev/null -w "%{http_code}" <url>`), and identify what the app is (title, README) so you can frame a sensible test task.
+2. **Run it** — first apply the vision gate from "Can you see images?" above:
+ - **No vision (text-only)?** → use **v2 cloud agents for every flow** (one v2 task per flow, each with `judge` + a 1–5 `structuredOutput`), per `references/browser-use-v2.md`. Skip the single-flow/subagent split below — it's v2 regardless of scale. Tunnel a `localhost` target and pass the public `startUrl`.
+ - **Vision, one flow** → drive **browser-harness directly** per `references/methodology.md`: resolve the key, tunnel localhost, and run the test loop with the field-tested gotchas (host-header rewrite, proxy-off, per-tab interstitial header, CORS-pinned APIs).
+ - **Vision, many flows → fan out, one subagent per flow:**
+ - **v2 agents (recommended)** → per `references/browser-use-v2.md`, create one task per flow (each with `judge` + a 1–5 `structuredOutput` schema), poll them all, and collect the verdicts. A `localhost` target still needs a tunnel (the cloud agent can't reach localhost) — tunnel it and pass the public `startUrl`.
+ - **Claude subagents** → spawn one Agent per flow, each following `references/methodology.md` on browser-harness.
+
+ *Whenever you use the v2 backend (either the no-vision case or the recommended fan-out): as each task is created, open its dashboard thread `https://cloud.browser-use.com/thread/{sessionId}` (the **session id** from the create response — not the task id) in the user's local Chrome so they can watch the agent run — the reference's `open_local(...)` helper does this. Always print the URL too.*
+3. **Tear down** what you started — only the **one-flow / Claude** paths have anything to stop (cloud browser + tunnel). A v2 task on a public URL has nothing to tear down (its one-off session auto-closes).
+4. **Return the verdict**: lead with `Score: N/5`, then task, result, what worked, issues (tagged), edge cases, and evidence — per the rubric and output format in `references/methodology.md`. **Fanning out?** Give a per-flow `Score: N/5` line and an **overall score that reflects the weakest critical path** (don't average a broken flow up because others passed).
+
+Scale effort to the ask: a quick "does X work?" is a few interactions and one score; "thoroughly QA this" warrants more flows and edge cases. Keep the verdict honest, specific, and reproducible.
diff --git a/skills/qa/references/browser-use-v2.md b/skills/qa/references/browser-use-v2.md
new file mode 100644
index 000000000..273b593d7
--- /dev/null
+++ b/skills/qa/references/browser-use-v2.md
@@ -0,0 +1,213 @@
+# Browser Use v2 agent backend (recommended for QA)
+
+Run the QA test as an autonomous **Browser Use cloud agent** instead of driving browser-harness
+step by step. It's purpose-built for QA: a **judge** evaluates pass/fail against expected
+behavior, and **structured output** forces the 1–5 score. It runs server-side, parallelizes, and
+returns step-by-step evidence (screenshots + actions).
+
+**Cost / credits:** the v2 agent spends Browser Use credits — about **$0.01 per task + ~$0.006 per
+step (LLM) + $0.02/hr browser**, drawn from the account's monthly allowance. (The Claude-subagent
+backend in `methodology.md` spends no Browser Use *task* credits.) Recommend v2 for real QA; fall
+back to the Claude subagent to avoid credits.
+
+> Note: the docs label the v2 API "legacy" and steer new projects to v3 — but the **`judge` +
+> structured-output** evaluation features QA needs live on v2 (`POST /api/v2/tasks`), so that's
+> what this backend uses.
+
+## The endpoints
+
+- **Create:** `POST https://api.browser-use.com/api/v2/tasks` → `202 {id, sessionId}`
+- **Poll:** `GET https://api.browser-use.com/api/v2/tasks/{id}` → `status` ∈ `created → started →
+ finished | failed | stopped`, plus `output`, `judgeVerdict`, `judgement`, `steps[]`, `cost`.
+- Auth header on both: `X-Browser-Use-API-Key`.
+
+## Key resolution — via browser-harness (it stores the key)
+
+The v2 API authenticates with `BROWSER_USE_API_KEY` — the same key `methodology.md` step 0 resolves
+(browser-harness's `.env`, the process env, or self-signup). The cleanest way to use
+*browser-harness's stored key* is to run the calls **inside a `browser-harness` heredoc**, where
+the key is already loaded into `os.environ` — no separate plumbing, no re-exporting. (Plain `curl`
+with `$BROWSER_USE_API_KEY` also works if it's exported. The v2 task itself runs on a Browser Use
+cloud browser, so no local Chrome is needed for the test — browser-harness here is just the key
+store + HTTP runtime.)
+
+## Flow: create → poll → report
+
+Fill in `task`, `startUrl` (the public URL — tunnel a localhost target first), and
+`judgeGroundTruth` (what success looks like), then run:
+
+```bash
+browser-harness <<'PY'
+import os, json, time, urllib.request, urllib.error, subprocess, sys
+KEY = os.environ.get("BROWSER_USE_API_KEY")
+assert KEY, "no BROWSER_USE_API_KEY — resolve it per methodology.md step 0"
+BASE = "https://api.browser-use.com/api/v2"
+
+def open_local(url):
+ """Open a URL in the user's LOCAL browser (Chrome first) so they can watch the cloud agent run.
+ This views the dashboard thread — it does NOT run the test locally; the task still runs in the cloud."""
+ cmds = ([["open", "-a", "Google Chrome", url], ["open", url]] if sys.platform == "darwin"
+ else [["google-chrome", url], ["xdg-open", url]])
+ for c in cmds:
+ try:
+ subprocess.Popen(c, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+ return
+ except FileNotFoundError:
+ continue
+
+def call(method, path, body=None):
+ req = urllib.request.Request(
+ BASE + path,
+ data=json.dumps(body).encode() if body is not None else None,
+ method=method,
+ headers={"X-Browser-Use-API-Key": KEY, "Content-Type": "application/json"},
+ )
+ try:
+ with urllib.request.urlopen(req) as r:
+ return json.load(r)
+ except urllib.error.HTTPError as e:
+ raise SystemExit(f"v2 API {e.code}: {e.read().decode()[:300]}")
+
+# 1-5 score schema (structuredOutput must be a *stringified* JSON schema)
+SCORE_SCHEMA = json.dumps({
+ "type": "object",
+ "properties": {
+ "score": {"type": "integer", "minimum": 1, "maximum": 5},
+ "verdict": {"type": "string"},
+ "worked": {"type": "array", "items": {"type": "string"}},
+ "issues": {"type": "array", "items": {"type": "string"}},
+ },
+ "required": ["score", "verdict"],
+})
+
+created = call("POST", "/tasks", {
+ "task": "QA TASK HERE — e.g. 'Add an item to the cart, go to checkout, and report whether "
+ "it completes. Score 1-5 (5=flawless, 1=broken) with what worked and any issues.'",
+ "startUrl": "https://PUBLIC-URL-UNDER-TEST", # tunnel localhost first; pass the public URL
+ "judge": True,
+ "judgeGroundTruth": "SUCCESS LOOKS LIKE — e.g. 'An order-confirmation / thank-you page is shown.'",
+ "structuredOutput": SCORE_SCHEMA,
+ "maxSteps": 50, # a CEILING, not a target — the agent stops when done, so this doesn't inflate cost;
+ # 50 gives room for a multi-step flow. Raise for long flows; cost = steps actually taken.
+ # optional: "llm": "browser-use-2.0", "vision": True,
+ # "sessionSettings": {"proxyCountryCode": "us", "enableRecording": True}
+})
+tid = created["id"]
+sid = created["sessionId"]
+watch_url = f"https://cloud.browser-use.com/thread/{sid}" # dashboard thread = the SESSION (not the task id)
+print("created task", tid, "session", sid, flush=True)
+print("watch:", watch_url, flush=True)
+open_local(watch_url) # pop it open in the user's local Chrome to watch
+
+while True: # poll to a terminal state
+ t = call("GET", "/tasks/" + tid)
+ if t["status"] in ("finished", "failed", "stopped"):
+ break
+ time.sleep(5)
+
+print(json.dumps({
+ "status": t["status"],
+ "score_output": t.get("output"), # the structuredOutput JSON → the 1-5 score object
+ "judgeVerdict": t.get("judgeVerdict"), # True = passed the ground-truth check, False = failed
+ "judgement": t.get("judgement"), # judge's reasoning (stringified JSON report)
+ "cost_usd": t.get("cost"), # what this run spent
+ "num_steps": len(t.get("steps") or []),
+}, indent=2))
+PY
+```
+
+## Watch it live: open the agent session in local Chrome
+
+As soon as a task is created, **open its dashboard thread in the user's local Chrome so they can watch the agent work** — that's the `open_local(...)` call above. The watch URL is built from the **session id**:
+
+```
+https://cloud.browser-use.com/thread/{sessionId}
+```
+
+That `/thread/<uuid>` page is the v2 agent's run: the live browser plus the agent's step-by-step reasoning, screenshots, and (when finished) the judge verdict. Notes:
+
+- The `{id}` is the **`sessionId`** from `POST /tasks` — **not** the task `id`. (Verified: `GET /tasks/{sessionId}` 404s; the dashboard groups a run by its session.) Always print the URL too, so the user has it even if the browser doesn't auto-open.
+- This is a **viewing** convenience only — it opens a webpage in local Chrome. It does **not** violate the "tests run on a cloud browser" rule; the task still executes server-side. (Don't confuse it with `liveUrl`, the raw single-session CDP viewer on `live.browser-use.com` that dies when the session stops — the dashboard thread persists after the run, so it's the better link to hand the user.)
+- `open_local` targets the user's local Chrome (`open -a "Google Chrome"` on macOS, `google-chrome`/`xdg-open` on Linux), falling back to the default browser.
+
+## Mapping the result to the verdict
+
+Report exactly as `methodology.md`'s output format, sourced from the agent's result:
+
+- **`Score: N/5`** ← the `score` field of the structured `output` — **but `judgeVerdict` overrides it.**
+ The structured `score` is the agent's *self-report* and can be wrong (an agent will happily score a
+ blank page 5/5). **If `judgeVerdict` is `False`, the flow FAILED regardless of the self-score** — cap
+ it at ≤2 and lead with the judge's `failure_reason`. (Real example: an agent self-scored x.ai/pricing
+ 5/5 "fully functional"; the judge saw the page rendered blank and returned `false`. Trust the judge.)
+- **Result / pass-fail** ← `judgeVerdict` (true = met the ground truth, false = didn't). The agent's
+ `score`/`isSuccess` are self-reports and are less reliable — **`judgeVerdict` is authoritative.**
+- **What worked / issues** ← the structured `worked` / `issues` arrays, cross-checked against
+ `judgement` (the judge's reasoning).
+- **Evidence** ← `steps[]`: each has `url`, `screenshotUrl`, `actions` (and sometimes `nextGoal` —
+ may be empty). Cite the `screenshotUrl`s of the key moments.
+- **Cost** ← surface `cost` so the user sees what the run spent.
+
+Report it in this format (the same one the Claude backend uses — self-contained here so you don't
+need to open `methodology.md`):
+
+```
+Score: N/5
+Task: <what you asked the agent to verify>
+Result: <pass/fail from judgeVerdict + one line>
+What worked:
+- <from the structured `worked` array / judgement>
+Issues:
+- [tag] <from `issues` / judgement; empty if none>
+Evidence: <key steps[].screenshotUrl links>
+Cost: $X.XX (Browser Use v2 agent, <n> steps)
+```
+
+## Fan out: many flows in parallel
+
+The whole point of v2 subagents is parallel coverage. To test several flows at once, **create all
+the tasks first** (each `POST /tasks` returns immediately with an `id`), then **poll them all** —
+they run concurrently in Browser Use cloud:
+
+```python
+flows = [
+ {"task": "Test signup: …", "startUrl": URL, "judgeGroundTruth": "Account created, lands on dashboard."},
+ {"task": "Test checkout: …", "startUrl": URL, "judgeGroundTruth": "Order confirmation shown."},
+ {"task": "Test search + filters: …", "startUrl": URL, "judgeGroundTruth": "Filtered results update."},
+]
+ids = []
+for f in flows:
+ c = call("POST", "/tasks", {**f, "judge": True, "structuredOutput": SCORE_SCHEMA, "maxSteps": 50})
+ open_local(f"https://cloud.browser-use.com/thread/{c['sessionId']}") # one Chrome tab per flow, to watch
+ ids.append((f["task"][:40], c["id"]))
+
+results = {}
+while len(results) < len(ids):
+ for label, tid in ids:
+ if tid in results: continue
+ t = call("GET", "/tasks/" + tid)
+ if t["status"] in ("finished", "failed", "stopped"):
+ self_score = (json.loads(t["output"]).get("score") if t.get("output") else None)
+ passed = t.get("judgeVerdict") is True # JUDGE is authoritative, not the self-score
+ results[tid] = {"label": label, "passed": passed, "self_score": self_score,
+ "score": (self_score if passed else min(self_score or 2, 2)), # judge=False caps it
+ "cost": t.get("cost")}
+ time.sleep(5)
+# Per flow: PASS only if judgeVerdict is True. A flow where the agent self-scored high but
+# judgeVerdict is False is a *caught failure* — flag it and score it low.
+# Overall = the weakest flow (min of the judge-corrected scores) — never average a failed flow up.
+```
+
+Watch the **concurrent-session cap** (Free = 3): creating more than the cap at once yields `429` —
+batch the creates to stay under it.
+
+## Gotchas
+
+- **`structuredOutput` is a *string*** — pass `json.dumps(schema)`, not the schema object.
+- **localhost isn't reachable** by the cloud agent — tunnel it (ngrok, per `methodology.md`) and
+ pass the public `startUrl`; for a free-ngrok host, tell the agent in the `task` to click through
+ any "You are about to visit" interstitial.
+- **`429 TooManyConcurrentActiveSessionsError`** — the account hit its concurrent-session cap
+ (Free = 3); wait or stop other sessions.
+- **`maxSteps` is a safety ceiling, not a cost lever** — the agent stops when the task is complete, so the cap doesn't drive cost (this run capped at 15 but used 5 steps). Keep ~50 for headroom; raise for long flows.
+- **Teardown is a no-op for the v2 path on a public URL** — the one-off session auto-closes and there's no tunnel to kill. (Only the Claude/localhost path needs teardown.)
+- **Verify the key resolves before the billable create** — the snippet's `assert KEY` does this; if it's missing, resolve it per `methodology.md` step 0 *before* calling `POST /tasks`.
diff --git a/skills/qa/references/methodology.md b/skills/qa/references/methodology.md
new file mode 100644
index 000000000..263690ca3
--- /dev/null
+++ b/skills/qa/references/methodology.md
@@ -0,0 +1,158 @@
+# QA methodology
+
+The full test loop, gotchas, rubric, and output format for the `qa` skill. Everything below runs through **browser-harness** (the `browser-harness <<'PY' … PY` heredoc form — each call is a fresh shell, daemon auto-starts).
+
+## Always test on a cloud browser (tunnel localhost)
+
+**Run every QA test on a Browser Use cloud browser — never the user's local Chrome.** This is the default for *all* targets, public or local. A cloud browser is a clean, real-user environment: no logged-in sessions, no extensions, no clobbering the tab the user is working in, and it produces a `liveUrl` the user (and the report) can point to. Testing on the user's own Chrome contaminates the result with their state and is not what QA wants.
+
+This means a `localhost` site is **not** an exception that lets you skip the cloud browser — it's the case that *requires the tunnel*. A cloud browser lives on the public internet and cannot reach `localhost`, so you expose the dev server with a tunnel first, then point the cloud browser at the public URL. Do **not** fall back to the local daemon just because the site is local; tunnel it out.
+
+**0. Get a Browser Use API key — the only credential this skill uses.** The cloud browser authenticates with `BROWSER_USE_API_KEY`, and browser-harness is the single source of it: it auto-loads a `.env` (from its repo root and `agent-workspace/`) on every call, with the process env winning over that. Use *only* that key — never substitute another credential, and **never fall back to the user's local Chrome** if it's absent. Don't assume it's missing just because it isn't echoed in your shell; the authoritative test is whether a cloud browser starts (step 2's `start_remote_daemon(...)` returns a `liveUrl`).
+
+If no key is resolvable, do **not** proceed on local Chrome. Pick one of exactly two paths (ask the user which, if it's unclear), then make the key available and retry step 2:
+
+- **A — Wait for the user to provide one** (they grab one at `cloud.browser-use.com/new-api-key`).
+- **B — Self-sign-up, no human needed** — run the agent challenge-response flow documented in `docs.browser-use.com/llms.txt` (the browser-harness README links it under setup) to get a free key. The challenge is a *randomized, often obfuscated* word problem (leetspeak, foreign-language numerals, multi-step) — not always simple arithmetic. If one is hard to decode confidently, just re-request a fresh challenge; difficulty varies and re-rolling is the fastest unblock.
+
+To make the key available, prefer the **inline form** — `export BROWSER_USE_API_KEY=bu_… ` at the top of every `browser-harness` call. This always works and sidesteps a real trap: the package that *runs* (a uv/pip install) often lives in a **different tree** than the skill/docs directory you're reading, so "browser-harness's `.env`" is ambiguous. If you do want to persist it via `.env`, write to the **running package's** repo root (`parents[2]` of the executing `helpers.py`/`admin.py`, e.g. `~/Developer/browser-harness/.env`) — not necessarily the folder these skill files live in.
+
+**A tunnel binary must also be installed and authed** — but only for a **localhost** target (a public URL skips the tunnel entirely, so don't block on this for public sites). Check before you rely on it, and recover if it's missing:
+
+```bash
+# ngrok is the default; cloudflared is the no-account fallback.
+command -v ngrok && ngrok config check # installed AND authed?
+command -v cloudflared # fallback that needs no account/auth
+```
+
+- **ngrok present and `config check` passes** → use it (step 1).
+- **ngrok present but `config check` fails** (no authtoken) → it's installed but unauthed. Either ask the user to run `ngrok config add-authtoken <token>` (free token at `dashboard.ngrok.com`), or fall through to cloudflared.
+- **Neither installed** → don't silently give up. Prefer **cloudflared** — it needs no account, no auth, and has no interstitial: install it (`brew install cloudflared` on macOS, or the binary from `github.com/cloudflare/cloudflared/releases`) and tunnel with `cloudflared tunnel --url http://localhost:PORT`. If you can't install either, **stop and tell the user** which one to install (don't fall back to local Chrome — that violates the cloud-browser rule).
+
+**1. Tunnel the local port — with host-header rewrite.** ngrok is the default (already on `$PATH`); cloudflared is a friction-free alternative if installed. **Use `--host-header=rewrite`:** modern dev servers (Vite, Next, webpack, CRA) reject requests whose `Host` is an unknown public domain with a `403 Blocked request / host not allowed` (Vite's `server.allowedHosts`). Rewriting the Host to `localhost:PORT` makes the dev server see a local request. Start it in the background and read the assigned URL from ngrok's agent API — don't scrape stdout.
+
+```bash
+# dev server is on, say, http://localhost:3000
+ngrok http 3000 --host-header=rewrite --log=stdout > /tmp/qa-ngrok.log 2>&1 &
+sleep 3
+PUBLIC_URL=$(curl -s http://localhost:4040/api/tunnels \
+ | python3 -c 'import sys,json; print(json.load(sys.stdin)["tunnels"][0]["public_url"])')
+echo "$PUBLIC_URL" | tee /tmp/qa-public-url.txt
+# Verify the tunnel reaches the APP, not a 403/interstitial, before spending a cloud browser:
+curl -s -H "ngrok-skip-browser-warning: true" "$PUBLIC_URL" | head -c 200
+# cloudflared alternative (no account, no interstitial): cloudflared tunnel --url http://localhost:3000
+```
+
+For a **public** target, skip the tunnel — just use the URL directly in step 2.
+
+**2. Spin up a cloud browser — with the BU proxy DISABLED — and drive the public URL.** `start_remote_daemon` creates the cloud browser, prints its `liveUrl`, and wires the daemon to `BU_NAME`. **Pass `proxyCountryCode=None`:** Browser Use's default residential proxy mangles ngrok's TLS, so the cloud browser lands on `chrome-error://` / `ERR_SSL_PROTOCOL_ERROR` even though `curl` and other sites work fine. Disabling the proxy fixes it.
+
+```bash
+browser-harness <<'PY'
+start_remote_daemon("qa", proxyCountryCode=None) # proxy off — required for ngrok TLS to work
+PY
+
+PUBLIC_URL=$(cat /tmp/qa-public-url.txt)
+BU_NAME=qa browser-harness <<PY
+new_tab("about:blank")
+# ngrok FREE shows a one-time interstitial; skip it by sending this header before navigating.
+cdp("Network.setExtraHTTPHeaders", headers={"ngrok-skip-browser-warning": "true"})
+goto_url("$PUBLIC_URL")
+wait_for_load()
+print(page_info()) # MUST show the app's real title — not chrome-error, 403, or interstitial
+PY
+```
+
+The bash `PUBLIC_URL` and the `browser-harness` Python heredoc are separate processes — interpolate the URL into the heredoc (note the **unquoted** `<<PY` above so `$PUBLIC_URL` expands), or read it from the temp file. On the cloud browser there's no user tab to clobber, so `goto_url` is fine. If you must change daemon options later (e.g. toggle the proxy), `restart_daemon("qa")` first — `start_remote_daemon` errors if a daemon for that name is already running.
+
+**3. Run the QA loop below** with `BU_NAME=qa` on every `browser-harness` call.
+
+**4. Tear down when done.** Kill the tunnel (`pkill -f "ngrok http 3000"`) and stop the cloud browser — it bills until its timeout. Call **`stop_remote_daemon("qa")`** (that's the function name — *not* `stop_daemon`); it PATCHes the browser to stop via the saved `BU_BROWSER_ID`. Only touch the daemon/browser **you** created: stale numbered daemons or sockets from prior runs (`bu-qa1…`) may belong to other sessions — pick a clean, unique `BU_NAME` and don't stop browsers you didn't start.
+
+Gotchas specific to this path (all field-hit — don't relearn them live):
+- **`403 host not allowed` → use `--host-header=rewrite`** (see step 1). The most common first failure against a Vite/Next/webpack dev server.
+- **`chrome-error://` / SSL error but curl works → disable the BU proxy** with `proxyCountryCode=None` (see step 2). To diagnose, navigate the cloud browser to `https://example.com` first: if that loads but your tunnel doesn't, it's the proxy.
+- **Localhost-only assets / CORS-pinned APIs break through the tunnel.** If the app hardcodes `http://localhost:3000/...` or pins its API/CORS to the `localhost:PORT` origin, those calls fail from the ngrok origin — a tunnel artifact, not a real bug. Don't score it against the app. When the real backend is unreachable this way, look for a **mock/demo mode** (e.g. a `?mock=N` query param or a fixtures flag) so you can still exercise the UI, and say in the report which paths were mock-only.
+- **Dev-instance config is not the app's fault.** A dev server may point at a staging/test backend via `.env` (e.g. `VITE_BU_API_BASE`), so a prod credential 401s. Confirm *which backend* the instance targets before scoring an auth failure as a bug — the app may be faithfully rendering a legitimate upstream error.
+- **The interstitial is not your app — and the skip header is per-tab.** `Network.setExtraHTTPHeaders` applies only to the *current* target, so any **new tab the app opens** (clicking a tile, `target=_blank`, OAuth popups, `window.open`) starts without it and lands on ngrok's `ERR_NGROK_6024` "You are about to visit" page. Re-apply `cdp("Network.setExtraHTTPHeaders", headers={"ngrok-skip-browser-warning":"true"})` on each new target before reading it — or sidestep the whole class by tunneling with **cloudflared**, which has no interstitial. Either way, don't QA the warning page.
+- **Latency is added.** Tunnel + cloud-browser adds round-trips; don't score raw load time harshly unless it's egregiously slow.
+- **Parallel targets:** one port → one tunnel → one `start_remote_daemon(name)` with a distinct `BU_NAME` each, run as separate subagents (browser-harness's SKILL.md covers the remote-browser fan-out pattern).
+
+## The loop
+
+Run every `browser-harness` call below against the cloud browser you started above (i.e. with its `BU_NAME`, e.g. `BU_NAME=qa browser-harness <<'PY' …`), pointed at the tunnel's public URL (or the public site) — not the bare local daemon.
+
+1. **Restate the goal as a concrete user task.** Turn "test the signup" into explicit steps a real user would take and a clear definition of success ("account created → lands on dashboard"). If the prompt is vague, pick the most obvious happy path and say so in the report.
+2. **Drive it like a user.** `new_tab(url)` → `wait_for_load()` → `capture_screenshot()`, then click/type your way through. Screenshot after every meaningful action and verify the page actually changed the way you expected — don't assume a click worked. Two reliability notes for cloud browsers: (a) **click from DOM coordinates, not scaled-screenshot pixels** — if you downscale a shot (e.g. `max_dim=1800` on a 1920-wide viewport) the pixels no longer map 1:1, so clicks miss; read targets with `js("…getBoundingClientRect()…")` and `click_at_xy` those. (b) **Clear an input before typing** (select-all + delete) — typing into an already-filled field concatenates and produces doubled values (a `bu_…bu_…` key), which then looks like an app auth failure but is your own artifact.
+3. **Watch for failures the screenshot won't show.** After each step, `drain_events()` and scan for JS errors (`Runtime.exceptionThrown`), console errors (`Runtime.consoleAPICalled` with `type == "error"`), and failed requests (`Network.responseReceived` with status ≥ 400, `Network.loadingFailed`). A page that *looks* fine but throws on every click is not a 5.
+4. **Probe a little past the happy path.** Try one obvious edge: submit an empty required field, an invalid email, a back-button. Good products handle these gracefully; broken ones leak stack traces or silently no-op.
+5. **Score, with evidence.** Map what you saw onto the rubric and cite specific observations.
+
+```python
+browser-harness <<'PY'
+new_tab("https://example.com/signup")
+wait_for_load()
+capture_screenshot("/tmp/qa-01-landing.png", max_dim=1800)
+
+# ... interact: click_at_xy, type_text, press_key("Enter") ...
+
+# pull non-visual failures
+errs = [e for e in drain_events() if (
+ e["method"] == "Runtime.exceptionThrown"
+ or (e["method"] == "Runtime.consoleAPICalled" and e["params"].get("type") == "error")
+ or (e["method"] == "Network.loadingFailed")
+ or (e["method"] == "Network.responseReceived"
+ and e["params"]["response"]["status"] >= 400)
+)]
+print(len(errs), "error events")
+for e in errs[:10]:
+ print(e["method"], e["params"])
+PY
+```
+
+## The rubric
+
+| Score | Meaning |
+|-------|---------|
+| **5** | Task completes flawlessly. No errors, no friction, responsive and polished. A real user would have zero complaints. |
+| **4** | Task completes. Minor cosmetic or UX nits (a slow load, awkward copy, one console warning) but nothing that blocks or confuses. |
+| **3** | Task completes, but with real friction — a confusing step, a workaround needed, a non-blocking error, or a rough edge case. Usable, not good. |
+| **2** | Task only partially works. A significant bug blocks part of the flow, or success requires luck/retries. Most users would get stuck. |
+| **1** | Task cannot be completed. Critical failure: dead button, hard crash, infinite spinner, page won't load, data lost. |
+
+Anchor the score to **task completion first**, then modify for errors and polish. "It worked but threw three console errors" is a 3–4, not a 5. "It looked beautiful but the submit button does nothing" is a 1, not a 4 — looks don't rescue a broken flow.
+
+When the prompt asks about several things (e.g. "test search *and* filters"), score each sub-task, then report an overall score that reflects the weakest critical path — don't average a broken checkout up to a 3 because the homepage was nice.
+
+## Output format
+
+Return a compact, skimmable verdict. Lead with the number.
+
+```
+Score: 3/5
+
+Task: Sign up with a new email and reach the dashboard.
+Result: Completed, but with friction.
+
+What worked:
+- Form accepted valid input, account created, redirected to dashboard.
+
+Issues:
+- [blocker?] no — "Email already in use" error rendered as raw "[object Object]" (saw it on retry).
+- [console] TypeError in analytics.js on every page (Runtime.exceptionThrown, see /tmp/qa-03.png).
+- [ux] no loading indicator on submit; looked frozen for ~4s.
+
+Edge cases tried: empty email (handled, inline error ✓), 8s submit latency (no spinner ✗).
+Evidence: /tmp/qa-01-landing.png, /tmp/qa-03-error.png
+```
+
+Keep it honest and specific — "the submit button at the bottom of the form did nothing and logged a 500" beats "signup is broken". Cite screenshots and the actual error text so the score is defensible.
+
+## Tips
+
+- **Don't over-trust a clean screenshot.** Always `drain_events()` — many failures (analytics crashes, 4xx/5xx APIs, unhandled promise rejections) are invisible in pixels.
+- **Reset state between runs** when a flow is one-shot (signup with a used email): use a fresh email/value, or a clean tab, so a failure is the *site's* fault not stale state.
+- **Time things that matter.** A 12-second load or a spinner that never resolves is a scoring fact, not a footnote.
+- **Stop at auth/payment walls you can't legitimately pass.** Score what you could verify, and state plainly what you couldn't reach and why.
+- **Mind real, billed, or destructive actions.** When the app under test itself provisions resources (spins up VMs/browsers, sends emails, charges cards), exercise the path *minimally* — one item, not a burst — and avoid bulk-destructive controls ("delete all", "stop all") that could nuke state you didn't create (including your own test harness or the user's pre-existing data). Clean up only what you made, ideally via API so you can target it precisely. If you can't test something without collateral damage, say so instead of doing it.
+- **Be reproducible.** Note the exact URL, the steps, and the inputs you used so someone can rerun your test.