mobridge-mcp 0.9.2 → 0.10.0

package/skills/mobridge-debugging/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: mobridge-debugging
+description: Use when a MoBridge call fails, times out, is ambiguous, flaky or stuck, or returns an error.code
+version: 1.0.0
+---
+
+# MoBridge debugging
+
+Turn an `error.code` or a strange result into the one next step. Read the error body first: it already carries
+`cause`, `recoverable`, `agentAction`, `userAction` and `recovery[]` for known codes. Follow them in order.
+
+## When to use
+
+- A tool or command returns `status: FAILED`, `TIMEOUT`, `RESULT_UNKNOWN`, or an `error`.
+- An action reports `DISPATCHED` but the screen did not change, or the same action keeps repeating (`stuck`).
+- A flow worked before and is now flaky, slow or blocked.
+
+## Workflow
+
+1. Read `error.code`, `error.message`, `error.details`, `recovery[0]`, and whether `recoverable` is true.
+2. Find the family below and open the matching reference for the full table.
+3. Apply exactly one fix, then retry once. Never retry a mutation after `RESULT_UNKNOWN` (see below).
+4. Still failing: collect evidence with `mobridge health --preflight`, `mobridge doctor` and `mobridge trace <traceId>`.
+5. Report the code, the `traceId`, `details.diagnostics` and what you already tried. Do not loop.
+
+```bash
+mobridge health --preflight
+mobridge doctor
+mobridge doctor --fix
+mobridge trace <traceId>
+mobridge diag LOGCAT --package com.example.app
+```
+
+`health --preflight` prints a verdict (`ready`, `degraded`, `blocked`) and ordered `nextSteps`: a `Run:` line is one
+command you may run, a `Guidance:` line is something only the person can do. `doctor --fix` previews the repair and
+`doctor --fix --apply` runs it (it only reconnects and re-checks).
+
+## Families
+
+| Family | Typical codes | Open |
+|---|---|---|
+| Connect, adb, device selection | `ADB_NOT_FOUND`, `DEVICE_OFFLINE`, `DEVICE_UNAUTHORIZED`, `MULTIPLE_DEVICES`, `DEVICE_BINDING_MISMATCH` | `references/connection-errors.md` |
+| Companion app and Accessibility | `COMPANION_MISSING`, `COMPANION_NOT_READY`, `ACCESSIBILITY_ENABLE_BLOCKED`, `EXTERNAL_INSTRUMENTATION_ACTIVE` | `references/connection-errors.md`, `mobridge-companion-setup` |
+| Finding the target | `NODE_NOT_FOUND`, `AMBIGUOUS_MATCH`, `STALE_NODE_REF`, `VISION_REQUIRED` | `references/action-errors.md` |
+| Verification and results | `DISPATCHED`, `VERIFY_TIMEOUT`, `RESULT_UNKNOWN`, `IDEMPOTENCY_MISMATCH` | `references/action-errors.md` |
+| Policy and permissions | `POLICY_BLOCKED`, `ACTION_REJECTED`, `PROTECTED_CONTROL_PLANE` | `references/action-errors.md`, `mobridge-app-control` |
+| Concurrency and workflows | `BUSY`, `DEVICE_BUSY`, `LOCK_TIMEOUT`, `WORKFLOW_NOT_FOUND`, `STALE_CAPTURE` | `references/action-errors.md` |
+
+## The five failures you will meet most
+
+1. `RESULT_UNKNOWN`: the action may or may not have happened (the link dropped after dispatch). Do not resend.
+   `mobridge operation status <operationId>`, then `mobridge screen observe`, then decide.
+2. `AMBIGUOUS_MATCH`: several nodes fit. Narrow with `--role`, `--nth`, `--within`, or `--resource-id`. Do not use the
+   first candidate.
+3. `NODE_NOT_FOUND`: wrong text, wrong match mode or the node is off screen. Default match is `NORMALIZED_EXACT`;
+   a longer on-screen string needs `CONTAINS`. Scroll with `mobridge find --text ... --scroll`. For a control with no
+   text try `--label`. If the screen has no accessibility tree you get `VISION_REQUIRED`, not `NODE_NOT_FOUND`.
+4. `DISPATCHED` but nothing changed: the node has no CLICK action, an overlay covers it, or the tree did not change
+   (WebView, canvas). Read `observation.treeEvidence` and `error.details.targetDiagnosis`. A non-clickable node
+   needs `--allow-gesture` with a verifying policy, or look at the pixels (`mobridge-surfaces`).
+5. `BUSY`: another state-changing call holds the device. Reads share the device; a read that arrives during a write
+   is refused. Wait for the write, then retry the read. Health and status calls stay available while busy.
+
+## Stuck and flaky
+
+- `stuck {repeatCount, hint}` after three identical actions with an unchanged tree: stop repeating. Observe,
+  change the query or the surface (capture and `act at`), or ask the user.
+- `targetDiagnosis.state`: `moved` and `covered` are proven; `gone` means a complete capture held no match;
+  `ambiguous` means several fit; `unknown` always names a reason such as `TARGET_OFFSCREEN` or `TREE_TRUNCATED`.
+- Wireless adb drops kill the transport. A read retries by itself; a mutation reports `RESULT_UNKNOWN`. Prefer USB
+  (`mobridge-devices`).
+- Another tool holding UiAutomation (Appium, uiautomator, a test runner) gives `EXTERNAL_INSTRUMENTATION_ACTIVE`.
+  Stop it, then `mobridge connect`.
+- After upgrading the package run `mobridge daemon restart`, then `mobridge connect`.
+
+## Evidence ladder
+
+| Need | Command |
+|---|---|
+| What did the last call do | `mobridge trace <traceId>` |
+| Is the phone ready | `mobridge health --preflight` |
+| Environment problems | `mobridge doctor` |
+| App crash, ANR, memory | `mobridge diag CRASH --package com.example.app`, `mobridge diag PERF --package com.example.app` |
+| App log | `mobridge diag LOGCAT --package com.example.app` |
+| Show me the screen | `mobridge screen capture` |
+| What changed between two reads | `mobridge diff --from <snapshotId> --to <snapshotId>` |
+
+## Do not
+
+- Do not repeat a mutation after `RESULT_UNKNOWN` or a dropped link.
+- Do not switch to raw `adb shell input` to "get around" a failure: it skips verification and the daemon will not
+  know what happened.
+- Do not edit the plan to hide a failing step. Fix the query or the surface.
+- Do not guess a package, a coordinate or a device. Ask, or read it from the tool.
+
+## Verification
+
+- The fix is proven only when the same call returns `VERIFIED` (or `health --preflight` reports ready) without a retry.
+- Record the `traceId` of the failing call; `mobridge trace <traceId>` is the evidence to quote.

