pi-agent-browser-native 0.2.24 → 0.2.25

package/docs/COMMAND_REFERENCE.md

@@ -5,6 +5,7 @@ Related docs:
 - [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md)
 - [`ARCHITECTURE.md`](ARCHITECTURE.md)
 - [`RELEASE.md`](RELEASE.md)
+- [`SUPPORT_MATRIX.md`](SUPPORT_MATRIX.md)
 
 ## Purpose
 
@@ -19,25 +20,52 @@ This project intentionally blocks normal `agent-browser` bash usage in most agen
 This reference is baselined to the locally installed `agent-browser 0.27.0` command/help surface. Upstream `agent-browser` remains the source of truth for command semantics; this file is the local fallback for Pi agent sessions where direct binary help is blocked or discouraged.
 
 The lightweight drift check is `npm run verify -- command-reference`. Run it whenever the installed upstream `agent-browser` version changes or this reference is edited.
+
+Use `npm run benchmark:agent-browser` or `npm run verify -- benchmark` before and after agent-facing workflow abstractions to measure task success, tool calls, model-visible output size, stale-ref behavior, artifact success, failure-category coverage, and elapsed-time estimates.
 <!-- agent-browser-capability-baseline:end upstream-baseline -->
 
 ## Core mental model
 
-Tool parameters:
+Tool parameters (use exactly one of `args`, `semanticAction`, `job`, `qa`, `sourceLookup`, or `networkSourceLookup`):
 
 ```json
-{
-  "args": ["open", "https://example.com"],
-  "stdin": "optional raw stdin content",
-  "sessionMode": "auto"
-}
+{ "args": ["open", "https://example.com"], "sessionMode": "auto" }
+```
+
+```json
+{ "semanticAction": { "action": "click", "locator": "text", "value": "Submit" }, "sessionMode": "auto" }
+```
+
+```json
+{ "args": ["batch"], "stdin": "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }
+```
+
+```json
+{ "job": { "steps": [{ "action": "open", "url": "https://example.com" }, { "action": "assertText", "text": "Example Domain" }] } }
+```
+
+```json
+{ "sourceLookup": { "selector": "#save", "reactFiberId": "2", "componentName": "SaveButton" } }
+```
+
+```json
+{ "networkSourceLookup": { "requestId": "req-1", "url": "/api/fail" } }
 ```
 
-- `args`: exact `agent-browser` CLI tokens after the binary name.
-- `stdin`: only for `batch`, `eval --stdin`, and `auth save --password-stdin`; other command/stdin combinations are rejected before `agent-browser` is launched.
+- `args`: exact `agent-browser` CLI tokens after the binary name. Omit when using `semanticAction`, `job`, `qa`, `sourceLookup`, or `networkSourceLookup` instead (mutually exclusive).
+- `semanticAction`: optional shorthand for common `find` flows; compiles to `find` argv and is rejected together with `args`, `job`, `qa`, `sourceLookup`, or `networkSourceLookup` on the same call.
+- `job`: optional constrained short-workflow schema; compiles to existing upstream `batch` args/stdin and reports the compiled plan in `details.compiledJob`.
+- `qa`: optional lightweight QA preset; compiles to the same batch path and reports `details.compiledQaPreset` plus `details.qaPreset` pass/fail evidence.
+- `sourceLookup`: optional experimental helper for local UI-to-source *candidates*; compiles to the same `batch` path, reports `details.compiledSourceLookup` and `details.sourceLookup`, and never reclassifies a fully successful upstream batch as failed the way `qa` can (see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#sourcelookup) and the longer notes below).
+- `networkSourceLookup`: optional experimental helper for failed request-to-source *candidates*; compiles to generated `batch`, reports `details.compiledNetworkSourceLookup` and `details.networkSourceLookup`, and never assigns blame or edits files.
+- `stdin`: only for `batch`, `eval --stdin`, and `auth save --password-stdin`; other command/stdin combinations are rejected before `agent-browser` is launched. `job`, `qa`, `sourceLookup`, and `networkSourceLookup` generate their own `batch` stdin.
 - `sessionMode`:
   - `"auto"` reuses the extension-managed session when possible.
-  - `"fresh"` rotates that managed session to a fresh upstream launch so launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, or `--enable` apply.
+  - `"fresh"` rotates that managed session to a fresh upstream launch so launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, `--enable`, `-p` / `--provider`, or iOS `--device` apply.
+
+### Debug, diff, stream, dashboard, and chat families
+
+Upstream also exposes non-core families (`network`, `diff`, `trace` / `profiler` / `record`, `console` / `errors` / `highlight` / `inspect` / `clipboard`, `stream`, `dashboard`, `chat`, and related subcommands). The wrapper still owns argv planning, `--json`, managed sessions where applicable, artifact metadata, and model-facing presentation: structured results are compacted and scrubbed in `extensions/agent-browser/lib/results/presentation.ts`, and echoed argv uses the same `redactInvocationArgs` rules as core commands (see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details) for the field contract). Deterministic fake-upstream coverage for representative JSON shapes and redaction lives in `test/agent-browser.extension-validation.test.ts` under `agentBrowserExtension passes through non-core network debug diff stream dashboard and chat families`.
 
 ## Recommended workflow
 
@@ -96,10 +124,15 @@ Examples:
 { "args": ["find", "role", "button", "click", "--name", "Close"] }
 { "args": ["find", "text", "Close", "click"] }
 { "args": ["find", "label", "Email", "fill", "user@example.com"] }
