mobridge-mcp 0.8.5 → 0.8.7

package/AI-USAGE.md

@@ -1,63 +1,177 @@
-# MoBridge 0.7 — hướng dẫn cho AI
-
-MoBridge dùng một daemon dùng chung (`mobd`). CLI và MCP đi qua cùng daemon, vì vậy không mở
-WebSocket riêng và không gọi ADB trực tiếp.
-
-## Cài đặt
-
-Chạy `npx -y mobridge-mcp install --yes` để tự cấu hình các agent đã phát hiện. Installer backup
-config cũ, gỡ registration MoBridge cũ, cài launcher `~/.mobridge/bin/mobridge`, trích companion
-APK và ghi tài liệu này vào `~/.mobridge/AI-USAGE.md`. Sau đó restart agent.
-
-## Chọn CLI hay MCP
-
-- Có shell: dùng CLI cho discovery, health/preflight, chẩn đoán, workflow JSONL, output file và
-  chuỗi lệnh nhiều bước. Lệnh chính: `mobridge devices`, `connect`, `health`, `observe`, `find`,
-  `run`, `trace`.
-- Chỉ có MCP: dùng đúng 5 tool `mobile.device.connect`, `mobile.screen.observe`,
-  `mobile.screen.act`, `mobile.screen.capture`, `mobile.run`.
-- MCP dùng cho semantic action và ảnh inline; CLI dùng cho batch/run, stream, diagnostics và file.
-
-## Khởi động phiên
-
-1. Gọi `mobile.device.connect` hoặc `mobridge connect -d ANDROID:<serial>` một lần.
-2. Luôn đọc `deviceId`, `supportedCapabilities` và trạng thái provision.
-3. Khi có nhiều thiết bị, luôn truyền `deviceId`/`-d`.
-4. Với CLI, preflight là `mobridge health --preflight <package>`.
-5. Mọi response live phải có `backend: "device"`. Nếu thấy `backend: "simulated"`, dừng và không coi kết quả là thao tác trên máy thật. Backend thật là mặc định; fixture chỉ bật tường minh bằng `--simulated` hoặc `MOBRIDGE_BACKEND=sim` cho test.
-
-## Quy tắc thao tác nhanh
-
-- Kết nối một lần. Nếu đã biết query, gọi thẳng `mobile.screen.act` với `query`; không observe/find riêng.
-- Từ hai bước trở lên dùng `mobile.run`/`mobridge run`; daemon giữ dataflow và session nóng.
-- Chỉ observe khi chưa biết màn hình, sau navigation, khi ambiguous hoặc khi action lỗi.
-- Mỗi MCP act chỉ một verb. Mutation phải có verify; `DISPATCHED` không đồng nghĩa `VERIFIED`.
-- NodeRef phải giữ `snapshotId` và `generation`; NodeRef thuần stale thì dừng, chỉ query gốc mới được resolve lại.
-- `mobile.run` không observe cuối mặc định; dùng `returnState:true` hoặc `mobridge run --return-state` khi cần.
-- Evidence lớn nằm trong trace; response thường chỉ có verdict, state gọn và traceId.
-- Dùng `mobile.run`/`mobridge run` cho dataflow; `$name` chỉ được resolve ở host.
-- Không retry mutation sau transport drop hoặc `RESULT_UNKNOWN`; đọc có thể recovery/retry một lần.
-- Mỗi mutation đơn cần `operationId`; workflow cần `workflowId` và `stepId` ổn định. Khi đổi MCP↔CLI,
-  tra operation/workflow status bằng ID gốc trước khi quyết định tiếp. `requestId` chỉ nhận diện một lần gọi.
-- JSONL workflow có checkpoint bền: dùng `mobridge run --status --workflow-id <id>` hoặc `mobile.run`
-  với plan `{"control":"status"}`; chỉ resume cùng plan/device bằng token hiện tại.
-- WAL giữ operation tombstone sau 5 phút; unresolved cũ thành `EXPIRED_UNKNOWN`, không trở thành mutation mới.
-  Checkpoint workflow tồn tại 24 giờ, chỉ lưu HMAC plan hash và verdict/step IDs, không lưu plan/secret; sau daemon restart hãy status rồi resume bằng token mới.
-- Không gọi `adb`, `uiautomator`, tọa độ hoặc `adb shell input` trong luồng semantic.
-- App control không có authorize/allowlist/denylist theo package. Device identity tường minh, fixed argv,
-  safety confirmation và runtime-permission policy vẫn áp dụng; `mobridge app authorize` không tồn tại.
-- Response dùng `transport: "accessibility"` cho semantic/gesture và `transport: "adb"` cho fallback/app step. Gesture tọa độ luôn `verification.level: "unverified"`.
-- Nếu response có `state.interactionBlocked:true` và `state.loadingLikely:true`, UI đang kẹt ở màn hình loading sparse. `mobridge run` sẽ giới hạn wait của bước đó tối đa 2 giây và trả `APP_LOADING_STUCK`; không retry vòng lặp, hãy `capture`/kiểm tra dialog, quyền hoặc mạng rồi observe lại.
-- Secret ưu tiên `valueRef`/secret broker được người dùng cho phép; CLI có thể đọc stdin. Không truyền secret trong argv,
-  không dùng environment làm mặc định, không lưu plaintext trong checkpoint, trace hoặc audit.
-- Ad fast path dùng BACK nhưng chỉ xác nhận thành công khi foreground Activity rời ad; nếu chưa rời thì dùng assisted capture/vision.
-
-## Ví dụ
-
-```bash
+# MoBridge — guide for AI agents (Android only)
+
+MoBridge uses one shared daemon (mobd). The CLI and MCP go through the same daemon, so there is no separate
+WebSocket and you never call ADB directly.
+
+## Install
+
+Run npx -y mobridge-mcp install --yes to configure the agents it detects. The installer backs up old
+configs, removes legacy MoBridge registrations, installs the ~/.mobridge/bin/mobridge launcher, extracts the
+companion APK and writes this document to ~/.mobridge/AI-USAGE.md. Restart the agent afterwards.
+
+## CLI or MCP
+
+- With a shell: use the CLI for discovery, health/preflight, diagnostics, JSONL workflows, file output and
+  multi-step chains. Main commands: mobridge devices, connect, health, observe, find, run, trace.
+- MCP only: use exactly the 5 tools mobile.device.connect, mobile.screen.observe, mobile.screen.act,
+  mobile.screen.capture, mobile.run.
+- MCP is for semantic actions and inline images; the CLI is for batch/run, streams, diagnostics and files.
+
+## Starting a session
+
+1. Call mobile.device.connect, or run mobridge connect -d ANDROID:<serial>, once.
+2. Always read deviceId, supportedCapabilities and the provision status. The connect result also carries
+   `usage`, the onboarding steps to follow before acting.
+3. With several devices always pass deviceId/-d.
+4. With the CLI the preflight is mobridge health --preflight <package>.
+5. Every live response must carry backend: "device". If you see backend: "simulated", stop and do not treat the result as an action on a real phone. The real backend is the default; fixtures are enabled only explicitly with --simulated or MOBRIDGE_BACKEND=sim, for tests.
+
+## Connection and failures (follow in order)
+
+One connect call handles installation: it installs the companion APK if missing, upgrades it when its version differs from the host,
+enables Accessibility over adb, creates the adb forward and then performs the handshake. You do not run adb or install the APK by hand.
+After an install/update, connect waits for the companion to become ready (a few seconds at most), so no immediate second call is needed.
+
+1. mobridge devices (or mobile.device.connect) to get the deviceId; with several devices always pass deviceId.
+2. mobile.device.connect / mobridge connect -d ANDROID:<serial>. Read ready, blockers, warnings, provision.companionInstalled
+   (ALREADY | INSTALLED | UPDATED) and health.accessibility.
+3. On failure read error.code and do exactly the matching step; do not try things at random:
+
+| error.code | Cause | Level | What to do |
+|---|---|---|---|
+| ADB_NOT_FOUND | `adb` is not installed or not on PATH. | needs action | Tell the user to install Android Platform Tools, then run `mobridge connect`. User: Install Android Platform Tools (https://developer.android.com/tools/releases/platform-tools) and add its folder to PATH. |
+| ADB_SERVER_UNRESPONSIVE | The adb server does not answer. | self-heals / retry | Retry `mobridge connect`; if it repeats ask the user to approve `mobridge doctor --restart-adb`. |
+| DEVICE_NOT_FOUND | The device that was named is not attached. | needs action | Run `mobridge devices`, pick an attached serial, never substitute another phone. User: Connect the phone by USB (or `adb connect`) and unlock it. |
+| DEVICE_OFFLINE | adb sees the device but it is offline or just reconnecting. | self-heals / retry | Wait a few seconds and retry `mobridge connect`. User: If it persists: replug the cable, unlock the phone, toggle USB debugging. |
+| DEVICE_UNAUTHORIZED | The phone has not accepted this computer's USB debugging key. | needs action | Ask the user to unlock the phone and accept the dialog, then retry `mobridge connect`. User: Unlock the phone and tap Allow on the "Allow USB debugging?" dialog (tick Always allow). |
+| MULTIPLE_DEVICES | More than one usable device is attached and none was chosen. | needs action | Pick one from `details.candidates` and pass it as deviceId (`-d ANDROID:<serial>`), or save it once with `mobridge device use <serial>`. |
+| AMBIGUOUS_DEVICE | Several devices are connected in this daemon and the call named none. | needs action | Pass `deviceId` (from `mobridge devices`) on every call; never guess one. |
+| DEVICE_BINDING_MISMATCH | The runtime socket answered for a different phone than the one named. | self-heals / retry | Run `mobridge connect -d ANDROID:<serial>` again; if it repeats run `mobridge doctor`. Nothing was driven. |
+| COMPANION_MISSING | The companion app is not installed and no APK was available. | needs action | Run `npx -y mobridge-mcp@latest install`, or set MSM_COMPANION_APK to the APK of this package. |
+| COMPANION_VERSION_MISMATCH | The installed companion is not the build this host expects. | self-heals / retry | Run `mobridge connect`; it updates the companion once. |
+| COMPANION_INSTALL_BLOCKED | The phone refused the USB install (OEM setting or confirmation prompt). | needs action | Show the user `recovery`, then retry `mobridge connect`. User: Unlock the phone and tap Install/Allow; Xiaomi/Redmi/POCO: Developer options > Install via USB and USB debugging (Security settings); Play Protect: Install anyway. |
+| COMPANION_INSTALL_FAILED | The install failed for a device reason (storage, Android version). | needs action | Show the user the message, then retry `mobridge connect`. User: Free storage, or use a device on Android 10+. |
+| COMPANION_NOT_READY | The companion did not answer the handshake ("socket hang up"). | self-heals / retry | Read `diagnostics` and `recovery[0]`, apply it, then run `mobridge connect` again. User: Only if `recovery[0]` asks: open the MoBridge Runtime app once / exclude it from battery optimisation. |
+| COMPANION_UNAVAILABLE | The companion process is not running. | self-heals / retry | Run `mobridge connect`; it restarts the companion. |
+| ACCESSIBILITY_DISABLED | The Accessibility service is off. | self-heals / retry | Run `mobridge connect`; it enables the service over adb and reads it back. |
+| ACCESSIBILITY_ENABLE_BLOCKED | The phone does not let adb enable the Accessibility service. | needs action | Show the user `userAction`, then run `mobridge connect --wait-user 120` to resume the moment it is on. User: Settings > Accessibility > MoBridge Runtime > On. Android 13+: first Settings > Apps > MoBridge Runtime > ⋮ > Allow restricted settings. Xiaomi: Developer options > USB debugging (Security settings). |
+| WAITING_FOR_USER_ACCESSIBILITY | Waiting for the person to turn Accessibility on; the wait window ended. | needs action | Ask the user to finish the step, then run `mobridge connect` again (it resumes; nothing is reinstalled). User: Settings > Accessibility > MoBridge Runtime > On. |
+| ACCESSIBILITY_PREEMPTED | The service is enabled but not bound; another owner took the session. | self-heals / retry | Wait a few seconds and run `mobridge connect`. |
+| EXTERNAL_INSTRUMENTATION_ACTIVE | Another tool holds UiAutomation (uiautomator, a test runner, another agent). | needs action | Fail fast: ask the user to stop the other tool, then `mobridge connect`. User: Stop the other automation tool on this phone. |
+| TRANSPORT_DEGRADED | The link to the phone dropped. | self-heals / retry | Retry the read; for a mutation check `mobridge operation status <operationId>` first. Prefer USB over wireless adb. |
+| WS_CONNECTION_LOST | The WebSocket to the companion closed. | self-heals / retry | Reads retry by themselves; a mutation reports RESULT_UNKNOWN, so look its operation up, never resend it. |
+| RESULT_UNKNOWN | A mutation was dispatched but its effect could not be confirmed. | needs action | Never repeat it. Run `mobridge operation status <operationId>` and observe the screen. |
+| AMBIGUOUS_MATCH | More than one node matches the query. | needs action | Narrow the query using `candidates`; never click the first. |
+| NEEDS_VISION | Semantics are not enough to decide. | needs action | Take `mobile.screen.capture`, look at the image and act with `at`. |
+| UNSUPPORTED_PLATFORM | iOS was requested. | needs action | Use an Android device. |
+
+4. Never repeat a mutation after RESULT_UNKNOWN; connecting again is safe, acting again is not.
+5. Still failing: mobridge doctor, mobridge health, then report with details.diagnostics.
+
+## Rules for fast operation
+
+- Connect once. If you already know the query, call mobile.screen.act with the query directly; do not observe/find separately.
+- Two or more steps: use mobile.run/mobridge run; the daemon keeps the dataflow and a hot session.
+- Observe only when the screen is unknown, after navigation, when a match is ambiguous or when an action failed.
+- One verb per MCP act. A mutation must be verified; DISPATCHED does not mean VERIFIED.
+- A NodeRef must keep its snapshotId and generation; a plain stale NodeRef stops, only the original query may be resolved again.
+- mobile.run does not observe at the end by default; use returnState:true or mobridge run --return-state when needed.
+- Large evidence lives in the trace; a normal response has only the verdict, a compact state and the traceId.
+- Use mobile.run/mobridge run for dataflow; $name is resolved on the host only.
+- Every single mutation needs an operationId; every workflow has a workflowId and stable stepIds. When switching MCP↔CLI,
+  look up mobridge operation status <operationId>, or call mobile.run with plan={"control":"status"} and the workflowId.
+  The CLI equivalent: mobridge run --status --workflow-id <id>; to resume use the same plan/device/workflowId and --resume-token.
+- Do not retry/replay a mutation after a transport drop or RESULT_UNKNOWN. requestId only identifies a call;
+  operationId identifies the logical effect. The WAL keeps a tombstone for 5 minutes; an old unresolved entry becomes EXPIRED_UNKNOWN and is never turned into a new command.
+- A workflow checkpoint lives at most 24 hours and stores only an HMAC plan hash and verdict/step ids, never the plan or secrets. After a daemon restart, status returns a fresh resumeToken;
+  resume only with the same workflowId, deviceId, plan hash and token.
+- Do not call adb, uiautomator, coordinates or adb shell input in the semantic flow.
+- App control has no per-package authorize/allowlist/denylist. Explicit device identity, fixed argv,
+  safety confirmation and the runtime-permission policy still apply; there is no app authorize command.
+- Responses use transport: accessibility for semantic/gesture actions and transport: adb for fallback/app steps. A coordinate gesture always has verification.level: unverified.
+- Prefer valueRef/a user-approved secret broker for secrets; the CLI can read stdin. Do not pass secrets in argv,
+  do not use env as the default, and never put plaintext in a workflow checkpoint, trace or audit.
+- FLAG_SECURE only blocks capture/vision; if semantics still work, keep using the semantic path.
+- Closing an ad: BACK is only the fast path; report success only after the foreground Activity has left the ad. If the ad is still there, use assisted capture/vision;
+  never click a CTA and never tap from an old screenshot.
+
+## Routing (the daemon picks the executor, the agent does not)
+
+- Two separate sensors: screen observe = semantic JSON from Accessibility (no image); screen capture = real pixels (the image stays in RAM and returns a captureId). Capture only when you need to look (colour, icon, canvas, ad, missing semantics): screen capture defaults to a small preview to understand the layout; to read small text/icons use --roi x,y,w,h (native resolution, screen coordinates) instead of recapturing the whole screen; screen act is for acting, not for reading the screen. The old observe/shot/tap syntax still works but the guidance uses only screen ....
+- Semantic UI (find/click/type/scroll/BACK/HOME/wait) runs through Accessibility; package/process/permission/settings/log/perf run through ADB; opening an app, permission flows, notifications and ads are hybrid; canvas/games/unlabeled icons use vision.
+- With a clear goal call one act directly; find is only for checking or when ambiguous. Several steps: mobile.run/mobridge run or mobridge session --jsonl; one-shot CLI is for single operations only.
+- permission respond answers the dialog that is showing (resource-id, not pm grant); permission set changes state with pm grant/revoke and reads it back to verify. The two do not replace each other.
+- NEEDS_VISION: read the current capture (it has a captureId), pick a point on the image, then act CLICK {at:{captureId,x,y}} (dynamic UI such as ads/video: stalePolicy VISUAL_DYNAMIC); an old image gives STALE_CAPTURE. Never guess coordinates. Find by colour: capture {color:{hex}} → colorMatch. A control without a node: capture {scan:{}} → regionScan.regions[] (regionId, bounds, position, semanticNode, at): neutral facts that do not name the icon. Look at the image, choose a region, act CLICK {at}; if unsure it stays NEEDS_VISION, do not guess.
+- Do not change executor after a dispatch that may have run (timeout/dropped connection): the result is RESULT_UNKNOWN, look up the operation status, do not resend over ADB.
+- Do not use raw adb when a typed command exists. mobridge capabilities [--family F] lists each op's executor, replay class and verification.
+
+## Choose the tool by goal
+
+- One known goal with visible text: one command, e.g. `mobridge screen act click --text "Login" --verify auto`.
+- Several steps: `mobridge run plan.jsonl`, or chain commands with `&&`. Long chains: `mobridge session --jsonl` (input lines {"id","argv":[...]}, output lines {"id","exit","output"}) so you do not pay a process spawn per command.
+- Unknown screen: `mobridge screen observe`. Look only when needed: `mobridge screen capture`.
+- Stuck on an ad, canvas or unlabeled icon: `mobridge screen capture`, then `mobridge screen act at --capture <captureId> --x X --y Y`; for a full-screen ad: `mobridge ad dismiss`.
+- The CLI and MCP share one daemon (no separate WebSocket), but every CLI call still pays process start-up; do not run dozens of single commands when one JSONL plan does the job.
+- In `a && b || c`, `||` runs when a OR b fails, not only when a fails; use `if` to branch.
+
+## CLI defaults (verified)
+
+- `--match` defaults to NORMALIZED_EXACT. When the on-screen text is longer than the query you get NODE_NOT_FOUND: use `--match CONTAINS` deliberately and accept the AMBIGUOUS_MATCH risk; do not enable it by default.
+- A click by query already waits for the node up to 1500 ms (4000 ms when the foreground is SystemUI); `--wait-ms <0-10000>` waits longer, `--wait-ms 0` turns the wait off.
+- `--verify auto` picks the policy from the action type. DISPATCHED is not VERIFIED.
+- A node without CLICK (plain text or icon): `--allow-gesture` taps the node centre by coordinates. It requires a `--verify` policy that checks the screen changed, never DISPATCH_ONLY. Use it only when needed; an ambiguous parent is still refused.
+- `screen act at`: `--stale-policy strict` is the default; use `dynamic` when the screen has video, ads or animation. `--space image|screen` selects the coordinate space (default image; the capture result carries a coordinateGuide).
+- `screen capture` defaults to a small image (scale 0.5): for small text use `--mode detail` or `--roi x,y,w,h`. The file format follows the `-o` extension (.png, .jpg, .webp) or `--format png|jpeg|webp`.
+- `screen observe --app-only` drops the status bar and unfocused system chrome (on by default in MCP, off by default in the CLI). Content below the status bar, such as a heads-up notification, is kept.
+- `type --secret` or `--secret-env VAR` keeps passwords out of argv.
+- `--nth <n>` and `--within <json>` narrow down duplicate matches.
+
+## Valid JSONL steps (one step per line, unique ids)
+
+{"id":"s1","open":"com.example.app"}
+{"id":"s2","tap":{"text":"Skip"}}
+{"id":"s3","wait":{"condition":{"nodeExists":{"text":{"value":"Home","match":"CONTAINS"}}},"timeoutMs":3000}}
+{"id":"s4","type":{"field":"com.example.app:id/email","text":"a@b.c"}}
+{"id":"s5","scroll":{"query":{"text":{"value":"Settings","match":"CONTAINS"}},"direction":"FORWARD"}}
+{"id":"s6","key":"BACK"}
+{"id":"s7","ad":"dismiss"}
+
+The `ad` step is VERIFIED when the ad is closed or there was no ad. If an ad is still up the plan stops PAUSED with a NEEDS_VISION yield (with a capture and closeCandidate): look at the image, close it by hand, then resume. A `wait` condition is always wrapped in nodeExists/nodeAbsent/anyOf/allOf, never a bare {"text":"Home"}.
+
+## Lesser-known commands
+
+- `mobridge diff --from <snapshotId> [--to <snapshotId>]` compares two snapshots (`--from` is required); `mobridge record START|STOP|STATUS|EXTRACT_FRAMES --mp4-path f.mp4`.
+- `mobridge permission respond --decision ALLOW|ALLOW_WHILE_USING|ALLOW_ONCE|DENY|DENY_DONT_ASK` answers the dialog that is showing.
+- `mobridge operation status <operationId>`: look here after RESULT_UNKNOWN; never resend the mutation.
+- `mobridge open <package> --action APP_BRING_TO_FRONT`; `mobridge diag LOGCAT|CRASH|PERF|APP_INFO|STARTUP|BATTERY|NETSTATS|STORAGE|BUNDLE`.
+
+## Connection traps
+
+- MULTIPLE_DEVICES: with several devices pass `-d ANDROID:<serial>` or run `mobridge device use <serial>`; with exactly one device it is picked automatically and `-d` is not needed.
+- EXTERNAL_INSTRUMENTATION_ACTIVE: Appium/UiAutomator holds Accessibility; stop it, then connect again.
+- WAITING_FOR_USER_ACCESSIBILITY (Android 13+, Xiaomi, Oppo): Settings → Apps → MoBridge Runtime → ⋮ → Allow restricted settings, then enable Accessibility.
+- Recovery: `mobridge daemon restart` (after upgrading the package), `mobridge doctor --restart-adb`.
+
+## Typed commands (generated from the registry)
+
+- ad: mobridge-ad dismiss · mobridge-ad tap-close
+- app: app clear · app force · open
+- device: devices · health --preflight · health · doctor · doctor --restart-adb · connect · state
+- diag: diag
+- fallback: fallback cancel · fallback commit · fallback prepare · fallback status
+- input: gesture · type · key
+- operation: operation status · trace
+- package: app install · app uninstall
+- permission: permission set · permission set --revoke · permission respond
+- run: batch · run · scenario
+- screen: screen act click | type | scroll · screen act at · analyze · screen capture · diff · find · inspect · screen observe · record · screen act scroll · wait · watch
+
+## Examples
+
 mobridge devices --json
 mobridge connect -d ANDROID:<serial>
-mobridge tap --text Login --verify auto
+mobridge screen observe
+mobridge screen act click --text Login --verify auto
+mobridge screen capture
 mobridge run login.jsonl -d ANDROID:<serial>
 mobridge trace <traceId>
-```