package/skills/mobridge-debugging/references/action-errors.md

@@ -0,0 +1,59 @@
+# Action, verification, policy and workflow errors
+
+These codes appear while acting, after the phone is connected. Connection and setup codes are in
+`connection-errors.md`.
+
+## Targeting
+
+| Code | Meaning | Do |
+|---|---|---|
+| `NODE_NOT_FOUND` | No node matched the query. | Check text and match mode, scroll (`find --scroll`), try `--label`, observe. |
+| `AMBIGUOUS_MATCH` | Several nodes match, or several scroll containers of similar size. | Narrow with `--role`, `--nth`, `--within`, `--resource-id`. For scrolling pass an explicit container query. |
+| `STALE_NODE_REF` | The screen changed since the NodeRef was read. | Resolve the original query again. Never revive an old ref. |
+| `WEAK_REFERENCE_UNRESOLVABLE` | The ref has no usable locator any more. | Query again from scratch. |
+| `VISION_REQUIRED` | The foreground has no usable accessibility tree (game, canvas, video). | `mobridge screen capture`, pick a point, `mobridge screen act at --capture <id> --x X --y Y`. |
+| `NEEDS_VISION` | Semantics are not enough to decide. | Same as above. |
+| `STALE_CAPTURE` | The screen no longer matches the capture you tapped on. | Capture again. For video or ads use `--stale-policy dynamic`. |
+| `ACTION_UNSUPPORTED` | The node does not support that action (for example `SCROLL_FORWARD` at the end of a list, or CLICK on text). | At a list end scroll the other way or stop. For CLICK use the clickable parent, `--allow-gesture`, or `act at`. |
+
+## Verification and results
+
+| Code or status | Meaning | Do |
+|---|---|---|
+| `DISPATCHED` | Sent, not proven. | Add `--verify`, or `wait` for the expected node. |
+| `VERIFY_TIMEOUT` | The predicate was not met in time. | Observe; the action may still have worked. Use a better policy or a longer wait. |
+| `NO_EFFECT` | The action ran and nothing changed. | Different target or surface. |
+| `RESULT_UNKNOWN` | Dispatched, effect unknown (link dropped). | Never resend. `mobridge operation status <operationId>`, then observe. |
+| `EXPIRED_UNKNOWN` | An old unknown operation timed out of the journal. | Treat as unknown. Observe. Never turn it into a new command. |
+| `IDEMPOTENCY_MISMATCH` | The same `operationId` was reused with a different payload. | Use a new `operationId` for a new action. |
+| `OPERATION_ID_REQUIRED` | A mutation arrived without an identity. | Pass `--operation-id` (MCP: `operationId`). |
+
+## Policy and safety
+
+| Code | Meaning | Do |
+|---|---|---|
+| `POLICY_BLOCKED` | A policy gate refused it (install path, permission allowlist, protected package). | Read `recovery`: it names the switch to turn on in the companion app. See `mobridge-app-control`. |
+| `ACTION_REJECTED` | Bad input, or input aimed at the MoBridge Runtime app itself. | Fix the field the message names. Input to the companion's own screen is refused on purpose: ask the person. |
+| `PROTECTED_CONTROL_PLANE` | The target is MoBridge's own companion. | Use the companion's own UI. Not overridable. |
+| `CRITICAL_SYSTEM_TARGET` | A core system package (settings, systemui, permission controller). | Only with an explicit `--allow-critical-system`, and only if you truly mean it. |
+| `USER_CONFIRMATION_REQUIRED` | A person must confirm. | Ask them. |
+| `AMBIGUOUS_DEVICE` | A destructive call named no device. | Pass `-d ANDROID:<serial>`. |
+| `CAPTURE_BLOCKED_SECURE_WINDOW` / `SECURE_WINDOW` | The window is flagged secure. | Capture is refused; semantics may still work. |
+
+## Concurrency, workflows, daemon
+
+| Code | Meaning | Do |
+|---|---|---|
+| `BUSY` | A state-changing call is running; this read would see mixed state. | Wait, retry the read. |
+| `DEVICE_BUSY` | The bounded mutation queue is full. | Wait for the active workflow. |
+| `LOCK_TIMEOUT` | The device lock was not acquired in time. Nothing was dispatched. | Retry after the active operation finishes. |
+| `WORKFLOW_NOT_FOUND` | No checkpoint for that workflow id. | Check the id; it expires after 24 hours. |
+| `WORKFLOW_IDENTITY_MISMATCH` / `WORKFLOW_PLAN_MISMATCH` | Resume with a different device or plan. | Resume only with the same workflow id, device, plan and token. |
+| `RESUME_TOKEN_REQUIRED` | Resume needs the token from the paused result. | Pass `--resume-token`. |
+| `DAEMON_BUILD_MISMATCH` | The running daemon is an older build. | `mobridge daemon restart`. |
+| `INVALID_JSON` | A `--query`, plan line or condition is not valid JSON. | Quote it; wrap conditions in `nodeExists`. |
+| `METHOD_NOT_FOUND` | Unknown command or action. | Read `recovery`; run `mobridge --help`. |
+
+## Reading a refused input
+
+Many `ACTION_REJECTED` bodies list the allowed values and a valid example. Fix that one field and retry once.