+{ "semanticAction": { "action": "click", "locator": "role", "value": "button", "name": "Close" } }
+{ "semanticAction": { "action": "fill", "locator": "label", "value": "Email", "text": "user@example.com" } }
+{ "semanticAction": { "action": "uncheck", "locator": "label", "value": "Remember me" } }
 { "args": ["scrollintoview", "@e12"] }
 { "args": ["snapshot", "-i"] }
 ```
 
+The optional native `semanticAction` object is only a thin schema for common locator-based actions; it compiles to existing upstream `find` commands and reports the compiled argv in `details.compiledSemanticAction` (see [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#semanticaction) for the full field rules). It is a top-level alternative to `args`, `job`, `qa`, `sourceLookup`, and `networkSourceLookup`, not a nested shape inside `batch` stdin arrays.
+
 Do not assume Playwright selector dialects such as `text=Close` or `button:has-text('Close')` are supported wrapper syntax. If you need those forms, verify current upstream `agent-browser` behavior first; otherwise use refs, `find`, or known CSS selectors.
 
 ### Extract page data
@@ -121,6 +154,44 @@ Prefer `get` and scoped `eval --stdin` for read-only extraction. Return the inte
 
 Use `batch --bail` when later steps should stop after the first failed command.
 
+For short constrained flows, use top-level `job` instead of hand-writing `batch` stdin. Supported job steps are `open`, `click`, `fill`, `wait`, `assertText`, `assertUrl`, `waitForDownload`, and `screenshot`; the wrapper compiles them to upstream `batch` and records `details.compiledJob.steps[]`. There is still no separate first-class catalog of reusable named browser recipes above `job`, the `qa` preset, and raw `batch`; see [`ARCHITECTURE.md`](ARCHITECTURE.md#no-reusable-recipe-layer-yet) for the closed `RQ-0068` decision and revisit bar.
+
+```json
+{
+  "job": {
+    "steps": [
+      { "action": "open", "url": "https://example.com" },
+      { "action": "assertText", "text": "Example Domain" },
+      { "action": "screenshot", "path": ".dogfood/example.png" }
+    ]
+  }
+}
+```
+
+Use raw `args: ["batch"]` with `stdin` when you need arbitrary upstream commands, flags, or batch failure policies outside the constrained schema. Do not pass `stdin` with `job`, `qa`, `sourceLookup`, or `networkSourceLookup`; those modes generate the batch stdin themselves.
+
+For quick smoke/QA checks, use top-level `qa`. It clears enabled network/console/page-error buffers before opening the target URL, waits for page readiness, checks expected text/selector, inspects fresh network requests, console messages, and page errors, and can capture an evidence screenshot.
+
+```json
+{ "qa": { "url": "https://example.com", "expectedText": "Example Domain", "screenshotPath": ".dogfood/qa-example.png" } }
+```
+
+Optional `checkNetwork`, `checkConsole`, and `checkErrors` default to `true`; set one to `false` to skip that diagnostic. Omit `expectedText` and `expectedSelector` when you only need load plus diagnostics.
+
+Use custom `job` or raw `batch` when you need a different check sequence.
+
+For local app debugging, top-level `sourceLookup` can gather candidate component/file locations for a visible element from selector DOM hints, React DevTools inspection, and a bounded workspace component-name search rooted at the Pi session working directory (`maxWorkspaceFiles` defaults to 2000 and cannot exceed 5000; the scan records at most ten `workspace-search` candidates). With a `selector`, the wrapper runs `is visible` and, unless `includeDomHints` is `false`, `get html` so DOM data attributes and embedded source-like paths can become `dom-attribute` candidates. It reports evidence and confidence in `details.sourceLookup` instead of claiming a guaranteed source file. React hints require a session opened with `--enable react-devtools`. The `details.sourceLookup.status` field reads `unsupported` only when no candidates were collected **and** a `react` batch step failed (inspect errors, missing renderer, and similar); it reads `no-candidates` when the batch succeeded but nothing matched. If selector or workspace hints still yield candidates, `status` remains `candidates-found` even when React inspection failed. Unlike `qa`, the wrapper does not downgrade a **fully successful** upstream batch to `isError` solely because those statuses appear—though failed batch steps still produce normal tool errors.
+
+```json
+{ "sourceLookup": { "selector": "#save", "reactFiberId": "2", "componentName": "SaveButton" } }
+```
+
+Top-level `networkSourceLookup` does the same for failed browser requests. When `requestId` is set it adds `network request <requestId>`; when `filter` or `url` is set it also adds `network requests --filter …`, using `url` as the filter pattern when `filter` is omitted. With `requestId` only, the compiled batch is just that request step; failed-request detection still walks the returned batch JSON and treats HTTP status ≥ 400, `failed: true`, or an `error` field as failure. When `filter` or `url` is present, the same heuristics apply but requests are correlated only if their URL matches that substring (either direction). Workspace URL literal search under the Pi session cwd reuses the `sourceLookup` scan rules (`maxWorkspaceFiles` defaults to 2000, hard cap 5000, at most ten `workspace-search` rows, up to eight URL/path needles from the query plus failed request URLs). It reports `details.networkSourceLookup.status` as `failed-requests-found`, `no-failed-requests`, or `no-candidates` and never assigns definitive blame.
+
+```json
+{ "networkSourceLookup": { "requestId": "req-1", "url": "/api/fail" } }
+```
+
 ### Wait for page readiness or downloads
 
 ```json
@@ -151,17 +222,23 @@ A successful wait-based download renders a readable summary such as `Download co
 ```json
 { "args": ["download", "@e5", "/tmp/report.pdf"] }
 { "args": ["screenshot", "/tmp/page.png"] }
