Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs(android): Android is marked experimental where Windows is, with what has been tested; the adb search list is written once, in configuration, and the internals page has the Windows additions; NOT_CHECKED comes from a peek, not browsentic android; the apps' Settings pages get their own table; no contractions, and lines wrapped at 100

Shahriaraf59df3d0d79
diff --git a/README.md b/README.md
index 450d176..9bb2e7c 100644
--- a/README.md
+++ b/README.md
@@ -113,7 +113,7 @@ Full guide, Firefox and unpacked installs included: **[browsentic.com/docs/guide
<td>🔌 <a href="docs/guide/mcp-clients.md"><b>Optional MCP server</b></a></td>
</tr>
<tr>
- <td colspan="3">📱 <a href="docs/guide/features/android.md"><b>Drives Chrome on your Android phone</b></a>, live in a desktop tab, with real taps</td>
+ <td colspan="3">📱 <a href="docs/guide/features/android.md"><b>Drives Chrome on your Android phone</b></a> (<a href="docs/guide/limits.md#android-is-experimental">experimental</a>)</td>
</tr>
</table>
diff --git a/docs/guide/features/android.md b/docs/guide/features/android.md
index 3e0646c..e5fd578 100644
--- a/docs/guide/features/android.md
+++ b/docs/guide/features/android.md
@@ -5,6 +5,8 @@ switch on **Android** in the side panel, and a tab opens showing the phone's Chr
phone frame. A conversation in that tab works on the phone: the same requests, with real taps and
swipes on the phone instead of mouse clicks. Nothing is installed on the phone.
+Android support is [experimental](../limits.md#android-is-experimental).
+
---
## What you need
@@ -12,11 +14,10 @@ swipes on the phone instead of mouse clicks. Nothing is installed on the phone.
- A Chromium browser (Chrome, Edge, Brave, Arc and the like) with the Browsentic extension, paired
to Browsentic Bridge. Firefox has no Android switch.
- **adb**, Android's debugging tool, from Google's
- [platform-tools](https://developer.android.com/tools/releases/platform-tools). The Bridge looks
- for it on your `PATH`, under `ANDROID_HOME` or `ANDROID_SDK_ROOT`, in Android Studio's SDK, where
- Homebrew puts it, and on Windows where winget, Scoop and Chocolatey put it and in your Downloads
- folder, where Windows unzips the platform-tools download. If it is somewhere else, name it in
- [`config.json`](../configuration.md#android).
+ [platform-tools](https://developer.android.com/tools/releases/platform-tools). The Bridge finds
+ it on your `PATH`, in the Android SDK, and where Homebrew, winget, Scoop and Chocolatey put it.
+ The [`android.adb`](../configuration.md#android) setting lists every place it looks, and names
+ your adb when it is somewhere else.
- An Android phone with Google Chrome, connected by USB, or over Wi-Fi once it has been paired with
adb.
@@ -91,10 +92,10 @@ outline to the element around it, and `Esc` cancels. A tap on the phone itself p
carries a photograph of the element from the phone. When the agent asks you to point at something,
it works the same way.
-**Live tools** work there as well. With the Live tool switch on, the agent can write code for the
-phone's page; you approve it before it runs, as on a desktop tab. You can keep the result as a
-saved tool and run it with `/` on the phone tab. A saved tool can't run on every visit on the
-phone, because nothing of Browsentic is installed there.
+**Live tools** work there as well. With the composer's **Live tool** switch on, the agent can write
+code for the phone's page; you approve it before it runs, as on a desktop tab. You can keep the
+result as a [saved tool](page-actions.md#keeping-one) and run it with `/` on the phone tab. A saved
+tool cannot run on every visit on the phone, because nothing of Browsentic is installed there.
## What is off on the phone
@@ -104,7 +105,7 @@ While the phone tab is in front, the side panel hides what only works in a deskt
still work. They all come back when you switch to a desktop tab.
The agent is offered only the tools that work on the phone. Hovering, captchas, downloads,
-uploading a file to a page, a site's own tools, monitors and diagnostics stay on the
+uploading a file to a page, recordings, a site's own tools, monitors and diagnostics stay on the
desktop. If you ask for one of those, the agent says it is not available on the phone.
## Privacy and safety
@@ -136,5 +137,5 @@ If you never want the Bridge to use adb at all, set `"android": { "enabled": fal
value instead.
- New tabs always open in front on the phone, because Chrome on Android does that.
-More in [Limits](../limits.md#android-phones). If a phone will not connect, see
+More in [Limits](../limits.md#android-is-experimental). If a phone will not connect, see
[Troubleshooting](../troubleshooting.md#android-phones).
diff --git a/docs/guide/limits.md b/docs/guide/limits.md
index e12f9ea..4840573 100644
--- a/docs/guide/limits.md
+++ b/docs/guide/limits.md
@@ -184,9 +184,12 @@ and it does nothing but start the Bridge. The trust boundary is unchanged: your
and Vivaldi and Arc on Windows, are not registered yet, so there the Bridge starts with the app, a
command or an MCP client instead.
-## Android phones
+## Android is experimental
-[Driving a phone](features/android.md) has limits of its own:
+[Driving a phone](features/android.md) has been tested on the Android emulator: every tool it
+offers, unplugging and closing Chrome mid-run, the Bridge restarting, and an older extension or
+Bridge on the other side. Real phones over USB and Wi-Fi, and Windows, have not been through that
+test yet. It also has limits of its own:
- **One phone at a time**, driven by one browser at a time.
- **Google Chrome only**, the stable app from the Play Store. Chrome Beta, Dev and Canary and other
@@ -197,7 +200,7 @@ command or an MCP client instead.
- **USB, or Wi-Fi already paired with adb.** Browsentic does not pair a phone over Wi-Fi for you.
- **Desktop-only tools stay on the desktop**: hover, captchas, downloads, uploading a file to a
page, a site's own tools, monitors, diagnostics, recordings and scheduling.
-- **Saved tools don't run on every visit on the phone.** They run with `/` on the phone tab; every
+- **Saved tools do not run on every visit on the phone.** They run with `/` on the phone tab; every
visit needs Browsentic in the page, and nothing of it is installed on the phone.
- **Page code installs in the top document.** In a frame, the agent steps back out first.
- **Native pickers are out of reach.** A `<select>` opens the phone's own picker, which is not part
diff --git a/docs/guide/mac-app.md b/docs/guide/mac-app.md
index 865fd66..cd9fd12 100644
--- a/docs/guide/mac-app.md
+++ b/docs/guide/mac-app.md
@@ -73,24 +73,32 @@ the folder holds a newer build than the browser has loaded.
## The window
-The tabs float at the top; ⌘1 to ⌘5 switch between them. Agents, Skills, Activity and Logs are pages of
-**Settings**, picked from its sidebar.
+The tabs float at the top; ⌘1 to ⌘5 switch between them. Agents, Skills, Activity and Logs are
+pages of **Settings**, picked from its sidebar.
![Browsentic Bridge running, with one row per browser: Chrome connected from the Chrome Web Store, Brave from an unpacked folder, and Edge and Firefox with an add button each.](../assets/mac-app/overview.webp "Overview")
![The Get a pairing code button, and two paired browsers, each with where its extension came from.](../assets/mac-app/browsers.webp "Browsers")
![Every agent CLI with its version and a model select; Codex runs the side panel.](../assets/mac-app/agents.webp "Settings → Agents")
![The three folders skills are read from, a filter, and a card for every skill the agent can route to.](../assets/mac-app/skills.webp "Settings → Skills")
![The Bridge log, followed live as the Bridge restarts and the extension reconnects.](../assets/mac-app/logs.webp "Settings → Logs")
-![The update check, this window’s appearance, the theme every paired browser uses, and the guardrails.](../assets/mac-app/settings.webp "Settings")
+![The update check, this window’s appearance, the theme every paired browser uses, and the guardrails.](../assets/mac-app/settings.webp "Settings → General")
| Tab | What you do there |
| --- | --- |
| **Overview** | Turn Browsentic Bridge on and off with the power button, restart it, see its address and version. One row per browser: where its extension comes from, whether it is connected, and a button that adds it from the store. The unpacked folder sits behind **Load it unpacked instead** |
| **Browsers** | Get a [pairing code](pair.md) with a live countdown, see every paired browser and the store its extension came from, unpair one or all |
| **Android** (experimental) | Whether a phone is ready to drive from the side panel: adb, the phone, USB debugging, Chrome, Chrome open and the screen, one row each, the same checks `browsentic android` prints. A row that fails says what to do, with **Open Chrome on the phone**, **Get Chrome** or the adb install command to copy. **Set up your phone** has the steps. The Bridge looks for phones only while this tab is open |
-| **Settings** | Five pages, picked from its sidebar. **General**: light, dark or system appearance for this window; whether the Bridge starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall. **Agents**: see which agent CLIs are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs. **Skills**: every [skill](features/skills.md) the router can see and which folder it came from. **Activity**: your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured. **Logs**: `~/.browsentic/daemon.log`, followed live |
+| **Settings** | Five pages, picked from its sidebar; see below |
| **About** | Who makes Browsentic, a GitHub star, every version on this computer with a copy button, **Report a bug** (GitHub's issue form with those versions filled in; nothing is sent until you submit it), and links to the guide, this page, [troubleshooting](troubleshooting.md) and the release notes. **Run the checks again** reruns the first-run checks |
+| Settings page | What you do there |
+| --- | --- |
+| **General** | Light, dark or system appearance for this window; whether the Bridge starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall |
+| **Agents** | See which agent CLIs are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs |
+| **Skills** | Every [skill](features/skills.md) the router can see and which folder it came from |
+| **Activity** | Your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured |
+| **Logs** | `~/.browsentic/daemon.log`, followed live |
+
A menu bar item, the Browsentic mark with its centre dot filled while the Bridge runs, shows the
Bridge’s state and has the same on, off and restart controls.
@@ -99,10 +107,10 @@ the side panel and any MCP client keep working with the app closed or quit.
## `browsentic` in your terminal
-**Settings → General → “browsentic” in your terminal** links the launcher into a folder that is already on
-your `PATH` and writable: `~/.local/bin`, `/opt/homebrew/bin` or `/usr/local/bin`. It edits no shell
-profile and asks for no password. Every command in the [CLI reference](../reference/cli.md) then
-works against the install the app manages.
+**Settings → General → “browsentic” in your terminal** links the launcher into a folder that is
+already on your `PATH` and writable: `~/.local/bin`, `/opt/homebrew/bin` or `/usr/local/bin`. It
+edits no shell profile and asks for no password. Every command in the
+[CLI reference](../reference/cli.md) then works against the install the app manages.
If you also installed it with `npm i -g browsentic`, remove that copy (`npm rm -g browsentic`) so
two versions cannot drift apart.
@@ -127,10 +135,10 @@ line, which installs the same release from a terminal.
## Uninstall
-**Settings → General → Uninstall…** runs [`browsentic uninstall`](../reference/cli.md#uninstall): it unpairs
-every browser, stops the Bridge and removes `~/.browsentic` and `~/browsentic`, optionally keeping
-your skills. Remove the extension from each browser first (right-click its toolbar icon →
-**Remove**), and drag the app to the Trash afterwards.
+**Settings → General → Uninstall…** runs [`browsentic uninstall`](../reference/cli.md#uninstall):
+it unpairs every browser, stops the Bridge and removes `~/.browsentic` and `~/browsentic`,
+optionally keeping your skills. Remove the extension from each browser first (right-click its
+toolbar icon → **Remove**), and drag the app to the Trash afterwards.
## Building it yourself
diff --git a/docs/guide/windows-app.md b/docs/guide/windows-app.md
index 020da07..aac01b6 100644
--- a/docs/guide/windows-app.md
+++ b/docs/guide/windows-app.md
@@ -57,18 +57,26 @@ its shell commands through.
## The window
-The tabs float at the top; Ctrl+1 to Ctrl+5 switch between them. Agents, Skills, Activity and Logs are
-pages of **Settings**, picked from its sidebar. Ctrl+Shift+D turns the Bridge on or off, Ctrl+Shift+R
-restarts it, and Ctrl+Shift+P gets a new pairing code.
+The tabs float at the top; Ctrl+1 to Ctrl+5 switch between them. Agents, Skills, Activity and Logs
+are pages of **Settings**, picked from its sidebar. Ctrl+Shift+D turns the Bridge on or off,
+Ctrl+Shift+R restarts it, and Ctrl+Shift+P gets a new pairing code.
| Tab | What you do there |
| --- | --- |
| **Overview** | Turn Browsentic Bridge on and off with the power button, restart it, see its address and version. One row per browser: where its extension comes from, whether it is connected, and a button that adds it from the store. The unpacked folder sits behind **Load it unpacked instead** |
| **Browsers** | Get a [pairing code](pair.md) with a live countdown, see every paired browser and the store its extension came from, unpair one or all |
| **Android** (experimental) | Whether a phone is ready to drive from the side panel: adb, the phone, USB debugging, Chrome, Chrome open and the screen, one row each, the same checks `browsentic android` prints. A row that fails says what to do, with **Open Chrome on the phone**, **Get Chrome**, the `winget` command that installs adb, or the page of phone makers' USB drivers, which many phones need before Windows shows them to adb. **Set up your phone** has the steps. The Bridge looks for phones only while this tab is open |
-| **Settings** | Five pages, picked from its sidebar. **General**: light, dark or system appearance for this window; whether the Bridge starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall. **Agents**: see which agent CLIs are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs. **Skills**: every [skill](features/skills.md) the router can see and which folder it came from. **Activity**: your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured. **Logs**: `%USERPROFILE%\.browsentic\daemon.log`, followed live |
+| **Settings** | Five pages, picked from its sidebar; see below |
| **About** | Who makes Browsentic, a GitHub star, every version on this computer with a copy button, **Report a bug** (GitHub's issue form with those versions filled in; nothing is sent until you submit it), and links to the guide, this page, [troubleshooting](troubleshooting.md) and the release notes. **Run the checks again** reruns the first-run checks |
+| Settings page | What you do there |
+| --- | --- |
+| **General** | Light, dark or system appearance for this window; whether the Bridge starts with the app; the **Browser theme** and **Guardrails** every paired browser uses, the same rows as the extension's settings page, kept in step both ways; `browsentic` in your terminal; the line that registers Browsentic with an [MCP client](mcp-clients.md); uninstall |
+| **Agents** | See which agent CLIs are ready, [switch](agents.md) between them, pick a model, install a missing one, or let Browsentic fix what one still needs |
+| **Skills** | Every [skill](features/skills.md) the router can see and which folder it came from |
+| **Activity** | Your standing [approvals](approvals.md), forgettable per site, and the downloads agents captured |
+| **Logs** | `%USERPROFILE%\.browsentic\daemon.log`, followed live |
+
The Browsentic icon in the notification area shows the Bridge's state and has the same on, off and
restart controls; left-click it to open the window.
@@ -93,9 +101,9 @@ than the browser has loaded.
## `browsentic` in your terminal
-**Settings → General → “browsentic” in your terminal** adds `%USERPROFILE%\.browsentic\bin` to your user
-`PATH`, without administrator rights and without changing anything else in it. Terminals already
-open keep their old `PATH`, so open a new one. Every command in the
+**Settings → General → “browsentic” in your terminal** adds `%USERPROFILE%\.browsentic\bin` to your
+user `PATH`, without administrator rights and without changing anything else in it. Terminals
+already open keep their old `PATH`, so open a new one. Every command in the
[CLI reference](../reference/cli.md) then works against the install the app manages.
`browsentic.exe` is a small executable rather than a `.cmd` script, so an MCP client, if you use
@@ -106,8 +114,8 @@ claude mcp add browsentic -- browsentic mcp
```
If you also installed it with `npm install --global browsentic`, remove that copy
-(`npm rm -g browsentic`) so two versions cannot drift apart. The Settings tab warns you when it
-finds one.
+(`npm rm -g browsentic`) so two versions cannot drift apart. **Settings → General** warns you when
+it finds one.
## Updating
@@ -128,10 +136,11 @@ release.
## Uninstall
-**Settings → General → Uninstall…** runs [`browsentic uninstall`](../reference/cli.md#uninstall): it unpairs
-every browser, stops the Bridge and removes `%USERPROFILE%\.browsentic` and `%USERPROFILE%\browsentic`,
-optionally keeping your skills. Remove the extension from each browser first (right-click its
-toolbar icon → **Remove**). Then uninstall the app itself in **Settings › Apps › Installed apps**.
+**Settings → General → Uninstall…** runs [`browsentic uninstall`](../reference/cli.md#uninstall):
+it unpairs every browser, stops the Bridge and removes `%USERPROFILE%\.browsentic` and
+`%USERPROFILE%\browsentic`, optionally keeping your skills. Remove the extension from each browser
+first (right-click its toolbar icon → **Remove**). Then uninstall the app itself in
+**Settings › Apps › Installed apps**.
Uninstalling only the app from Installed apps stops the Bridge and takes `browsentic` off your
`PATH`, but keeps your pairing, settings and skills, as dragging the Mac app to the Trash does.
diff --git a/docs/internals/agent-runs.md b/docs/internals/agent-runs.md
index 379e293..a8b81fe 100644
--- a/docs/internals/agent-runs.md
+++ b/docs/internals/agent-runs.md
@@ -494,8 +494,8 @@ Chrome versions, and the viewport, read when the message is sent. The run change
desktop tools a phone run is not offered (hover, captchas, downloads, a site's own tools), and
naming a withheld tool invites the agent to try it. `phone.md` names only `PHONE_TOOLS`, and a
test holds it to that. Site notes for the phone page's host still ride along, and the
- page-scripting overlay does with Live tool on, as on desktop. Like `page-scripting`,
- `phone` is a `general` skill kept out of desktop routing by name.
+ page-scripting overlay does with Live tool on, as on desktop. Like `page-scripting`, `phone` is a
+ `general` skill kept out of desktop routing by name.
- **Its prompt opens on the phone** (`PHONE_OPENING` in `prompt.ts`): every tool call lands on the
tab in front on the phone, not on "whichever tab is frontmost". The numbered rules are the same.
- **An `# Android phone` section** carries `phoneBlock(context.phone)`, such as
@@ -503,8 +503,8 @@ Chrome versions, and the viewport, read when the message is sent. The run change
tool call to learn the device. It holds no address, so it does not change with every message.
- **Its tool list is smaller.** `offerFor` withholds every tool off `PHONE_TOOLS`, and the
page-code tools unless Live tool is on, and `invokeForRun` refuses a call to one with
- `NOT_ON_PHONE`. The tool list the browser describes
- is never varied, because it feeds the manifest hash.
+ `NOT_ON_PHONE`. The tool list the browser describes is never varied, because it feeds the
+ manifest hash.
Together these make a phone run's fixed overhead close to 40 % smaller than a desktop run's:
measured as sent on 10 Oct 2026 with Live tool off, the repository's part of the system prompt was
diff --git a/docs/internals/android.md b/docs/internals/android.md
index 8e776d2..4a57807 100644
--- a/docs/internals/android.md
+++ b/docs/internals/android.md
@@ -6,7 +6,7 @@ user sees, read [guide/features/android.md](../guide/features/android.md) first.
---
-## The shape of it
+## How the parts connect
```
Phone Chrome ── debugging socket (localabstract:chrome_devtools_remote)
@@ -43,15 +43,21 @@ WebSocket an extension page opens carries one. Node's `ws` sends none.
## adb, without spawning adb
-`src/daemon/android/adb.ts` finds one adb binary (the configured `android.adb`, then `PATH`,
-`ANDROID_HOME`, `ANDROID_SDK_ROOT`, Android Studio's SDK, Homebrew and winget) and runs it only for
-`adb version` and, when nothing listens on 5037, `adb start-server`. Everything else goes to adb's
-own server over its socket on 127.0.0.1:5037 (`adb-server.ts`): `host:track-devices-l` for the
-phone list, `shell:` for the facts, `forward` and `killforward`.
+`src/daemon/android/adb.ts` finds one adb binary and runs it only for `adb version` and, when
+nothing listens on 5037, `adb start-server`. `adbCandidates` tries, in order: the configured
+`android.adb`, `PATH`, `platform-tools` under `ANDROID_HOME`, `ANDROID_SDK_ROOT` and Android
+Studio's SDK, then Homebrew's two prefixes, or on Windows winget's two package folders, Scoop's
+shims, Chocolatey's `bin` and a platform-tools zip unpacked in `Downloads`. A Bridge keeps the
+`PATH` it started with, so an adb installed after it would otherwise stay unseen.
+
+Everything else goes to adb's own server over its socket on 127.0.0.1:5037 (`adb-server.ts`):
+`host:track-devices-l` for the phone list, `shell:` for the facts, `forward` and `killforward`.
A socket client never kills a server of another version, which running a second adb binary does,
taking Android Studio's connection with it. For the same reason the Bridge never runs
-`adb kill-server` or removes forwards it did not make.
+`adb kill-server` or removes forwards it did not make. `start-server` runs in adb's own folder with
+its output ignored: the server it forks keeps its working folder and any pipe it inherits for as
+long as it runs, and on Windows a folder in use cannot be deleted, renamed or updated.
`phone-facts.ts` asks for everything in one `shell:` call, each answer under its own marker:
`getprop` for the model and Android version, `wm size` and `wm density`, `dumpsys power` for the
@@ -183,30 +189,35 @@ the panel.
`code-toolkit.ts` keeps each approved toolkit for a **place** (`ToolkitPlace`): a desktop tab
(`tabPlace`), or the phone's front tab (`phoneToolkitPlace` in `phone-backend.ts`, keyed
-`phone:<targetId>`). On the phone the installer is evaluated in the top document's main world with a
-plain `Runtime.evaluate` over the relay, which no page CSP can refuse. Calls run `page.runCode`'s own
-page side in the bundle's isolated world, which reaches the toolkit by DOM events exactly as the
-desktop content script does. `toolkitPlaceFor` in `phone-invoke.ts` picks the place for the panel's
-`keepTool` and `/` run. Every-visit tools need `chrome.userScripts` in the page, so they stay desktop
-only.
+`phone:<targetId>`). On the phone the installer is evaluated in the top document's main world with
+a plain `Runtime.evaluate` over the relay, which no page CSP can refuse. Calls run `page.runCode`'s
+own page side in the bundle's isolated world, which reaches the toolkit by DOM events exactly as
+the desktop content script does. `toolkitPlaceFor` in `phone-invoke.ts` picks the place for the
+panel's `keepTool` and `/` run. Every-visit tools need `chrome.userScripts` in the page, so they
+stay desktop only.
## A-Eye on the phone
`page.pickElement` runs its own lens in the bundle's world on the phone. While it waits, `pickOn`
-hands the mirror the lens (`steerLensFromMirror`), and the mirror tab's pointer steers it instead of
-touching the page: a hover sends `aim`, a press that stays within 6 px sends `pick`, and `↑` and `Esc`
-send `wider` and `cancel`. A press that travels further becomes a touch drag, so the page still
-scrolls. The background turns each point into the lens frame's client coordinates (`framePoint`,
-`screenPoint` backwards) and calls `__browsenticPhone.lens` in the lens's world, and collapses aims
-while one is on its way. The page gets no input at all, so disabled controls, links, fields and
-elements whose touch handlers cancel a tap can all be picked. A tap on the phone itself still picks
-through the lens's `click` listener; the lens mutes touch events along with pointer and mouse ones,
-so the page's own handlers cannot cancel that click. The wait is capped at 170 s, under the relay's 180 s per command, so the page's own
-timeout answers first. `pickOn` then photographs the element: `pickClip` pads its box, keeps it on
-screen, moves it into document coordinates (plus any frame's offset), and asks `Page.captureScreenshot`
-for it at device resolution, up to 1,200 px on the long side. The panel's A-Eye button reaches the
-phone through the background (`pickFocus` in `aeye.ts` sends the `invoke` bridge op), because the
-panel cannot reach the socket.
+hands the mirror the lens (`steerLensFromMirror`), and the phone tab's pointer steers it instead of
+touching the page:
+
+- **Steering.** A hover sends `aim`, a press that stays within 6 px sends `pick`, and `↑` and `Esc`
+ send `wider` and `cancel`. A press that travels further becomes a touch drag, so the page still
+ scrolls. The background turns each point into the lens frame's client coordinates (`framePoint`,
+ `screenPoint` backwards), calls `__browsenticPhone.lens` in the lens's world, and collapses aims
+ while one is on its way.
+- **Nothing reaches the page.** Disabled controls, links, fields and elements whose touch handlers
+ cancel a tap can all be picked. A tap on the phone itself still picks through the lens's `click`
+ listener; the lens mutes touch events along with pointer and mouse ones, so the page's own
+ handlers cannot cancel that click.
+- **The wait** is capped at 170 s, under the relay's 180 s per command, so the page's own timeout
+ answers first.
+- **The photograph.** `pickClip` pads the element's box, keeps it on screen, moves it into document
+ coordinates (plus any frame's offset), and `Page.captureScreenshot` takes it at device
+ resolution, up to 1,200 px on the long side.
+- **The panel's A-Eye button** reaches the phone through the background (`pickFocus` in `aeye.ts`
+ sends the `invoke` bridge op), because the panel cannot reach the socket.
## The prompt
diff --git a/docs/internals/extension.md b/docs/internals/extension.md
index 0710684..71bee14 100644
--- a/docs/internals/extension.md
+++ b/docs/internals/extension.md
@@ -434,8 +434,8 @@ Driving a phone (see [Android phones](android.md)) adds two unlisted entrypoints
The phone session itself is `browsentic/phone` in `storage.session`, written only through
`phone.ts`, and the side panel and popup read it with `usePhoneSession`. The panel recognises the
phone tab by its id, not its URL: without the `tabs` permission an extension page's URL is hidden
-from `tabs.query`. The **Android** toggle is hidden on Firefox, and the Firefox build leaves out both entrypoints. No new
-permission was needed.
+from `tabs.query`. The **Android** toggle is hidden on Firefox, and the Firefox build leaves out
+both entrypoints. No new permission was needed.
## Tab scoping
diff --git a/docs/internals/state.md b/docs/internals/state.md
index 966373c..d67d5f7 100644
--- a/docs/internals/state.md
+++ b/docs/internals/state.md
@@ -84,9 +84,9 @@ the page (`browsentic/actionCues`, off when absent).
**The phone session** is `browsentic/phone` in `storage.session`: the phone's serial, the phone
tab's id and window, the phone's tabs and which one is in front, and why it ended. A conversation on
the phone tab is a tab session like any other, marked `phone: { serial }`. Both go when the browser
-closes. Nothing about the phone reaches the Bridge's disk beyond `daemon.log` lines naming its serial,
-its Chrome version and each DevTools method sent, never its parameters; screencast frames are
-never logged or stored. See [Android phones](android.md).
+closes. Nothing about the phone reaches the Bridge's disk beyond `daemon.log` lines naming its
+serial, its Chrome version and each DevTools method sent, never its parameters; screencast frames
+are never logged or stored. See [Android phones](android.md).
**Blocked sites** are `browsentic/blockedSites` in `storage.local`: a list of up to 500 patterns that
the daemon never receives. Removing the extension removes it; each browser keeps its own.
diff --git a/docs/internals/transport.md b/docs/internals/transport.md
index 01bc31f..7b66e03 100644
--- a/docs/internals/transport.md
+++ b/docs/internals/transport.md
@@ -138,8 +138,8 @@ until a store build that retries has replaced it.
Protocol 23 adds the frames that let a browser drive Chrome on an Android phone through the Bridge.
The Bridge keeps the number each extension's `hello` claimed and sends these frames only to an
extension that speaks 23. The extension keeps the number the `welcome` carried (`daemonSpeaks`) and
-sends them only to a Bridge that speaks 23. An extension that speaks 22 is never sent one, and a phone
-request from it is answered `UNSUPPORTED`. The shapes are in `src/lib/phone/types.ts`.
+sends them only to a Bridge that speaks 23. An extension that speaks 22 is never sent one, and a
+phone request from it is answered `UNSUPPORTED`. The shapes are in `src/lib/phone/types.ts`.
| Frame | From | What it carries |
| --- | --- | --- |
@@ -158,8 +158,8 @@ showing its Android tab. The control socket has an `android` op that reads the s
subscribes to `android-changed` with `watch` (and lets go with `watch: false`), answers only what is
already known with `peek` (`NOT_CHECKED` while nobody watches), and opens Chrome on a phone with
`launch` and an optional `url` (refused to an agent run's connection). It has no way to send a
-DevTools command. Every action on the phone goes through the extension, which
-is where the blocked-sites list is checked. [Android phones](android.md) follows a tap through all of it.
+DevTools command. Every action on the phone goes through the extension, which is where the
+blocked-sites list is checked. [Android phones](android.md) follows a tap through all of it.
---
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 640ec12..afdcc81 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -103,10 +103,9 @@ spelling still works and is undocumented.
| `browsentic android` | Whether a phone is ready to drive from the side panel: adb, the phone, USB debugging, Chrome, Chrome open and the screen, one row each. A row that fails says what to do; when nothing is ready, the setup steps follow |
| `browsentic android open [url]` | Open Chrome on the phone, at that page if one is given (in a new tab when Chrome is already open). With more than one phone, name it with `--serial <serial>` |
-`android` takes `--json`: the state the apps read, with the setup steps as `guide`. Browsentic finds
-adb on `PATH`, under `ANDROID_HOME` or `ANDROID_SDK_ROOT`, in Android Studio's SDK, or where Homebrew
-puts it; `"android": { "adb": "<path>" }` in `config.json` names one, and
-`"android": { "enabled": false }` stops the Bridge using adb at all.
+`android` takes `--json`: the state the apps read, with the setup steps as `guide`. Where the
+Bridge looks for adb, and the keys that name one or stop it using adb at all, are under
+[Android](../guide/configuration.md#android) in the configuration guide.
## MCP
diff --git a/docs/reference/errors.md b/docs/reference/errors.md
index f4e56b4..e14465e 100644
--- a/docs/reference/errors.md
+++ b/docs/reference/errors.md
@@ -130,7 +130,6 @@ and handed to the agent with the file so it can say why it cannot answer from it
| `FILE_NOT_FOUND` | failed | The browser no longer holds the file's bytes. Attach it again |
| `AGENT_FAILED` | failed | The agent could not start, or returned something that was not a report. The message says which |
-
## Android phones
These come from a conversation on the [phone tab](../guide/features/android.md). The readiness codes
@@ -146,7 +145,7 @@ the apps report; each has a row in [troubleshooting](../guide/troubleshooting.md
| `NAVIGATION_FAILED` | Extension | Chrome on the phone could not open the address; the message carries Chrome's reason |
| `CHROME_NOT_RUNNING` | Daemon | Chrome is not open on the phone, so the session could not start. Open it, or run `browsentic android open` |
| `NOT_OWNER` | Daemon | Another paired browser is already driving this phone. One browser drives a phone at a time |
-| `NOT_CHECKED` | Daemon | `browsentic android` asked before any browser or app was watching for phones, so the Bridge has not looked yet |
+| `NOT_CHECKED` | Daemon | The control socket's `android` op was asked with `peek` before any browser or app was watching for phones, so the Bridge has not looked yet. `browsentic status` shows it as `not checked`; `browsentic android` looks |
| `CDP_ERROR` | Daemon | Chrome on the phone refused a command. The message carries Chrome's reason |
---