package/skills/mobridge-debugging/references/connection-errors.md

@@ -0,0 +1,31 @@
+# Connection and setup errors
+
+Every code below comes with `cause`, `recoverable`, `agentAction` and, when a person must act, `userAction` in the error body. Do exactly the matching step; do not try things at random.
+
+| `error.code` | Cause | Self-heals or plain retry | What to do |
+|---|---|---|---|
+| `ADB_NOT_FOUND` | `adb` is not installed or not on PATH. | no | 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. | yes | 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. | no | 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. | yes | 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. | no | 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. | no | 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. | no | 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. | yes | 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. | no | 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. | yes | Run `mobridge connect`; it updates the companion once. |
+| `COMPANION_INSTALL_BLOCKED` | The phone refused the USB install (OEM setting or confirmation prompt). | no | 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). | no | 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"). | yes | 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. | yes | Run `mobridge connect`; it restarts the companion. |
+| `ACCESSIBILITY_DISABLED` | The Accessibility service is off. | yes | 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. | no | 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. | no | 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. | yes | Wait a few seconds and run `mobridge connect`. |
+| `EXTERNAL_INSTRUMENTATION_ACTIVE` | Another tool holds UiAutomation (uiautomator, a test runner, another agent). | no | 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. | yes | 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. | yes | 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. | no | Never repeat it. Run `mobridge operation status <operationId>` and observe the screen. |
+| `AMBIGUOUS_MATCH` | More than one node matches the query. | no | Narrow the query using `candidates`; never click the first. |
+| `NEEDS_VISION` | Semantics are not enough to decide. | no | Take `mobile.screen.capture`, look at the image and act with `at`. |
+| `UNSUPPORTED_PLATFORM` | iOS was requested. | no | Use an Android device. |