+{ "args": ["screenshot", "--full", "/tmp/full-page.png"] }
+{ "args": ["screenshot", "--annotate", "/tmp/annotated.png"] }
 { "args": ["pdf", "/tmp/page.pdf"] }
 ```
 
+The upstream screenshot aliases are `screenshot --full` for full-page capture and `screenshot --annotate` for labeled screenshots.
+
 Prefer `download <selector> <path>` when the target element itself is the downloadable link/control. Use `click` plus `wait --download [path]` when a previous action starts the download indirectly.
 
 Wrapper result rendering is metadata-first for saved files:
 - screenshots return a saved-path summary, visible artifact metadata, structured `details.artifacts` metadata, and an inline image attachment when safe; the visible block includes artifact type, requested path, absolute path, existence, size, cwd, session, and repair/copy status when applicable
-- downloads, PDFs, `wait --download` files, traces, CPU profiles, completed WebM recordings from `record stop`, and path-bearing HAR captures return concise saved-path summaries plus structured `details.artifacts` metadata without inlining large files
+- downloads, PDFs, `wait --download` files, `state save` state files, diff screenshot output images, traces, CPU profiles, completed WebM recordings from `record stop`, and path-bearing HAR captures return concise saved-path summaries plus structured `details.artifacts` metadata without inlining large files
 - `record start <path>` reports that recording started and that output will be written on `record stop`; the target file may not exist until recording stops
 - `batch` keeps each step's artifacts in `details.batchSteps[].artifacts` and aggregates them in top-level `details.artifacts` in step order
 
+`diff screenshot` follows the file-artifact path above for the **diff** image: model-visible text and `details.artifacts` focus on that output, while baseline paths stay out of the artifact summary block, and Pi does **not** auto-inline the diff the way it inlines trusted `screenshot` captures. `state load` may print the loaded path in prose but does not add a saved-file artifact entry the way `state save` does.
+
 For screenshot paths under dot-directories such as `.dogfood/run/foo.png`, the wrapper normalizes the requested path to an absolute path before invoking upstream `agent-browser`, verifies the requested file exists, and repairs from an upstream temp screenshot when possible. The requested path remains visible as `Requested path`, while `Absolute path` shows the actual on-disk location.
 
 For annotated screenshots in `batch`, put `--annotate` in top-level args instead of inside the screenshot step:
@@ -214,6 +291,32 @@ If the result says `Pending confirmation id: c_8f3a1234`, choose one follow-up:
 
 Confirmation context may be redacted when it contains credentials, tokens, cookies, or auth-bearing URLs. Use the id exactly as printed.
 
+### Use stateful browser-context commands safely
+
+Stateful commands are native `agent_browser` calls, not shell commands. Keep secrets out of `args` whenever upstream supports stdin, and expect model-facing summaries to redact auth, cookie, password, secret, session, and token-like values.
+
+```json
+{ "args": ["auth", "save", "demo", "--password-stdin"], "stdin": "password from the user-approved secret source" }
+{ "args": ["auth", "login", "demo"] }
+{ "args": ["state", "save", "/tmp/demo-state.json"] }
+{ "args": ["state", "load", "/tmp/demo-state.json"], "sessionMode": "fresh" }
+{ "args": ["cookies", "set", "theme", "dark", "--url", "https://example.com"] }
+{ "args": ["storage", "local", "get", "theme"] }
+{ "args": ["dialog", "status"] }
+{ "args": ["dialog", "accept", "prompt text"] }
+{ "args": ["frame", "main"] }
+```
+
+Operational notes:
+
+- `stdin` is accepted only for `batch`, `eval --stdin`, and `auth save --password-stdin`; other stdin-bearing calls are rejected before launch.
+- `auth list/show/save/login/delete` summaries avoid expanding profile secrets. Prefer `auth save --password-stdin` over `--password <value>`.
+- `state save <path>` is a verified file-artifact workflow; inspect `details.artifactVerification` before relying on the file. `state load <path>` is not treated as a newly saved artifact.
+- `cookies get` can expose real authenticated-profile cookies; prefer task-specific page actions and only inspect cookies when the user needs cookie data.
+- `storage local|session` summaries redact sensitive keys and values; still avoid broad storage dumps unless necessary.
+- `dialog accept/dismiss/status`, `frame <selector|main>`, and guarded-action `confirm <id>` / `deny <id>` pass through the native tool. Prefer `details.nextActions` for exact confirmation recovery payloads.
+- `batch` mirrors the same redaction on every step: top-level `details.data` is a compact `{ success, command, result?, error? }[]` matrix (argv-redacted `command`, stateful `result`, scrubbed `error` text). Use `details.batchSteps[]` when you need per-step artifacts, categories, spill paths, or full structured errors beyond the roll-up.
+
 ## Full supported surface
 
 The tables below intentionally list more than the recommended workflow. Rare commands are included so agents can discover that the installed upstream supports them without direct `agent-browser --help` access.
@@ -222,12 +325,14 @@ The tables below intentionally list more than the recommended workflow. Rare com
 
 Native-tool note: upstream skills are written for the standalone `agent-browser` CLI and may show bash/heredoc examples. In pi, convert those examples to `agent_browser` calls: pass CLI tokens in `args`, and pass heredoc/stdin bodies through the tool `stdin` field for `batch`, `eval --stdin`, or `auth save --password-stdin`.
 
+Session note: `skills list`, `skills get …`, and `skills path …` are **stateless** in this wrapper. Even with default `sessionMode: "auto"`, the extension does not prepend the implicit managed `--session` for those commands, so reading bundled skills does not attach to or rotate the active browser session (same intent as plain-text `--help` / `--version` inspection). Other `skills` subcommands follow normal session rules until explicitly allowlisted in `extensions/agent-browser/lib/runtime.ts` alongside regression coverage in `test/agent-browser.runtime.test.ts`.
+
 | Command | Purpose |
 | --- | --- |
 | `skills list` | List available CLI-bundled skills. |
 | `skills get core` | Print the core usage guide. |
 | `skills get core --full` | Print the full version-matched core command reference and templates. |
-| `skills get <name>` | Load a specialized skill such as `electron` or `slack`. |
+| `skills get <name>` | Load a specialized skill such as `electron` or `slack`. Common specialized calls include `skills get electron`, `skills get slack`, `skills get dogfood`, `skills get vercel-sandbox`, and `skills get agentcore`. |
 | `skills path [name]` | Print a skill directory path. |
 
 ### Core page and element commands
@@ -239,7 +344,7 @@ Native-tool note: upstream skills are written for the standalone `agent-browser`
 | `dblclick <sel>` | Double-click an element. |
 | `type <sel> <text>` | Type into an element. |
 | `fill <sel> <text>` | Clear and fill an element. |
-| `press <key>` | Press a key such as `Enter`, `Tab`, or `Control+a`. |
+| `press <key>` | Press a key such as `Enter`, `Tab`, or `Control+a`. Related key-hold aliases include `keydown Shift` and `keyup Shift`. |
 | `keyboard type <text>` | Type text with real keystrokes and no selector. |
 | `keyboard inserttext <text>` | Insert text without key events. |
 | `hover <sel>` | Hover an element. |
@@ -268,12 +373,19 @@ Native-tool note: upstream skills are written for the standalone `agent-browser`
 | `forward` | Go forward. |
 | `reload` | Reload the current page. |
 
-### Session and inspection commands
+### Session, state, frames, dialogs, windows, and inspection commands
 
 | Command | Purpose |
 | --- | --- |
 | `session` | Show current session name. |
 | `session list` | List active sessions. |
+| `state save <path>` | Save cookies, local storage, and session storage to a state file. |
+| `state load <path>` | Load cookies and storage from a state file. |
+| `frame <selector|main>` | Switch iframe context by selector/ref/name/URL, or return to the main frame. |
+| `dialog accept [text]` | Accept an alert, confirm, or prompt dialog, optionally supplying prompt text. |
+| `dialog dismiss` | Dismiss or cancel the current dialog. |
+| `dialog status` | Check whether a dialog is pending. |
+| `window new` | Open a new browser window. |
 | `close` | Close the current browser session. |
 | `close --all` | Close every session. |
 
@@ -284,7 +396,7 @@ Native inspection calls use the `agent_browser` tool shape, not shell-like direc
 - { "args": ["--help"] }
 - { "args": ["--version"] }
 
-These calls return plain text and stay stateless: the extension does not inject its implicit session and does not let inspection consume the managed-session slot needed for later profile, session, CDP, state, or auto-connect launches.
+These calls return plain text and stay stateless: the extension does not inject its implicit session and does not let inspection consume the managed-session slot needed for later profile, session, CDP, state, auto-connect, or provider-backed launches.
 <!-- agent-browser-playbook:end inspection -->
 
 ### Page state, finding, mouse, settings, network, and storage
@@ -353,6 +465,7 @@ Stable tab ids look like `t1`, `t2`, and `t3`. Optional user labels such as `doc
 | `profiler start|stop [path]` | Record a Chrome DevTools profile. |
 | `record start <path> [url]` | Start WebM video recording; output is written on `record stop`. |
 | `record stop` | Stop and save video. |