package/README.md

@@ -14,6 +14,8 @@ npx -y mobridge-mcp install --yes   # wires every detected agent: Claude Code, C
 
 Drop `--yes` for a wizard. The installer backs up each agent config, removes older MoBridge registrations, extracts the signed companion APK, installs a user-owned launcher at `~/.mobridge/bin/mobridge` (add it to `PATH` to use the CLI), writes the agent guide to `~/.mobridge/AI-USAGE.md` and registers `mobridge mcp`. Restart your agent afterwards. `mobridge install --dry-run` previews; `mobridge remove` undoes it.
 
+The skill template ships with the package (staged at `~/.mobridge/skills/mobridge/SKILL.md`) but is never written into an agent's folders by default. `mobridge skill status` shows where it is installed; `mobridge skill install --agent <claude-code|codex|cursor|antigravity|all> [--dry-run]` installs or updates it, and `mobridge skill remove --agent …` deletes only a skill MoBridge wrote. A foreign `SKILL.md` of the same name is never overwritten, and an agent without a verified skill folder is reported `unsupported`. The result describes files on disk; it does not prove the agent loaded the skill. MCP works without it: tool descriptions, rejection messages and the `usage` field of `mobile.device.connect` carry the same guidance. `mobridge guide --short` prints the quickstart.
+
 First connect is automatic: `mobile.device.connect` installs the companion app on the phone, enables its accessibility service through ADB and opens the channel. Nothing else to tap.
 
 ## How it works