package/skills/mobridge-devices/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: mobridge-devices
+description: Use when choosing a phone, working with several devices, USB versus wireless adb, or a lost connection
+version: 1.0.0
+---
+
+# MoBridge devices and transport
+
+Rule: the answer comes from the phone you named, or the call fails. No call ever falls back to another phone.
+
+## When to use
+
+- More than one phone is attached, or you are unsure which one a command will hit.
+- You want to move from USB to wireless adb, or the link dropped.
+- `MULTIPLE_DEVICES`, `AMBIGUOUS_DEVICE`, `DEVICE_NOT_FOUND`, `DEVICE_OFFLINE`, `DEVICE_UNAUTHORIZED`,
+  `DEVICE_BINDING_MISMATCH`, `TRANSPORT_DEGRADED` or `WS_CONNECTION_LOST`.
+
+## Workflow
+
+1. `mobridge devices` to list what is attached and usable.
+2. Name the phone on every call, or save it once with `mobridge device use <serial>`.
+3. Prefer USB for long plans and mutations; use wireless only for short reads.
+4. On a dropped link follow "Recover a lost connection" below, then apply `mobridge-companion-setup` if the companion is the problem.
+
+## Choose a phone
+
+```bash
+mobridge devices
+mobridge connect -d ANDROID:<serial>
+mobridge device use <serial>
+mobridge device current
+mobridge device clear
+```
+
+| Attached | You pass | Result |
+|---|---|---|
+| one usable | nothing | that phone |
+| two or more usable | nothing | `MULTIPLE_DEVICES` with `details.candidates` |
+| any | a named, usable phone | that phone |
+| any | a named, absent phone | `DEVICE_NOT_FOUND` |
+| any | a named, offline or unauthorized phone | `DEVICE_OFFLINE` / `DEVICE_UNAUTHORIZED` |
+
+- With several phones pass `-d ANDROID:<serial>` on every call (MCP: `deviceId`), or save one with
+  `mobridge device use <serial>` once. Never pick one yourself from the candidates without asking when it matters.
+- Destructive calls (app control, `app ...`) always need an explicit device.
+- Each phone has its own binding proof: a nonce is written to that serial and must come back from the companion
+  socket. A stale forward to another phone fails as `DEVICE_BINDING_MISMATCH`; run `mobridge connect -d ANDROID:<serial>` again.
+- The registry serialises state-changing calls per device and runs in practice as one session. Do not assume two
+  phones can be driven in parallel from one daemon without naming each.
+
+## USB or wireless
+
+| | USB | Wireless adb (same Wi-Fi) |
+|---|---|---|
+| Setup | cable, USB debugging on, accept the key | `adb pair` / `adb connect` on the computer first |
+| Stability | best | a link drop kills the transport and the companion's session |
+| Use for | long plans, mutations, anything you must trust | quick reads, demos |
+
+Prefer USB for long flows and mutations. On wireless, check `mobridge health --preflight` before a plan and expect
+`TRANSPORT_DEGRADED` or `WS_CONNECTION_LOST` if the Wi-Fi blips: a read retries by itself; a mutation reports
+`RESULT_UNKNOWN`, so look up its `operationId` instead of resending.
+
+Different network and no cable: only an overlay VPN (WireGuard or Tailscale) with `MSM_ADB_REMOTE=host:5555`, or a
+relay, gives a route. Without one there is no route; ask the person to connect a cable.
+
+## Recover a lost connection
+
+1. `mobridge health --preflight` for the verdict and ordered `nextSteps`.
+2. `mobridge connect -d ANDROID:<serial>` once. It reinstalls nothing that is already right.
+3. Still down: `mobridge doctor`, then `mobridge doctor --fix`, and with the person's yes `mobridge doctor --fix --apply`.
+4. After upgrading the package or when a stale daemon answers: `mobridge daemon restart`, then connect.
+5. Check the daemon itself with `mobridge daemon status`.
+
+```bash
+mobridge health --preflight
+mobridge connect -d ANDROID:<serial>
+mobridge doctor
+mobridge daemon status
+mobridge daemon restart
+```
+
+## Rules for several phones
+
+- Name the phone on every call. If you lose track, run `mobridge devices` and `mobridge device current`.
+- Do not carry a NodeRef, a capture id or a workflow id from one phone to another.
+- When two phones share an operation id, reuse is refused; give each action its own `operationId`.
+- A foreground-only fact (screen contents) is per phone. Observe again after switching.
+
+References: `references/wireless-adb.md`.
+
+## Verification
+
+- `mobridge device current` shows the saved default; `mobridge health --preflight` shows the phone you will hit is ready.
+- The `device` field of every response must match the phone you meant.

