---
name: browser-guidance
description: Use when operating websites or local web apps through the built-in browser tool.
allowed_tools: ["browser", "web_fetch", "web_search"]
---

# Browser Guidance

Use `browser` for JavaScript-capable pages. Choose the right web tool once, read with `snapshot`, act with current refs, then verify with `wait`/`get`.

## Tool Routing

- `web_search`: static facts, no known URL.
- `web_fetch`: one known URL with readable server HTML.
- `browser`: JavaScript-rendered pages, forms, clicks, login checks, live/interactive data, dashboards, seat maps — in `browser`'s OWN managed instance, NOT the page/app the user has open on their screen.
- `computer_use`: when the task is about the user's OWN live screen or a session they are watching (a page/app/game they already have open) — `browser` can't see or act on that (separate context; it desyncs). One carve-out: when the live state is SERVER-synced under the same account (a live game, a shared doc), driving the same page here acts on the very state the user is watching — the element rails then beat screen pixels; for anything not server-synced, a second copy silently desyncs from their view. Reserve `computer_use` for live-screen work; a nameable URL is still `web_fetch`/`browser`.
- Never shell-scrape JavaScript sites. Empty/partial `web_search` or `web_fetch` output on dynamic content means switch to `browser`.
- To wait for a page to change (a result to load, live content to update, the other side of a shared session to move), use the browser's `act` action with `kind: "wait"` (and a `wait_until` target) on THIS session — there is no top-level `wait` action; don't switch to `computer_use` to watch a page you are already driving here.

## Operating Loop

1. Use the default profile unless login state, user observation, or a headless-only blocker requires another.
2. `open`/`navigate`, then `snapshot`; snapshot refs are valid only for that page state.
3. Pass the intended `target` when multiple tabs exist.
4. After page-changing actions, verify with `wait`/`get`; snapshot again only when refs or structure changed.

## Actions

- `fill` sets a field value; `type` appends.
- `submit` uses a field ref from the form and clicks the primary submit/search control.
- `click`/`submit` may return sampled `url`; `fill`/`type` may return sampled `value`. Receipts are immediate observations, not proof that async navigation or rendering finished.
- Use `wait` for expected URL/text/element/load changes; use `get` for cheap URL/title/text/ready-state reads.

## Tab And Ref Hygiene

- Reuse one tab target per flow. If popups or retries create extras, use `tabs`, then `focus` or `close`.
- On stale/missing refs: snapshot the same target, retry once with the new ref, then report the blocker.
- Avoid snapshot churn; do not snapshot after every successful `fill`.
- The `screenshot` action returns the page as an image the model actually sees — use it to inspect rendered/visual state. Treat PDFs and downloads as saved artifacts (a path, not seen); read them with `file_read`.

## Stop Conditions

Stop and report for CAPTCHA, 2FA, payment confirmation, missing credentials, URL-policy blocks, unsafe dialogs, repeated launch/profile errors, or the same action failing twice with no new information.