+| `record restart <path> [url]` | Stop any current recording and start a new WebM recording. |
 | `console [--clear]` | View or clear console logs. |
 | `errors [--clear]` | View or clear page errors. |
 | `highlight <sel>` | Highlight an element. |
@@ -370,7 +483,9 @@ Stable tab ids look like `t1`, `t2`, and `t3`. Optional user labels such as `doc
 | `pushstate <url>` | Perform SPA client-side navigation; detects Next.js router pushes and falls back to history navigation events. |
 | `removeinitscript <id>` | Remove an init script registered through upstream init-script mechanisms. |
 
-When these diagnostic commands are invoked through the native `agent_browser` tool, structured console, page-error, React, Web Vitals, and SPA outputs render as compact summaries when possible, with large outputs previewed and spilled instead of dumped into context. Large outputs are previewed with a `Full output path:` spill file instead of dumping the entire payload into context.
+When these diagnostic commands are invoked through the native `agent_browser` tool, structured console, page-error, React, Web Vitals, and SPA outputs render as compact summaries when possible, with large outputs previewed and spilled instead of dumped into context. Large outputs are previewed with a `Full output path:` spill file instead of dumping the entire payload into context. Artifact-producing commands such as `network har stop`, `diff screenshot`, `trace stop`, `profiler stop`, and `record stop` report `details.artifacts[]` plus `details.artifactVerification`; `record start` is reported as pending until `record stop` completes.
+
+Long-running or lifecycle commands should be explicitly paired with cleanup calls: `stream enable` → `stream disable`, `dashboard start` → `dashboard stop`, `trace start` → `trace stop`, `profiler start` → `profiler stop`, and `record start` → `record stop`. The wrapper keeps each subprocess bounded by its normal timeout; it does not keep an interactive `chat` REPL open, so prefer `chat <message>` with `--model` or `AI_GATEWAY_MODEL` for single-shot AI use.
 
 `trace` and `profiler` share upstream Chrome tracing machinery. Do not run them at the same time. The wrapper tracks owner state it observes in the current Pi session and blocks conflicting starts/stops with "wrapper believes ..." wording because direct upstream CLI use or browser restarts can desynchronize wrapper-local state.
 
@@ -379,7 +494,7 @@ When these diagnostic commands are invoked through the native `agent_browser` to
 | Command | Purpose |
 | --- | --- |
 | `batch [--bail] ["cmd" ...]` | Execute multiple commands sequentially from args or stdin. |
-| `auth save <name> [opts]` | Save an auth profile with options such as `--url`, `--username`, `--password`, or `--password-stdin`. Prefer `--password-stdin` with the tool `stdin` field; avoid putting passwords in `args`. |
+| `auth save <name> [opts]` | Save an auth profile with options such as `--url`, `--username`, `--password`, or `--password-stdin`. Prefer `auth save <name> --password-stdin` with the tool `stdin` field; avoid putting passwords in `args`. |
 | `auth login <name>` | Login using saved credentials. |
 | `auth list` | List saved auth profiles. |
 | `auth show <name>` | Show auth profile metadata. |
@@ -396,10 +511,10 @@ When these diagnostic commands are invoked through the native `agent_browser` to
 | `install` | Install browser binaries. |
 | `install --with-deps` | Install browser binaries plus Linux system dependencies. |
 | `upgrade` | Upgrade `agent-browser` to the latest version. |
-| `doctor [--fix]` | Diagnose install issues and optionally auto-clean stale files. |
+| `doctor [--fix]` | Diagnose install issues and optionally auto-clean stale files. Use `doctor --offline --quick` for a fast local-only check and `doctor --json` for structured output. |
 | `profiles` | List available Chrome profiles. |
 
-When these commands are invoked through the native `agent_browser` tool, structured diagnostic/status outputs are rendered as compact summaries. List-like outputs such as sessions, Chrome profiles, auth profiles, network requests, console messages, and page errors include counts and key fields; large outputs are previewed with a `Full output path:` spill file instead of dumping the entire payload into context. For `network requests`, the wrapper shows status, method, URL, resource/mime type, request id, and, when the installed upstream output includes body-like fields, bounded redacted payload, response, and failure/error snippets. `network request <requestId>` can expose upstream full-detail body fields such as response bodies using the same bounded model-facing preview. Header, cookie, auth, token, and other secret-like fields are not expanded in model-facing text; use upstream HAR or full raw details only when complete data is required.
+When these commands are invoked through the native `agent_browser` tool, structured diagnostic/status outputs are rendered as compact summaries. List-like outputs such as sessions, Chrome profiles, auth profiles, network requests, console messages, and page errors include counts and key fields; large outputs are previewed with a `Full output path:` spill file instead of dumping the entire payload into context. For `network requests`, the wrapper shows status, method, URL, resource/mime type, request id, and, when the installed upstream output includes body-like fields, bounded redacted payload, response, and failure/error snippets. `network request <requestId>` can expose upstream full-detail body fields such as response bodies using the same bounded model-facing preview. Header, cookie, auth, token, and other secret-like fields are not expanded in model-facing text or `details.data`; command echoes also redact `--body`, `--headers`, `--password`, proxy credentials, auth-bearing URLs, cookie/storage values, and bearer/basic credential text in positional arguments. Use upstream HAR or full raw details only when complete data is required.
 
 ## Important global flags, config, and environment
 
@@ -433,7 +548,7 @@ When these commands are invoked through the native `agent_browser` tool, structu
 
 ### Output, provider, policy, and AI flags
 
-- `--json`: JSON output. The wrapper injects this automatically for normal tool execution.
+- `--json`: JSON output. The wrapper injects this automatically for normal tool execution. Environment: `AGENT_BROWSER_JSON`.
 - `--annotate`: annotated screenshot with numbered labels and legend. Environment: `AGENT_BROWSER_ANNOTATE`.
 - `--screenshot-dir <path>`: default screenshot output directory. Environment: `AGENT_BROWSER_SCREENSHOT_DIR`.
 - `--screenshot-quality <n>`: JPEG quality `0-100`. Environment: `AGENT_BROWSER_SCREENSHOT_QUALITY`.
@@ -446,6 +561,7 @@ When these commands are invoked through the native `agent_browser` tool, structu
 - `--confirm-interactive`: interactive confirmations; auto-denies when stdin is not a TTY. Environment: `AGENT_BROWSER_CONFIRM_INTERACTIVE`.
 - `-p, --provider <name>`: provider such as `ios`, `browserbase`, `kernel`, `browseruse`, `browserless`, or `agentcore`. Environment: `AGENT_BROWSER_PROVIDER`.
 - `--device <name>`: iOS device name. Environment: `AGENT_BROWSER_IOS_DEVICE`.
+- Provider-specific iOS examples from upstream include `agent-browser -p ios device list`, `agent-browser -p ios swipe up`, and `agent-browser -p ios tap @e1`; in pi, pass those tokens through `args` rather than bash. iOS requires external Xcode/Appium setup, and cloud providers (`browserbase`, `kernel`, `browseruse`, `browserless`, `agentcore`) require their upstream accounts, credentials, and provider-specific environment variables. The wrapper forwards provider flags/env and stays thin; it does not emulate provider setup or cloud browser behavior.
 - `--model <name>`: AI model for `chat`. Environment: `AI_GATEWAY_MODEL`.
 - `-v, --verbose`: show tool commands and raw output.
 - `-q, --quiet`: show only AI text responses.
@@ -463,12 +579,12 @@ When these commands are invoked through the native `agent_browser` tool, structu
 
 Use `--config <path>` to load a specific config file. Boolean flags accept optional `true` or `false` values, such as `--headed false`, to override config. Browser extensions from user and project configs are merged rather than replaced.
 
-Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGENT_BROWSER_STREAM_PORT`, `AGENT_BROWSER_IDLE_TIMEOUT_MS`, `AGENT_BROWSER_ENCRYPTION_KEY`, `AGENT_BROWSER_STATE_EXPIRE_DAYS`, `AGENT_BROWSER_IOS_UDID`, `AI_GATEWAY_URL`, and `AI_GATEWAY_API_KEY`.
+Other useful environment variables include `AGENT_BROWSER_DEFAULT_TIMEOUT`, `AGENT_BROWSER_STREAM_PORT`, `AGENT_BROWSER_IDLE_TIMEOUT_MS`, `AGENT_BROWSER_ENCRYPTION_KEY`, `AGENT_BROWSER_STATE_EXPIRE_DAYS`, `AGENT_BROWSER_IOS_DEVICE`, `AGENT_BROWSER_IOS_UDID`, `AI_GATEWAY_URL`, and `AI_GATEWAY_API_KEY`. The upstream child also receives every parent variable whose name starts with `AGENT_BROWSER_`, `AGENTCORE_`, `AI_GATEWAY_`, `BROWSERBASE_`, `BROWSERLESS_`, `BROWSER_USE_`, `KERNEL_`, or `XDG_`, plus the explicit inherited-name allowlist in `buildAgentBrowserProcessEnv` (`extensions/agent-browser/lib/process.ts`).
 
 ## Wrapper-specific behavior worth knowing
 
 - The extension may keep following one implicit managed session across later tool calls.
