junhsss · Nov 11, 2026 · Nov 11, 2026 · Nov 11, 2026 · Nov 12, 2026 · Nov 12, 2026
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
@@ -64,7 +64,6 @@ Steel CLI - browser automation for AI agents. This file is generated from `steel
 - [steel browser tab new](#steel-browser-tab-new)
 - [steel browser tab switch](#steel-browser-tab-switch)
 - [steel browser tab close](#steel-browser-tab-close)
-- [steel browser dialog](#steel-browser-dialog)
 - [steel browser status](#steel-browser-status)
 - [steel browser cancel](#steel-browser-cancel)
 - [steel sessions](#steel-sessions)
@@ -222,7 +221,6 @@ steel browser
 - `is`: Check element state
 - `wait`: Wait for an element, text, URL, load state, download, or a fixed time
 - `tab`: List, open, switch, or close tabs
-- `dialog`: Accept or dismiss an open dialog
 - `status`: Wait for a command that is still running
 - `cancel`: Stop a command that is still running
 
@@ -297,12 +295,12 @@ steel browser captcha
 
 ### Subcommands
 
-- `solve`: Solve a CAPTCHA on the current page
-- `status`: Check CAPTCHA status
+- `solve`: Solve every detected CAPTCHA, or the one a flag picks
+- `status`: Check CAPTCHA status and list page and task ids
 
 ## steel browser captcha solve
 
-Solve a CAPTCHA on the current page
+Solve every detected CAPTCHA, or the one a flag picks
 
 ### Usage
 
@@ -312,13 +310,13 @@ steel browser captcha solve
 
 ### Parameters
 
-- `--page-id` (string, optional): Page ID
-- `--url` (string, optional): Page URL for targeted CAPTCHA solving
-- `--task-id` (string, optional): CAPTCHA task ID for targeted solving
+- `--page-id` (string, optional): Solve only the CAPTCHA on this page (ids from `captcha status`)
+- `--url` (string, optional): Solve only the CAPTCHA on the page at this URL
+- `--task-id` (string, optional): Solve only this CAPTCHA task (ids from `captcha status`)
 
 ## steel browser captcha status
 
-Check CAPTCHA status
+Check CAPTCHA status and list page and task ids
 
 ### Usage
 
@@ -328,7 +326,7 @@ steel browser captcha status
 
 ### Parameters
 
-- `--page-id` (string, optional): Page ID
+- `--page-id` (string, optional): Check only this page
 - `-w, --wait` (boolean, optional): Wait for terminal status
 - `--timeout` (string, optional): Timeout in milliseconds for --wait mode
 - `--interval` (string, optional): Poll interval in milliseconds for --wait mode
@@ -774,7 +772,7 @@ steel browser get
 - `attr`: Get an element attribute
 - `url`: Get the page URL
 - `title`: Get the page title
-- `count`: Count matching elements
+- `count`: Count elements that match a CSS selector
 - `box`: Get an element's bounding box
 
 ## steel browser get text
@@ -870,7 +868,7 @@ steel browser get title
 
 ## steel browser get count
 
-Count matching elements
+Count elements that match a CSS selector
 
 ### Usage
 
@@ -880,7 +878,7 @@ steel browser get count
 
 ### Parameters
 
-- `selector` (string, required): Element ref (e.g. e5) or CSS selector
+- `selector` (string, required): CSS selector (refs do not work here)
 
 ## steel browser get box
 
@@ -1045,22 +1043,6 @@ steel browser tab close
 
 - `tab` (string, optional): Tab id from `tab list`, such as t2
 
-## steel browser dialog
-
-Accept or dismiss an open dialog
-
-### Usage
-
-```bash
-steel browser dialog
-```
-
-### Parameters
-
-- `action` (enum, required): accept or dismiss
-- `id` (string, optional): Dialog id such as d-2 (default: the last dialog the CLI saw)
-- `--text` (string, optional): Answer for a prompt dialog
-
 ## steel browser status
 
 Wait for a command that is still running

diff --git a/docs/references/agent-troubleshooting.md b/docs/references/agent-troubleshooting.md
@@ -88,7 +88,9 @@ steel browser start --local --session "$SESSION_NAME"
 - `stale_ref`: take a new snapshot and use the new refs.
 - `tab_required`: several tabs are open. Run `steel browser tab list`, then
   `steel browser tab switch <tab>`.
-- `dialog_pending`: answer with `steel browser dialog accept` or `dismiss`.
+- `dialog_pending`: commands cannot answer dialogs. Close it in the live view
+  (`steel browser live`), or run `steel browser tab new`, then
+  `steel browser tab close <tab>`.
 - `delivery_failed`: the API could not reach the browser. Run the same command
   again; it will not run twice.
 - Stale state:

diff --git a/docs/references/steel-browser-commands.md b/docs/references/steel-browser-commands.md
@@ -77,7 +77,7 @@ steel browser get value <sel>
 steel browser get attr <sel> <name>
 steel browser get url
 steel browser get title
-steel browser get count <sel>
+steel browser get count <css>      # CSS selector only; a ref names one element
 steel browser get box <sel>
 steel browser is visible|enabled|checked <sel>
 steel browser find <value>         # CSS by default; --by role|text|label|placeholder|alt|title|testid, --name, --exact
@@ -109,25 +109,24 @@ steel browser tab switch t2
 steel browser tab close [t2]     # the current tab if omitted
 ```
 