package/skills/mobridge-devices/references/wireless-adb.md

@@ -0,0 +1,35 @@
+# Wireless adb
+
+MoBridge uses adb only to provision (install the companion, enable Accessibility, forward a port). Once connected,
+the runtime talks to the companion over a WebSocket on the forwarded port. Wireless adb therefore only has to
+survive provisioning; the session then depends on that forward staying alive.
+
+## Android 11 and newer (pairing code)
+
+On the phone: Developer options, Wireless debugging on, Pair device with pairing code. On the computer:
+
+```bash
+adb pair <ip>:<pairing-port>
+adb connect <ip>:<connect-port>
+adb devices
+```
+
+Then run `mobridge devices` and `mobridge connect -d ANDROID:<serial>` where the serial is what `adb devices` shows
+(usually `<ip>:<port>`).
+
+## Older phones
+
+Connect once by USB, run `adb tcpip 5555`, unplug, `adb connect <ip>:5555`.
+
+## Staying connected
+
+- Keep the screen on and the phone on the same network. Sleep and Wi-Fi roaming drop the link.
+- A drop appears as `TRANSPORT_DEGRADED` or `WS_CONNECTION_LOST`. Reads recover; for a mutation use
+  `mobridge operation status <operationId>`.
+- If the address changes, adb needs a new `adb connect`, and MoBridge needs a new `mobridge connect`.
+- A phone that is connected both by USB and wireless shows up twice: name the serial you want.
+
+## Not on the same network
+
+There is no route without a cable. Overlay networks (WireGuard, Tailscale) work with `MSM_ADB_REMOTE=host:5555`
+set in the environment of the daemon. Ask the person before setting it.