-- If launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, or `--enable` would be ignored because that implicit session is already active, retry with `sessionMode: "fresh"`.
+- If launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, `--auto-connect`, `--init-script`, `--enable`, `--provider` / `-p`, or provider device flags like `--device` would be ignored because that implicit session is already active, retry with `sessionMode: "fresh"`.
 <!-- agent-browser-playbook:start wrapper-tab-recovery -->
 <!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
 - After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --profile, --session-name, or --state), agent_browser best-effort re-selects the tab whose URL matches the returned page when restored tabs steal focus during launch.
@@ -491,46 +607,362 @@ This generated block is review data for maintainers. The human-authored referenc
 
 #### Upstream help commands sampled
 - root help: `agent-browser --help`
+- skills help: `agent-browser skills --help`
+- skills list: `agent-browser skills list`
+- core skill full: `agent-browser skills get core --full`
 - tab help: `agent-browser tab --help`
 - snapshot help: `agent-browser snapshot --help`
 - wait help: `agent-browser wait --help`
+- screenshot help: `agent-browser screenshot --help`
+- find help: `agent-browser find --help`
+- network help: `agent-browser network --help`
+- cookies help: `agent-browser cookies --help`
+- storage help: `agent-browser storage --help`
+- state help: `agent-browser state --help`
+- frame help: `agent-browser frame --help`
+- dialog help: `agent-browser dialog --help`
+- window help: `agent-browser window --help`
+- keyboard help: `agent-browser keyboard --help`
+- batch help: `agent-browser batch --help`
+- auth help: `agent-browser auth --help`
+- stream help: `agent-browser stream --help`
+- dashboard help: `agent-browser dashboard --help`
+- chat help: `agent-browser chat --help`
+- doctor help: `agent-browser doctor --help`
+- diff help: `agent-browser diff --help`
+- trace help: `agent-browser trace --help`
+- profiler help: `agent-browser profiler --help`
+- record help: `agent-browser record --help`
+
+#### Inventory sections
+- Built-in skills: 10 human-doc token(s), 11 upstream token(s)
+- Core page, element, navigation, and extraction commands: 38 human-doc token(s), 40 upstream token(s)
+- Sessions, state, tabs, frames, dialogs, and windows: 12 human-doc token(s), 8 upstream token(s)
+- Network, storage, artifacts, diagnostics, and performance: 29 human-doc token(s), 33 upstream token(s)
+- Batch, auth, confirmations, setup, dashboard, and AI commands: 19 human-doc token(s), 17 upstream token(s)
+- Global flags, config, providers, policy, and environment: 95 human-doc token(s), 90 upstream token(s)
+
+#### Human-authored doc tokens required
+##### Built-in skills
+- `skills list`
+- `skills get core`
+- `skills get core --full`
+- `skills get <name>`
+- `skills get electron`
+- `skills get slack`
+- `skills get dogfood`
+- `skills get vercel-sandbox`
+- `skills get agentcore`
+- `skills path [name]`
+
+##### Core page, element, navigation, and extraction commands
+- `open <url>`
+- `click <sel>`
+- `dblclick <sel>`
+- `type <sel> <text>`
+- `fill <sel> <text>`
+- `press <key>`
+- `keyboard type <text>`
+- `keyboard inserttext <text>`
+- `keydown Shift`
+- `keyup Shift`
+- `hover <sel>`
+- `focus <sel>`
+- `check <sel>`
+- `uncheck <sel>`
+- `select <sel> <val...>`
+- `drag <src> <dst>`
+- `upload <sel> <files...>`
+- `download <sel> <path>`
+- `scroll <dir> [px]`
+- `scrollintoview <sel>`
+- `wait <sel|ms>`
+- `screenshot [path]`
+- `screenshot --full`
+- `screenshot --annotate`
+- `pdf <path>`
+- `snapshot`
+- `eval <js>`
+- `connect <port|url>`
+- `close [--all]`
+- `back`
+- `forward`
+- `reload`
+- `pushstate <url>`
+- `get <what> [selector]`
+- `is <what> <selector>`
+- `find <locator> <value> <action>`
+- `mouse <action> [args]`
+- `set <setting> [value]`
+
+##### Sessions, state, tabs, frames, dialogs, and windows
+- `session`
+- `session list`
+- `state save <path>`
+- `state load <path>`
+- `tab list`
+- `tab new --label <name> [url]`
+- `tab <t<N>|label>`
+- `frame <selector|main>`
+- `dialog accept [text]`
+- `dialog dismiss`
+- `dialog status`
+- `window new`
+
+##### Network, storage, artifacts, diagnostics, and performance
+- `network <action>`
+- `network route <url> [--abort|--body <json>] [--resource-type <csv>]`
+- `network request <requestId>`
+- `cookies [get|set|clear]`
+- `cookies set --curl <file>`
+- `storage <local|session>`
+- `diff snapshot`
+- `diff screenshot --baseline`
+- `diff url <u1> <u2>`
+- `trace start|stop [path]`
+- `profiler start|stop [path]`
+- `record start <path> [url]`
+- `record restart <path> [url]`
+- `record stop`
+- `console [--clear]`
+- `errors [--clear]`
+- `highlight <sel>`
+- `inspect`
+- `clipboard <op> [text]`
+- `stream enable [--port <n>]`
+- `stream disable`
+- `stream status`
+- `react tree`
+- `react inspect <id>`
+- `react renders start`
+- `react renders stop [--json]`
+- `react suspense [--only-dynamic] [--json]`
+- `vitals [url] [--json]`
+- `removeinitscript <id>`
+
+##### Batch, auth, confirmations, setup, dashboard, and AI commands
+- `batch [--bail]`
+- `auth save <name>`
+- `auth save <name> --password-stdin`
+- `auth login <name>`
+- `auth list`
+- `auth show <name>`
+- `auth delete <name>`
+- `confirm <id>`
+- `deny <id>`
+- `chat <message>`
+- `dashboard start --port <n>`
+- `dashboard stop`
+- `install`
+- `install --with-deps`
+- `upgrade`
+- `doctor [--fix]`
+- `doctor --offline --quick`
+- `doctor --json`
+- `profiles`
+
+##### Global flags, config, providers, policy, and environment
+- `--profile <name|path>`
+- `AGENT_BROWSER_PROFILE`
+- `--session <name>`
+- `AGENT_BROWSER_SESSION`
+- `--session-name <name>`
+- `AGENT_BROWSER_SESSION_NAME`
+- `--state <path>`
+- `AGENT_BROWSER_STATE`
+- `--auto-connect`
+- `AGENT_BROWSER_AUTO_CONNECT`
+- `--headers <json>`
+- `--init-script <path>`
+- `AGENT_BROWSER_INIT_SCRIPTS`
+- `--enable <feature>`
+- `AGENT_BROWSER_ENABLE`
+- `--executable-path <path>`
+- `AGENT_BROWSER_EXECUTABLE_PATH`
+- `--extension <path>`
+- `AGENT_BROWSER_EXTENSIONS`
+- `--args <args>`
+- `AGENT_BROWSER_ARGS`
+- `--user-agent <ua>`
+- `AGENT_BROWSER_USER_AGENT`
+- `--proxy <server>`
+- `AGENT_BROWSER_PROXY`
+- `HTTP_PROXY`
+- `HTTPS_PROXY`
+- `ALL_PROXY`
+- `--proxy-bypass <hosts>`
+- `AGENT_BROWSER_PROXY_BYPASS`
+- `NO_PROXY`
+- `--ignore-https-errors`
+- `AGENT_BROWSER_IGNORE_HTTPS_ERRORS`
+- `--allow-file-access`
+- `AGENT_BROWSER_ALLOW_FILE_ACCESS`
+- `--headed`
+- `AGENT_BROWSER_HEADED`
+- `--cdp <port>`
+- `--color-scheme <scheme>`
+- `AGENT_BROWSER_COLOR_SCHEME`
+- `--download-path <path>`
+- `AGENT_BROWSER_DOWNLOAD_PATH`
+- `--engine <name>`
+- `AGENT_BROWSER_ENGINE`
+- `--no-auto-dialog`
+- `AGENT_BROWSER_NO_AUTO_DIALOG`
+- `--json`
+- `AGENT_BROWSER_JSON`
+- `--annotate`
+- `AGENT_BROWSER_ANNOTATE`
+- `--screenshot-dir <path>`
+- `AGENT_BROWSER_SCREENSHOT_DIR`
+- `--screenshot-quality <n>`
+- `AGENT_BROWSER_SCREENSHOT_QUALITY`
+- `--screenshot-format <fmt>`
+- `AGENT_BROWSER_SCREENSHOT_FORMAT`
+- `--content-boundaries`
+- `AGENT_BROWSER_CONTENT_BOUNDARIES`
+- `--max-output <chars>`
+- `AGENT_BROWSER_MAX_OUTPUT`
+- `--allowed-domains <list>`
+- `AGENT_BROWSER_ALLOWED_DOMAINS`
+- `--action-policy <path>`
+- `AGENT_BROWSER_ACTION_POLICY`
+- `--confirm-actions <list>`
+- `AGENT_BROWSER_CONFIRM_ACTIONS`
+- `--confirm-interactive`
+- `AGENT_BROWSER_CONFIRM_INTERACTIVE`
+- `-p, --provider <name>`
+- `AGENT_BROWSER_PROVIDER`
+- `browserbase`
+- `kernel`
+- `browseruse`
+- `browserless`
+- `agentcore`
+- `--device <name>`
+- `AGENT_BROWSER_IOS_DEVICE`
+- `agent-browser -p ios device list`
+- `agent-browser -p ios swipe up`
+- `agent-browser -p ios tap @e1`
+- `--model <name>`
+- `AI_GATEWAY_MODEL`
+- `-v, --verbose`
+- `-q, --quiet`
+- `--debug`
+- `AGENT_BROWSER_DEBUG`
+- `AGENT_BROWSER_CONFIG`
+- `AGENT_BROWSER_DEFAULT_TIMEOUT`
+- `AGENT_BROWSER_STREAM_PORT`
+- `AGENT_BROWSER_IDLE_TIMEOUT_MS`
+- `AGENT_BROWSER_ENCRYPTION_KEY`
+- `AGENT_BROWSER_STATE_EXPIRE_DAYS`
+- `AGENT_BROWSER_IOS_UDID`
+- `AI_GATEWAY_URL`
+- `AI_GATEWAY_API_KEY`
 
 #### Upstream help tokens expected