@@ -122,7 +124,7 @@ Two or more steps: send a JSONL plan instead of many calls. The daemon keeps the
 | Answer a permission dialog | CLI `mobridge permission respond --decision ALLOW_WHILE_USING` (answers the dialog like a user). `permission set <pkg> CAMERA` changes the state directly via ADB and reads it back. They are not interchangeable. |
 | Close an ad | CLI `mobridge ad dismiss`. It tries BACK, then assisted capture; it never taps a call-to-action. Exit 8 = pick the close point from the returned capture, then `mobridge ad tap-close`. |
 | Install / force-stop / uninstall | CLI `mobridge app install <file.apk>` (copies it into `MSM_APK_DIR` and reads the package id with aapt2/aapt, from PATH or the Android SDK build-tools), `app install <package> --apk <name>`, `app uninstall`, `app force`; `package install|uninstall` and `process stop` are aliases. Each reads the package/process state back. |
-| Wait / exit codes | `mobridge wait` that runs out of time returns status `TIMEOUT` and exit 10 (never VERIFIED/0). Exit codes: 0 VERIFIED, 1 FAILED, 2 DISPATCHED, 3 RESULT_UNKNOWN, 4 needs setup, 5 ambiguous, 6 policy, 7 transport, 8/9 `ad`, 10 TIMEOUT. |
+| Wait / exit codes | `mobridge wait` that runs out of time returns status `TIMEOUT` and exit 10 (never VERIFIED/0). Exit codes: 0 VERIFIED, 1 FAILED, 2 DISPATCHED, 3 RESULT_UNKNOWN, 4 needs setup, 5 ambiguous, 6 policy, 7 transport, 8/9 `ad`, 10 TIMEOUT. Exit 2 means "sent, effect unproven", so do not chain on it with `&&` without a `--verify` policy; `mobridge open <pkg>` returns 0 when the package is already in front. `mobridge daemon restart` replaces a stale daemon (use after upgrading the package). `mobridge screen act key` takes `BACK`, `HOME`, `RECENTS` or `NOTIFICATION_SHADE`, positional or `--key`. |
 | Diagnose | CLI `mobridge diag LOGCAT|CRASH|BATTERY|NETWORK|DISPLAY|POWER`. |
 | Anything missing | `mobridge capabilities [--family F]` lists every operation, its executor, replay class and verification. |