package/skills/mobridge-efficiency/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: mobridge-efficiency
+description: Use when optimizing MoBridge for fewer tokens, faster runs, parallel reads, burst capture or long plans
+version: 1.0.0
+---
+
+# MoBridge efficiency
+
+How to get the most out of each call: fewer tokens, fewer round trips, no wasted waits.
+
+## When to use
+
+- A flow is slow, verbose or burns context on screenshots.
+- You are about to run dozens of single commands, poll in a loop, or read the whole tree after every tap.
+- You need a short video-like view of a transition.
+
+## Workflow
+
+1. Start from `mobridge-core` and act by query without a preliminary observe.
+2. Pick the cheapest sensor from the ladder; capture only when meaning is missing (then apply `mobridge-surfaces`).
+3. Batch two or more steps into one plan (apply `mobridge-recipes`).
+4. Measure with the `timing` spans before changing anything else.
+
+## The token ladder (cheapest first)
+
+| Need | Use | Cost |
+|---|---|---|
+| Act on something you can name | `mobridge screen act click --text "X" --verify auto` (no observe) | the verdict only |
+| Know what is tappable | `mobridge screen observe --actionable` | small JSON |
+| Read the screen | `mobridge screen observe` | semantic JSON, no image |
+| See pixels | `mobridge screen capture` | small image (scale 0.5) |
+| Read small text | `mobridge screen capture --mode detail` or `--roi x,y,w,h` | native resolution of a region |
+| Watch a transition | `mobridge screen burst --duration 2 --interval 400` | frames in daemon memory, fetched one by one |
+
+Rules of thumb:
+
+- Observe only when the screen is unknown, after navigation, when a match is ambiguous, or when an action failed.
+- Never observe at the end of a plan unless you need the state: use `--return-state` on `run` when you do.
+- Prefer `observe --actionable` to a full read. In MCP `app-only` is on by default and drops status-bar noise.
+- A capture is the last resort for understanding; try the semantic path first. Games, canvas and ads need pixels.
+- Use `--format webp` for smaller files; the `-o` extension also sets the format.
+
+```bash
+mobridge screen observe --actionable
+mobridge screen capture --mode detail
+mobridge screen capture --roi 0,0,1080,400 -o top.png
+mobridge screen burst --duration 2 --interval 400
+mobridge screen burst --frame <burstId>.3 -o frame3.webp
+```
+
+## Fewer round trips
+
+- Two or more steps: one `mobridge run plan.jsonl` or `mobile.run`. The daemon keeps a hot session and passes data
+  between steps without sending it through the model.
+- Many commands from a script: `mobridge session --jsonl`. Input lines `{"id":"1","argv":["screen","observe"]}`, output
+  lines `{"id":"1","exit":0,"output":{...}}`. One process, no spawn per command.
+- Every CLI call still pays process start-up. Do not issue a hundred single commands when one plan does the job.
+- A click by query already waits up to 1500 ms (4000 ms on system UI). Add `--wait-ms <0-10000>` instead of a manual
+  sleep. `--wait-ms 0` turns it off.
+- Wait on a condition, never on a timer: `mobridge wait '<condition>'` or `mobridge watch --timeout-ms 3000`.
+
+## Parallel work
+
+- Reads share the device: observe, capture, inspect and state may run at the same time.
+- State-changing calls run one after another per device. A read that arrives during a write is refused with `BUSY`;
+  retry it after the write. Do not parallelise mutations.
+- Several phones: each call names its phone, and the calls for different phones are independent.
+
+## Burst instead of video
+
+`screen burst --duration S --interval MS` takes ordered screenshots on a wall-clock schedule and keeps them in
+daemon RAM, never on disk.
+
+| Limit | Value |
+|---|---|
+| Duration | up to 60 s |
+| Frames | up to 120 |
+| Memory | 48 MiB, oldest frames evicted first |
+| Held for | 120 s, then dropped |
+| Minimum interval | 350 ms (Android throttles screenshots near 333 ms) |
+
+The result lists frames with `seq`, `tMs`, `frameId` and `changedFromPrev`, without images. Fetch one with
+`--frame <burstId>.<n>`, or a range `<burstId>.<a>-<b>`. Frames cannot be used with `act at`; capture again to tap.
+
+## Habits that save the most
+
+1. Act with a query directly; skip the preliminary observe.
+2. Verify with the right policy so you do not need a second read.
+3. Use `app` in the act result instead of observing to see where a tap landed.
+4. Cache nothing across navigation; a NodeRef from before a screen change is stale.
+5. Stop a failing loop at `stuck` instead of retrying.
+
+References: `references/measuring.md`.
+
+## Verification
+
+- Compare `timing` and output size before and after a change; keep it only if one of them drops and the verdict stays `VERIFIED`.
+- Do not claim a speed-up without a measured run on the target app.

package/skills/mobridge-efficiency/references/measuring.md

@@ -0,0 +1,29 @@
+# Measuring cost
+
+Every response carries `timing`: CLI start-up, IPC, daemon queue, device RPC, resolve, verification and
+serialization spans. Read them before guessing what is slow.
+
+| Span | What a high value means |
+|---|---|
+| CLI `moduleReadyMs` / `ensureDaemonMs` | Process start-up. Batch commands (`run`, `session --jsonl`). |
+| `daemonQueueMs` | Another mutation was running. Serialise less, or wait for it. |
+| `deviceRpcMs` | The phone is slow: heavy screen, wireless link, battery saver. |
+| `resolveNodeMs` | The tree is large. Narrow with `--within` or `--resource-id`. |
+| `verificationMs` / `uiStabilityMs` | The screen keeps animating. Use `watch`, or verify on a stable node. |
+
+## Quick experiments
+
+```bash
+mobridge screen observe --actionable --json
+mobridge screen observe --json
+mobridge screen capture --json
+```
+
+Compare the sizes of the three outputs for your screen. The semantic read is much smaller than a full tree dump and
+carries no image; a capture costs image tokens, so use it when pixels are the question.
+
+## Rules
+
+- Measure with real calls on the target app. Do not quote benchmark numbers from another phone or app.
+- Change one thing at a time, then compare `timing` and output size.
+- If a flow needs more than about ten commands, turn it into a plan before tuning anything else.