-- root help: `skills`
-- root help: `keyboard`
-- root help: `scroll`
-- root help: `scrollintoview`
-- root help: `connect`
-- root help: `is`
-- root help: `find`
-- root help: `mouse`
-- root help: `set`
-- root help: `network`
+##### Built-in skills
+- root help: `skills get core --full`
+- skills help: `get <name> --full`
+- skills list: `core`
+- skills list: `electron`
+- skills list: `slack`
+- skills list: `dogfood`
+- skills list: `vercel-sandbox`
+- skills list: `agentcore`
+- core skill full: `agent-browser frame @e3`
+- core skill full: `agent-browser dialog accept`
+- core skill full: `agent-browser state save ./auth.json`
+
+##### Core page, element, navigation, and extraction commands
+- root help: `open <url>`
+- root help: `click <sel>`
+- root help: `dblclick <sel>`
+- root help: `type <sel> <text>`
+- root help: `fill <sel> <text>`
+- root help: `press <key>`
+- root help: `keyboard type <text>`
+- root help: `keyboard inserttext <text>`
+- root help: `hover <sel>`
+- root help: `focus <sel>`
+- root help: `check <sel>`
+- root help: `uncheck <sel>`
+- root help: `select <sel> <val...>`
+- root help: `drag <src> <dst>`
+- root help: `upload <sel> <files...>`
+- root help: `download <sel> <path>`
+- root help: `scroll <dir> [px]`
+- root help: `scrollintoview <sel>`
+- root help: `wait <sel|ms>`
+- root help: `screenshot [path]`
+- root help: `pdf <path>`
+- root help: `snapshot`
+- root help: `eval <js>`
+- root help: `connect <port|url>`
+- root help: `close [--all]`
+- root help: `back`
+- root help: `forward`
+- root help: `reload`
+- root help: `pushstate <url>`
+- root help: `Get Info:  agent-browser get <what> [selector]`
+- root help: `Check State:  agent-browser is <what> <selector>`
+- root help: `Find Elements:  agent-browser find <locator> <value> <action> [text]`
+- root help: `Mouse:  agent-browser mouse <action> [args]`
+- root help: `Browser Settings:  agent-browser set <setting> [value]`
+- keyboard help: `type <text>`
+- keyboard help: `inserttext <text>`
+- screenshot help: `--full, -f`
+- screenshot help: `--annotate`
+- find help: `role <role>`
+- find help: `testid <id>`
+
+##### Sessions, state, tabs, frames, dialogs, and windows
+- root help: `session list`
+- state help: `save <path>`
+- state help: `load <path>`
+- tab help: `new --label <name> [url]`
+- tab help: `Stable tab ids`
+- frame help: `frame <selector|main>`
+- dialog help: `dialog <accept|dismiss|status> [text]`
+- window help: `window <operation>`
+
+##### Network, storage, artifacts, diagnostics, and performance
+- root help: `network <action>`
+- root help: `--resource-type <csv>`
 - root help: `cookies [get|set|clear]`