-Commands without a ref run on the current tab. When a page opens a tab, the CLI prints `Tab t3 opened from t1` and stays on the current tab.
+Commands without a ref run on the current tab. When a page opens a tab, the CLI stays on the current tab. Run `steel browser tab list` to find the new one.
 
 ## Dialogs and long commands
 
 ```bash
-steel browser dialog accept [d-2]      # or dismiss; --text answers a prompt
 steel browser status x-7               # wait for a command that is still running
 steel browser cancel x-7               # stop it
 ```
 
-Dialogs stay open until you answer them. A command that opens one prints the dialog id.
+Commands cannot answer dialogs. A dialog stays open until it is closed, and commands on its tab fail with `dialog_pending` until then. The CLI prints the dialog id and its tab. Close the dialog in the live view (`steel browser live` prints its URL), or close its tab with `steel browser tab close <tab>`. The last open tab cannot be closed, so open another one first with `steel browser tab new`. `steel browser dialog` was removed and prints this advice.
 
 ## Batch
 
 ```bash
 steel browser batch "fill e3 Seoul" "fill e4 Tokyo" "click e5" "snapshot -i"
 ```
 
-Batch sends all commands in one request (at most 50). They run in order and stop at the first failure. Each command is one string. Group words with double or single quotes (`"fill e3 'New York'"`). A quote opens only at the start of a word or right after `=`, and closes only at the end of a word. Quotes anywhere else stay as typed, so `"eval document.querySelector('h1').textContent"` works as written. Inside double quotes, `\"` and `\\` are escapes. An unclosed quote is an error. `tab new`, `tab switch`, `tab close`, `dialog`, `status`, and `cancel` must run on their own. `stop` is not a batch command.
+Batch sends all commands in one request (at most 50). They run in order and stop at the first failure. Each command is one string. Group words with double or single quotes (`"fill e3 'New York'"`). A quote opens only at the start of a word or right after `=`, and closes only at the end of a word. Quotes anywhere else stay as typed, so `"eval document.querySelector('h1').textContent"` works as written. Inside double quotes, `\"` and `\\` are escapes. An unclosed quote is an error. `tab new`, `tab switch`, `tab close`, `status`, and `cancel` must run on their own. `stop` is not a batch command.
 
 ## Retries and output
 

diff --git a/docs/references/steel-browser.md b/docs/references/steel-browser.md
@@ -7,6 +7,7 @@ This reference defines how `steel browser` runs and the contracts of its session
 Each `steel browser` action is one HTTP request to the session's commands API:
 
 - `POST /v1/sessions/{sessionId}/commands` with the API key, a random `Idempotency-Key`, and `after` (the last operation id the CLI received).
+- `steel browser status` and `steel browser cancel` use `GET /v1/sessions/{sessionId}/commands/executions/{executionId}` and `POST .../cancel`. The CLI also uses the `GET` to wait for a command that is still running.
 - The browser engine runs inside the session next to Chrome. It holds refs, tabs, dialogs, and the execution records.
 - The CLI keeps no process running. It stores per-session state in `~/.config/steel/browser-sessions/<name>.json`.
 
@@ -129,7 +130,10 @@ Main flags:
 
 ### `steel browser captcha solve`
 
-Purpose: manually trigger CAPTCHA solving for a target session.
+Purpose: manually trigger CAPTCHA solving for a target session. Without flags it
+solves every CAPTCHA detected in the session. `--page-id`, `--url`, or
+`--task-id` solves only the one it names. `steel browser captcha status` lists
+the page and task ids.
 
 Main flags:
 
@@ -146,6 +150,25 @@ API mapping:
 - Request body: optional `pageId`, `url`, `taskId`
 - Response: `success` + optional `message`
 
+### `steel browser captcha status`
+
+Purpose: print the overall CAPTCHA status, then one line per page and per task:
+
+```text
+solving turnstile
+page 9F3C2A1B https://example.com/login
+  task 7d1e turnstile solving
+```
+
+Pass the page id to `--page-id` and the task id to `--task-id`. `--page-id` on
+`status` checks only that page. `--json` returns the same ids under `data.pages`.
+
+Main flags:
+
+- `--session <name|id>`
+- `--page-id <id>`
+- `-w, --wait`, `--timeout <ms>`, `--interval <ms>`
+
 ## Profile Persistence
 
 Profiles let sessions start with pre-existing browser state (cookies, local storage, IndexedDB, etc.) imported from a local Chrome installation.
@@ -173,6 +196,8 @@ Profile metadata is stored at `~/.config/steel/profiles/<name>.json`.
 Self-hosted steel-browser serves the commands API only when it runs with
 `ENABLE_COMMANDS_API=true`. Without it, browser actions fail with
 `missing_capability`. `steel dev start` does not turn it on yet.
+It also needs steel-browser from 2026-11-09 or later. Older builds do not
+serve the execution routes or the `find` target form.
 
 ## Troubleshooting (Agent-Focused)
 
@@ -185,7 +210,9 @@ Self-hosted steel-browser serves the commands API only when it runs with
   ensure all steps share the same `--session <name>`.
 - `stale_ref`: take a new snapshot (`steel browser snapshot -i`) and use the new refs.
 - `tab_required`: several tabs are open. Pick one with `steel browser tab switch <tab>`.
-- `dialog_pending`: answer the dialog with `steel browser dialog accept` or `dismiss`.
+- `dialog_pending`: a dialog blocks the tab, and commands cannot answer it. Close
+  it in the live view (`steel browser live`), or run `steel browser tab new`, then
+  `steel browser tab close <tab>`.
 - `This is the stored result of an earlier run`: the same command already ran
   after the last response the CLI received. Nothing ran again.
 - `delivery_failed`: the API could not reach the browser. Run the same command