package/skills/mobridge-recipes/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: mobridge-recipes
+description: Use when chaining MoBridge steps, writing a JSONL plan, mixing CLI with MCP or saving and replaying a flow
+version: 1.0.0
+---
+
+# MoBridge recipes
+
+How to combine the CLI and MCP surfaces, and how to turn a manual flow into a plan that can be resumed,
+replayed and handed from one interface to the other.
+
+## When to use
+
+- A task needs two or more steps, a login, a form, a settings change or any repeatable flow.
+- You started in MCP and want a file, a batch or diagnostics from the CLI (or the reverse).
+- You want to save a verified flow so it can run again.
+
+## Workflow
+
+1. Apply `mobridge-core` for the single-step loop and `mobridge-devices` to name the phone.
+2. One step: act directly. Two or more steps: write a JSONL plan and run it once.
+3. Give the run a stable `workflowId` and step ids so it can be resumed or looked up from CLI or MCP.
+4. Read `mobridge run --status` on failure; resume only from the reported step, never replay a mutation.
+5. Save a flow that worked as a scenario; apply `mobridge-debugging` when it fails.
+
+## Choose the surface
+
+| Goal | Use |
+|---|---|
+| One known action with visible text | `mobridge screen act click --text "Login" --verify auto` or `mobile.screen.act` |
+| Two or more steps | `mobridge run plan.jsonl` or `mobile.run` |
+| Many CLI commands in a row | `mobridge session --jsonl` (one process, no spawn per command) |
+| Inline image for the model | MCP `mobile.screen.capture` |
+| Files, streams, diagnostics, recordings | CLI |
+| Unknown screen | `mobridge screen observe`, then decide |
+
+Chaining shell commands with `&&` is fine, but each call pays process start-up. In `a && b || c` the `||` branch
+runs when a OR b fails: use `if` to branch.
+
+## Plans (JSONL)
+
+One step per line, unique `id`, stable across retries. A `wait` condition is always wrapped.
+
+```json
+{"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"}
+```
+
+Run it with a workflow id, check it, resume it:
+
+```bash
+mobridge run plan.jsonl --workflow-id wf_login_0001
+mobridge run --status --workflow-id wf_login_0001
+mobridge run plan.jsonl --workflow-id wf_login_0001 --resume-token <token>
+mobridge run plan.jsonl --workflow-id wf_login_0002 --return-state
+```
+
+- The run stops at the first step that is not verified and reports `PAUSED` with a `resumeToken` and `notRun`.
+- A `scroll` step scrolls until the query is found; it is not a single swipe.
+- By default a run does not observe at the end. Add `--return-state` (MCP `returnState: true`) when you need it.
+- A checkpoint lives at most 24 hours and stores only a plan hash and step ids, never the plan or secrets.
+  Resume only with the same workflow id, device, plan and token.
+
+More step shapes and dataflow: `references/jsonl-steps.md`.
+
+## CLI and MCP on the same task
+
+Both go through one daemon, so a flow can start in one and finish in the other.
+
+1. Give every single mutation an `operationId` and every plan a `workflowId`.
+2. When you switch interface, look the work up instead of repeating it:
+   - mutation: `mobridge operation status <operationId>`;
+   - plan: `mobridge run --status --workflow-id <id>`, or MCP `mobile.run` with `plan: {"control":"status"}`.
+3. Reuse of an `operationId` with the same payload returns the receipt with `idempotentReplay: true`.
+
+## Save a flow as a scenario
+
+```bash
+mobridge scenario list
+mobridge scenario save login-flow --intent "log in with the test account" --steps '[{"id":"s1","action":"CLICK","find":{"query":{"text":{"value":"Login","match":"EXACT"}}},"verify":{"policy":"WINDOW_CHANGED"}}]'
+mobridge scenario get login-flow
+mobridge scenario run login-flow
+mobridge scenario delete login-flow
+```
+
+Scenario ids are lowercase letters, digits and hyphens. A saved scenario is a recording, not a guarantee: run it
+and read the verdicts. A scenario fails closed when a target is missing.
+
+## Recipes
+
+Login without leaking the password:
+
+```bash
+mobridge open com.example.app
+mobridge type --field com.example.app:id/email "user@example.com" --verify auto
+mobridge type --field com.example.app:id/password --secret --verify auto
+mobridge screen act click --text "Sign in" --verify auto
+```
+
+(`--secret` reads the value from stdin; `--secret-env VAR` reads an environment variable.)
+
+Read a list that scrolls:
+
+```bash
+mobridge screen observe --actionable
+mobridge scroll down
+mobridge screen observe --actionable
+mobridge diff --from <beforeSnapshot> --to <afterSnapshot>
+```
+
+Wait for a screen to settle after a tap:
+
+```bash
+mobridge screen act click --text "Continue" --verify WINDOW_CHANGED
+mobridge watch --timeout-ms 3000
+```
+
+Answer a system permission dialog that is on screen:
+
+```bash
+mobridge permission respond --decision ALLOW_WHILE_USING
+```
+
+## Pitfalls
+
+- Do not send a long run as dozens of CLI processes. One plan or one `session --jsonl` does it.
+- Do not reuse a step id inside a plan; the run reports a structured result but the status is ambiguous.
+- Do not branch on a `DISPATCHED` step as if it succeeded. Add a verify or a `wait` step.
+- A plan that mixes an `open` of an app with a different foreground app after launch can stay `DISPATCHED`: the
+  app opened another activity or package. Observe and wait on the expected node instead of assuming.
+
+## Verification
+
+- A plan is done when `run` reports every step `VERIFIED` (or the `--return-state` read shows the target screen).
+- After a failure, `mobridge run --status --workflow-id <id>` shows the last good step and the resume token.