-- root help: `storage`
+- root help: `cookies set --curl <file>`
+- root help: `storage <local|session>`
 - root help: `diff snapshot`
+- root help: `diff screenshot --baseline`
 - root help: `trace start|stop [path]`
 - root help: `profiler start|stop [path]`
 - root help: `record start <path> [url]`
+- root help: `record stop`
 - root help: `console [--clear]`
 - root help: `errors [--clear]`
 - root help: `highlight <sel>`
 - root help: `inspect`
 - root help: `clipboard <op> [text]`
 - root help: `stream enable [--port <n>]`
+- root help: `stream disable`
+- root help: `stream status`
 - root help: `react tree`
 - root help: `react inspect <id>`
 - root help: `react renders start`
 - root help: `react renders stop [--json]`
 - root help: `react suspense [--only-dynamic] [--json]`
 - root help: `vitals [url] [--json]`
-- root help: `pushstate <url>`
 - root help: `removeinitscript <id>`
-- root help: `--init-script <path>`
-- root help: `--enable <feature>`
-- root help: `--resource-type <csv>`
-- root help: `cookies set --curl <file>`
+- network help: `request <requestId>`
+- network help: `har <start|stop>`
+- storage help: `set <key> <value>`
+- diff help: `diff screenshot --baseline <f>`
+- trace help: `trace <operation> [path]`
+- profiler help: `--categories <list>`
+- record help: `record restart <path.webm> [url]`
+
+##### Batch, auth, confirmations, setup, dashboard, and AI commands
+- root help: `batch [--bail]`
 - root help: `auth save <name>`
+- root help: `auth login <name>`
 - root help: `confirm <id>`
 - root help: `deny <id>`
 - root help: `chat <message>`
@@ -539,9 +971,104 @@ This generated block is review data for maintainers. The human-authored referenc
 - root help: `upgrade`
 - root help: `doctor [--fix]`
 - root help: `profiles`
-- snapshot help: `-u, --urls`
-- wait help: `--download [path]`
-- tab help: `new --label <name> [url]`
+- batch help: `--bail`
+- auth help: `--password-stdin`
+- dashboard help: `dashboard [start|stop] [options]`
+- chat help: `chat <message>`
+- doctor help: `--offline`
+- doctor help: `--json`
+
+##### Global flags, config, providers, policy, and environment
+- root help: `--profile <name|path>`
+- root help: `AGENT_BROWSER_PROFILE`
+- root help: `--session <name>`
+- root help: `AGENT_BROWSER_SESSION`
+- root help: `--session-name <name>`
+- root help: `AGENT_BROWSER_SESSION_NAME`
+- root help: `--state <path>`
+- root help: `AGENT_BROWSER_STATE`
+- root help: `--auto-connect`
+- root help: `AGENT_BROWSER_AUTO_CONNECT`
+- root help: `--headers <json>`
+- root help: `--init-script <path>`
+- root help: `AGENT_BROWSER_INIT_SCRIPTS`
+- root help: `--enable <feature>`
+- root help: `AGENT_BROWSER_ENABLE`
+- root help: `--executable-path <path>`
+- root help: `AGENT_BROWSER_EXECUTABLE_PATH`
+- root help: `--extension <path>`
+- root help: `AGENT_BROWSER_EXTENSIONS`
+- root help: `--args <args>`
+- root help: `AGENT_BROWSER_ARGS`
+- root help: `--user-agent <ua>`
+- root help: `AGENT_BROWSER_USER_AGENT`
+- root help: `--proxy <server>`
+- root help: `AGENT_BROWSER_PROXY`
+- root help: `HTTP_PROXY / HTTPS_PROXY`
+- root help: `ALL_PROXY`
+- root help: `--proxy-bypass <hosts>`
+- root help: `AGENT_BROWSER_PROXY_BYPASS`
+- root help: `NO_PROXY`
+- root help: `--ignore-https-errors`
+- root help: `AGENT_BROWSER_IGNORE_HTTPS_ERRORS`
+- root help: `--allow-file-access`
+- root help: `AGENT_BROWSER_ALLOW_FILE_ACCESS`
+- root help: `--headed`
+- root help: `AGENT_BROWSER_HEADED`
+- root help: `--cdp <port>`
+- root help: `--color-scheme <scheme>`
+- root help: `AGENT_BROWSER_COLOR_SCHEME`
+- root help: `--download-path <path>`
+- root help: `AGENT_BROWSER_DOWNLOAD_PATH`
+- root help: `--engine <name>`
+- root help: `AGENT_BROWSER_ENGINE`
+- root help: `--no-auto-dialog`
+- root help: `AGENT_BROWSER_NO_AUTO_DIALOG`
+- root help: `--json`
+- root help: `AGENT_BROWSER_JSON`
+- root help: `--annotate`
+- root help: `AGENT_BROWSER_ANNOTATE`
+- root help: `--screenshot-dir <path>`
+- root help: `AGENT_BROWSER_SCREENSHOT_DIR`
+- root help: `--screenshot-quality <n>`
+- root help: `AGENT_BROWSER_SCREENSHOT_QUALITY`
+- root help: `--screenshot-format <fmt>`
+- root help: `AGENT_BROWSER_SCREENSHOT_FORMAT`
+- root help: `--content-boundaries`
+- root help: `AGENT_BROWSER_CONTENT_BOUNDARIES`
+- root help: `--max-output <chars>`
+- root help: `AGENT_BROWSER_MAX_OUTPUT`
+- root help: `--allowed-domains <list>`
+- root help: `AGENT_BROWSER_ALLOWED_DOMAINS`
+- root help: `--action-policy <path>`
+- root help: `AGENT_BROWSER_ACTION_POLICY`
+- root help: `--confirm-actions <list>`
+- root help: `AGENT_BROWSER_CONFIRM_ACTIONS`
+- root help: `--confirm-interactive`
+- root help: `AGENT_BROWSER_CONFIRM_INTERACTIVE`
+- root help: `--provider <name>`
+- root help: `AGENT_BROWSER_PROVIDER`
+- root help: `agent-browser -p ios device list`
+- root help: `agent-browser -p ios swipe up`
+- root help: `agent-browser -p ios tap @e1`
+- root help: `--device <name>`
+- root help: `AGENT_BROWSER_IOS_DEVICE`
+- root help: `--model <name>`
+- root help: `AI_GATEWAY_MODEL`
+- root help: `--verbose`
+- root help: `--quiet`
+- root help: `--debug`
+- root help: `AGENT_BROWSER_DEBUG`
+- root help: `--config <path>`
+- root help: `AGENT_BROWSER_CONFIG`
+- root help: `AGENT_BROWSER_DEFAULT_TIMEOUT`
+- root help: `AGENT_BROWSER_STREAM_PORT`
+- root help: `AGENT_BROWSER_IDLE_TIMEOUT_MS`
+- root help: `AGENT_BROWSER_ENCRYPTION_KEY`
+- root help: `AGENT_BROWSER_STATE_EXPIRE_DAYS`
+- root help: `AGENT_BROWSER_IOS_UDID`
+- root help: `AI_GATEWAY_URL`
+- root help: `AI_GATEWAY_API_KEY`
 
 </details>
 <!-- agent-browser-capability-baseline:end capability-token-baseline -->