package/skills/mobridge-recipes/references/jsonl-steps.md

@@ -0,0 +1,28 @@
+# JSONL step reference
+
+Every line is one JSON object with a unique `id` and exactly one verb key.
+
+| Verb | Shape | Notes |
+|---|---|---|
+| `open` | `{"id":"s1","open":"com.example.app"}` | Launch or bring to front. Verified by the foreground package. |
+| `tap` | `{"id":"s2","tap":{"text":"Skip"}}` | Same query fields as `find`. Add `"verify":{"policy":"WINDOW_CHANGED"}` when you know it. |
+| `type` | `{"id":"s3","type":{"field":"com.example.app:id/email","text":"a@b.c"}}` | `field` is the resource id of the input, `text` is the value to type. |
+| `wait` | `{"id":"s4","wait":{"condition":{"nodeExists":{...}},"timeoutMs":3000}}` | Wrapped condition only. |
+| `scroll` | `{"id":"s5","scroll":{"query":{...},"direction":"FORWARD"}}` | Scrolls until the query is found. |
+| `key` | `{"id":"s6","key":"BACK"}` | `BACK`, `HOME`, `RECENTS`, `NOTIFICATION_SHADE`. |
+| `find` | `{"id":"s7","find":{"query":{...}}}` | Resolves a node for later steps. |
+| `gesture` | `{"id":"s8","gesture":{"kind":"SWIPE","x":540,"y":1600,"x2":540,"y2":800,"durationMs":300}}` | Coordinates are unverified by nature. |
+| `capture` | `{"id":"s9","capture":{}}` | Takes a screenshot into daemon memory and returns a `captureId`. |
+| `diag` | `{"id":"s10","diag":{"kind":"LOGCAT","packageName":"com.example.app"}}` | Host-side diagnostics. |
+
+## Dataflow
+
+A step result can feed a later step. `$name` references are resolved on the host only, never sent to the model.
+Use them for ids and values that appear mid-flow; keep secrets out of plans.
+
+## Rules
+
+- Ids are unique and stable. Retrying a plan with the same workflow id reuses them.
+- A step that is only `DISPATCHED` stops the run unless it carries its own verify.
+- Unknown verbs are rejected with `ACTION_REJECTED` and the allowed shapes; fix the line and run again.
+- Keep plans short. Split a long flow at a natural checkpoint (a screen that is easy to wait on).