mobridge-mcp 0.9.2 → 0.10.0

package/integrity.json

@@ -1,4 +1,4 @@
 {
-  "buildId": "594f6bd-20261029141345",
-  "bundleSha256": "ac2a1a3415f59462022441285d1fb1f8e2c739dffa9789c9227305bc98cf0846"
+  "buildId": "4168178-20261029170722",
+  "bundleSha256": "2355be9209ed061f5481e363e7e1adf6ab670f13b42919f199145f47d8cd56aa"
 }

package/loader.cjs

@@ -14,7 +14,7 @@ const os = require("node:os");
 const path = require("node:path");
 const crypto = require("node:crypto");
 
-const BUILD_ID = "594f6bd-20261029141345"; // pack-npx stamps the real build id
+const BUILD_ID = "4168178-20261029170722"; // pack-npx stamps the real build id
 const ROOT = __dirname; // package root (loader.cjs sits here)
 const DIST = path.join(ROOT, "dist");
 const BUNDLE = path.join(DIST, "main.obf.cjs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobridge-mcp",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "MoBridge MCP — a stdio MCP server exposing on-device Android UIs as fast semantic read / observe / find / act / verify tools plus screenshots. Ships an installer that wires it into Claude Code, Claude Desktop, Cursor and Codex.",
   "keywords": [
     "mcp",
@@ -30,6 +30,7 @@
     "loader.cjs",
     "dist",
     "resources",
+    "skills",
     "integrity.json",
     "README.md",
     "AI-USAGE.md"

package/skills/VERSIONS.json

@@ -0,0 +1,34 @@
+{
+  "mobridge-app-control": {
+    "version": "1.0.1",
+    "digest": "1647b16f56ddad5d"
+  },
+  "mobridge-companion-setup": {
+    "version": "1.1.0",
+    "digest": "12a409e4d043a1c3"
+  },
+  "mobridge-core": {
+    "version": "1.0.0",
+    "digest": "24f729f499124b41"
+  },
+  "mobridge-debugging": {
+    "version": "1.0.0",
+    "digest": "d37ef00fcc3a80b9"
+  },
+  "mobridge-devices": {
+    "version": "1.0.0",
+    "digest": "57e4a93e339129c9"
+  },
+  "mobridge-efficiency": {
+    "version": "1.0.0",
+    "digest": "7042f9dd731fd563"
+  },
+  "mobridge-recipes": {
+    "version": "1.0.0",
+    "digest": "0d6ee3eeb4c82f53"
+  },
+  "mobridge-surfaces": {
+    "version": "1.0.0",
+    "digest": "9cdde1172e5a81f6"
+  }
+}

package/skills/mobridge-app-control/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: mobridge-app-control
+description: Use when installing, uninstalling, force-stopping, clearing data or granting permissions to apps via MoBridge
+version: 1.0.1
+---
+
+# MoBridge app control
+
+Write-side device management through typed, fixed-argument commands: force-stop, clear data, install, uninstall,
+grant and revoke runtime permissions. There is no raw shell and no free-text parameter anywhere in this surface.
+
+## When to use
+
+- You must install a build, remove an app, reset an app's data or change one runtime permission.
+- A command returned `POLICY_BLOCKED`, `CRITICAL_SYSTEM_TARGET`, `PROTECTED_CONTROL_PLANE` or `AMBIGUOUS_DEVICE`.
+- A permission dialog is on screen and you need to answer it.
+
+Do not use this for taps and typing (`mobridge-core`) or for connecting a phone (`mobridge-devices`).
+
+## Workflow
+
+1. Apply `mobridge-devices`: name the phone with `-d ANDROID:<serial>`; app control never guesses a device.
+2. Read the gate that blocks the action and the owner switch that lifts it (table below); ask the person to flip it on the phone.
+3. Run one command with the exact `--package`; do not chain destructive commands.
+4. Read back the state the command returns, then apply `mobridge-core` to continue in the app.
+
+## Ground rules
+
+- Every command here is destructive or side-effecting and needs an explicit device: `mobridge -d ANDROID:<serial> app ...`.
+  Without it you get `AMBIGUOUS_DEVICE`. The `-d` flag goes before `app`.
+- Act only on a package the user named. Never guess a package id; read it from `mobridge diag APP_INFO` or ask.
+- Each command reads the result back (`pm` exiting 0 is dispatch, not proof) and reports `CONDITION_MET` or says it
+  could not confirm. Do not report success from a dispatched command alone.
+- Every call is written to the app-control audit log.
+
+## Commands
+
+```bash
+mobridge -d ANDROID:<serial> app force --package com.example.app
+mobridge -d ANDROID:<serial> app clear --package com.example.app
+mobridge -d ANDROID:<serial> app install ./build/app-release.apk
+mobridge -d ANDROID:<serial> app uninstall --package com.example.app
+mobridge -d ANDROID:<serial> app grant --package com.example.app --permission android.permission.CAMERA
+mobridge -d ANDROID:<serial> app revoke --package com.example.app --permission android.permission.CAMERA
+mobridge -d ANDROID:<serial> permission set com.example.app CAMERA
+mobridge permission respond --decision ALLOW_WHILE_USING
+mobridge operation status <operationId>
+```
+
+| Command | Effect | Reversible |
+|---|---|---|
+| `app force` | Stops the app process | yes |
+| `app clear` | Deletes the app's user data | no |
+| `app install <file.apk>` | Installs or replaces (`-r`); reads the package id with aapt2 or aapt | by uninstalling |
+| `app uninstall` | Removes the app and its data | no |
+| `app grant` / `app revoke` / `permission set` | Changes one runtime permission and reads it back | yes |
+| `permission respond` | Answers the permission dialog that is showing | n/a |
+
+`permission set` changes state with `pm grant` or `pm revoke`; `permission respond` taps the dialog on screen. They do
+not replace each other. Install flow: the file is staged to a private copy, its SHA-256 and declared package are
+checked against the package you selected, then installed.
+
+## Policy gates and the switches that lift them
+
+The companion app, section "Quyền điều khiển CLI / MCP", has one switch per gate. Install any APK and Grant/revoke permissions are on by default; Protected apps is off. The owner can turn any of them off. A refusal means that switch is off on this phone. An agent cannot flip these switches (input to the companion window is refused).
+
+| Refusal | Gate | Switch that lifts it |
+|---|---|---|
+| `POLICY_BLOCKED` "MSM_APK_DIR is not configured" | Install only from a vetted directory | Cài APK từ đường dẫn bất kỳ (or set `MSM_APK_DIR`) |
+| `POLICY_BLOCKED` "not in the runtime-permission allowlist" | Closed list: camera, microphone, location, contacts, calendar, media, notifications, Bluetooth, nearby Wi-Fi | Cấp/thu hồi mọi quyền runtime |
+| `POLICY_BLOCKED` "PROTECTED_TEST_APP" | Packages in `MSM_PROTECTED_TEST_PACKAGES` cannot be uninstalled | Thao tác app trong danh sách bảo vệ |
+| `CRITICAL_SYSTEM_TARGET` | Core system packages | none: add `--allow-critical-system` only when truly intended |
+| `PROTECTED_CONTROL_PLANE` | MoBridge's own companion | none: never overridable |
+
+What to do on a refusal: read `recovery`, tell the person exactly which switch to turn on and why, wait for them,
+then retry once. Never route around a gate with raw `adb`.
+
+Even with the permissions switch on, only runtime ("dangerous") permissions the device declares are accepted.
+Signature and development permissions (for example `WRITE_SECURE_SETTINGS`, `READ_LOGS`, `DUMP`) stay refused.
+
+## Safe habits
+
+- Prefer `app force` over `app clear` when a restart is enough.
+- Before `app clear` or `app uninstall`, state the package, what will be lost, and get the user's yes.
+- After `app install`, `mobridge open <package>` and `mobridge screen observe` to confirm it starts.
+- Use `mobridge diag APP_INFO --package <pkg>` to confirm version and install state instead of trusting the command.
+- If a call ends in `RESULT_UNKNOWN`, look it up with `mobridge operation status <operationId>`; do not resend.
+
+References: `references/permissions.md`.
+
+## Verification
+
+- Each command returns the package, process or permission state read back from the device; `CONDITION_MET` is success.
+- If the state cannot be read, run `mobridge diag APP_INFO --package <pkg>` before trying again.

package/skills/mobridge-app-control/references/permissions.md

@@ -0,0 +1,27 @@
+# Runtime permissions
+
+## Default allowlist
+
+`android.permission.` plus: `CAMERA`, `RECORD_AUDIO`, `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`,
+`READ_CONTACTS`, `WRITE_CONTACTS`, `READ_CALENDAR`, `WRITE_CALENDAR`, `READ_MEDIA_IMAGES`, `READ_MEDIA_VIDEO`,
+`READ_MEDIA_AUDIO`, `POST_NOTIFICATIONS`, `BLUETOOTH_CONNECT`, `BLUETOOTH_SCAN`, `NEARBY_WIFI_DEVICES`.
+
+Messaging, call, billing and signature permissions are excluded by design. With the permissions switch on, any
+permission that `pm list permissions -d -g` reports as dangerous on that device is accepted; nothing else.
+
+## Choosing the right command
+
+| You want | Use |
+|---|---|
+| Pre-grant a permission before a flow so no dialog appears | `mobridge -d ANDROID:<serial> app grant --package <pkg> --permission android.permission.CAMERA` |
+| Take a permission away | `mobridge -d ANDROID:<serial> app revoke --package <pkg> --permission android.permission.CAMERA` |
+| Same, with the short form | `mobridge -d ANDROID:<serial> permission set <pkg> CAMERA` (add `--revoke` to take it away) |
+| A dialog is on screen right now | `mobridge permission respond --decision ALLOW_WHILE_USING` |
+
+`permission respond` decisions: `ALLOW`, `ALLOW_WHILE_USING`, `ALLOW_ONCE`, `ALLOW_ALWAYS`, `DENY`, `DENY_DONT_ASK`,
+and `PRECISE` / `APPROXIMATE` for location. Add `--package` and `--permission` to name the dialog.
+
+## Reading the result
+
+A grant or revoke returns the permission state read back from the package manager. `CONDITION_MET` means the state is
+what you asked for. `CONDITION_UNKNOWN` means it could not be read: observe, then run `mobridge diag APP_INFO --package <pkg>`.

package/skills/mobridge-companion-setup/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: mobridge-companion-setup
+description: Use when installing, upgrading or fixing the MoBridge companion APK, Accessibility, vendor limits or signature errors
+version: 1.1.0
+---
+
+# MoBridge companion setup
+
+The companion ("MoBridge Runtime") is an Android app with an AccessibilityService. MoBridge reads and acts through it.
+Normally one `mobridge connect` installs, enables and verifies it. This skill covers the first run, upgrades,
+vendor restrictions and the owner switches on the phone.
+
+## When to use
+
+- First run on a phone, `COMPANION_*` or `ACCESSIBILITY_*` errors, a phone that refuses the install.
+- Upgrading the package, a signature mismatch, a downgrade, or a companion that keeps stopping.
+- A command is refused with `POLICY_BLOCKED` and the recovery names a switch in the companion app.
+
+## Workflow
+
+1. Run `mobridge health --preflight` and read the verdict and `nextSteps`.
+2. Run `mobridge connect -d ANDROID:<serial>`; it installs or upgrades the companion and enables Accessibility.
+3. If it reports a blocker, find the code in the table below and follow its `recovery`; vendor and Android 13+ steps are in `references/vendors.md`.
+4. If the phone has no PC link, use `references/manual-install.md`; for version or signature errors use `references/upgrades.md`.
+5. Apply `mobridge-devices` when the link keeps dropping and `mobridge-debugging` for any other error code.
+
+## What connect does
+
+```bash
+mobridge connect
+mobridge connect -d ANDROID:<serial>
+mobridge health --preflight
+```
+
+In order: resolve the named phone, install the bundled APK if missing or update it when its version differs from the
+host (a signature mismatch is solved by uninstall then install), write `enabled_accessibility_services` over adb and
+read it back, forward the runtime port to that serial, prove the binding with a nonce, then handshake. Concurrent
+connects share one provisioning run. You never run `adb install` by hand in the normal path.
+
+Read the result: `provision.companionInstalled` is `ALREADY`, `INSTALLED` or `UPDATED`; `health.accessibility`
+and `binding: VERIFIED` must be set before you act. `mobridge health --preflight` gives a verdict (`ready`,
+`degraded`, `blocked`) with ordered `nextSteps`.
+
+## Pick the right path
+
+| Situation | Path |
+|---|---|
+| Phone on USB, debugging allowed | `mobridge connect` and nothing else |
+| Phone on the same Wi-Fi, no cable | Wireless adb, then `mobridge connect` (see `mobridge-devices`) |
+| adb cannot install or enable it | Install by hand on the phone (`references/manual-install.md`), then `mobridge connect` |
+| Android 13+, Xiaomi, Oppo, Vivo, Samsung refuse | `references/vendors.md`, then `mobridge connect --wait-user 120` |
+| New package version | `mobridge connect` updates the companion once; run `mobridge daemon restart` first |
+| Wrong build, wrong signature | `mobridge connect` handles it; if it cannot, `references/upgrades.md` |
+
+## Errors you will meet
+
+| Code | First step |
+|---|---|
+| `COMPANION_MISSING` | Run `npx -y mobridge-mcp@latest install`, or set `MSM_COMPANION_APK` to the APK of this package. |
+| `COMPANION_INSTALL_BLOCKED` | The phone is asking for a confirmation or an OEM setting. Show the user `recovery`, then connect again. |
+| `COMPANION_INSTALL_FAILED` | Storage or Android version. Free space or check the minimum SDK, then connect again. |
+| `COMPANION_NOT_READY` | Handshake dropped ("socket hang up"). Read `details.diagnostics` and `recovery[0]`, apply, connect once. |
+| `ACCESSIBILITY_ENABLE_BLOCKED` | The phone refuses the adb write. Ask the person to turn it on, then `mobridge connect --wait-user 120`. |
+| `WAITING_FOR_USER_ACCESSIBILITY` | The wait window ended with it still off. Ask again, then connect (it resumes). |
+| `EXTERNAL_INSTRUMENTATION_ACTIVE` | Another tool holds UiAutomation. Stop it, then connect. |
+
+The full table is in `mobridge-debugging`.
+
+## User-assisted Accessibility
+
+Only after you asked the person to act. `mobridge connect --wait-user 120` (MCP `waitUserMs`, max 300000) polls the
+setting once a second, then continues the moment it reads back as on. Nothing is reinstalled. Android 13+ first needs
+Settings, Apps, MoBridge Runtime, menu, Allow restricted settings.
+
+## Owner switches on the phone
+
+The companion screen has a section "Quyền điều khiển CLI / MCP" with three independent switches. Install any APK and Grant/revoke permissions are on by default; Protected apps is off.
+Each lifts exactly one host policy gate, for the CLI and MCP alike:
+
+| Switch | Lifts |
+|---|---|
+| Cài APK từ đường dẫn bất kỳ | `mobridge app install` from any file; APKs stage to `~/.mobridge/apk` when `MSM_APK_DIR` is unset |
+| Cấp/thu hồi mọi quyền runtime | `app grant` / `app revoke` for any runtime (dangerous) permission the device declares |
+| Thao tác app trong danh sách bảo vệ | Uninstalling a package listed in `MSM_PROTECTED_TEST_PACKAGES` |
+
+An agent cannot flip them: input aimed at the companion's own window is refused (`ACTION_REJECTED`). Tell the person
+which switch to turn on and why; each asks for confirmation. Critical system packages and the companion itself stay
+protected whatever the switches say.
+
+The screen also has a separate display switch, "Hiển thị thao tác" (off by default). When on, the phone draws tap ripples, swipe trails, red find boxes, a scan sweep and a screenshot flash while MCP or CLI works. Touch passes through it and it is hidden while a screenshot is taken. It is not a policy gate. The companion reports it in `device.status` under `overlay` (`enabled`, `active`, `lastError`).
+
+## Behaviours worth knowing
+
+- The service shows a persistent notification while a session is active. Do not hide it.
+- With no controller for about five minutes the companion turns its own Accessibility service off (a safety
+  kill-switch). `mobridge connect` turns it on again over adb.
+- The bundled APK is the developer flavor (sideload and adb). Enterprise and Play-safe flavors exist in the source
+  and gate sensitive capabilities at build time; they are not what the npm package installs.
+- A debug build and a release build have different signatures; connect resolves it by uninstall then install, which
+  clears only the companion's own data.
+
+## Verification
+
+```bash
+mobridge health --preflight
+mobridge state
+mobridge screen observe
+```
+
+`state` must show the phone model and `connection`; `observe` must return `app` and `elements`; every response must
+say `backend: "device"`.

package/skills/mobridge-companion-setup/references/manual-install.md

@@ -0,0 +1,20 @@
+# Install the companion by hand (no adb from a computer)
+
+Use this only when `mobridge connect` cannot install it: adb is unavailable, the phone refuses USB installs, or you
+are preparing a phone for someone else. The APK is the developer build shipped inside the npm package.
+
+1. Run `npx -y mobridge-mcp@latest install` once on the computer. It extracts the APK to
+   `~/.mobridge/resources/android/app-developer-release.apk` (Windows: `%USERPROFILE%\.mobridge\resources\android`).
+2. Move that file to the phone (cloud drive, share sheet, cable).
+3. On the phone allow installs from that source, open the file and install it.
+4. Open MoBridge Runtime. It lists what is on and what is missing.
+5. Turn on the Accessibility service for MoBridge Runtime. On Android 13+ first allow restricted settings
+   (Settings, Apps, MoBridge Runtime, menu, Allow restricted settings).
+6. On the computer run `mobridge connect` (USB or wireless adb). The host forwards the port, proves the binding and
+   handshakes. If the companion is already the right version it is left alone.
+
+If adb is not usable at all, the host can pair over the LAN with a code shown on the phone
+(`MSM_BACKEND=ws MSM_WS_MODE=pair MSM_PAIR_CODE=<six digits>`; the phone also needs an on-device confirm tap).
+That path is advanced and exercises a different transport; ask the person before using it.
+
+Never install an APK that did not come from this package or a build the user named.

package/skills/mobridge-companion-setup/references/upgrades.md

@@ -0,0 +1,38 @@
+# Upgrades, downgrades and signature problems
+
+## Normal upgrade
+
+```bash
+mobridge daemon restart
+mobridge connect
+mobridge health --preflight
+```
+
+`connect` compares the installed companion version with the host. A newer host updates it once (`install -r`). The
+Accessibility setting is re-checked and re-enabled, then the handshake runs.
+
+## Signature mismatch
+
+An APK signed with another key cannot replace the installed one. `connect` handles it by uninstalling the companion
+and installing the bundled one. That clears only the companion's own data (pairing state, switches), not other apps.
+The owner switches go back to their defaults (install and permissions on, protected apps off): tell the person to turn on again what they need.
+
+## When connect cannot fix it
+
+| Symptom | Step |
+|---|---|
+| `COMPANION_VERSION_MISMATCH` persists | `mobridge connect` once more; if it repeats `mobridge doctor` |
+| `COMPANION_INSTALL_FAILED` | Free storage, check minimum SDK, retry |
+| The daemon runs an old build (`DAEMON_BUILD_MISMATCH`) | `mobridge daemon restart` |
+| A stale forward points at another phone (`DEVICE_BINDING_MISMATCH`) | `mobridge connect -d ANDROID:<serial>`, then `mobridge doctor` |
+| Wrong APK picked up | Set `MSM_COMPANION_APK` to the APK inside this package, or reinstall with `npx -y mobridge-mcp@latest install` |
+
+## Downgrade
+
+Android refuses to install a lower version code over a newer one. If `connect` cannot replace the companion after you
+installed an older package, ask the person to uninstall MoBridge Runtime (Settings, Apps), then run
+`mobridge daemon restart` and `mobridge connect`. Their owner switches go back to their defaults.
+
+## After any upgrade
+
+Reconnect once, observe, and confirm `backend: "device"` before running a long plan.

package/skills/mobridge-companion-setup/references/vendors.md

@@ -0,0 +1,21 @@
+# Vendor and Android-version restrictions
+
+What is verified: a Pixel 5 on Android 14 over USB and Wi-Fi/LAN (fresh install, old companion, Accessibility off,
+force-stop, cold daemon, parallel connects). Real Xiaomi, Oppo, Vivo, Samsung and Android 13+ restricted-settings
+phones were exercised with a fake adb only. Treat the rows below as guidance and tell the person when a screen differs.
+
+| Symptom | Likely cause | What the person does |
+|---|---|---|
+| `COMPANION_INSTALL_BLOCKED` | Vendor install confirmation, "install via USB" disabled, Play Protect prompt | Unlock the phone, tap Allow or Install on the prompt, allow USB installs in Developer options, then connect again |
+| `ACCESSIBILITY_ENABLE_BLOCKED` | The phone refuses `settings put secure` for accessibility | Settings, Accessibility, MoBridge Runtime, turn on. Then `mobridge connect --wait-user 120` |
+| The toggle is greyed out or says restricted | Android 13+ "restricted settings" for sideloaded apps | Settings, Apps, MoBridge Runtime, menu (three dots), Allow restricted settings. Then enable Accessibility |
+| Xiaomi: write refused even with debugging on | Security settings for USB debugging | Developer options, USB debugging (Security settings) on |
+| Service turns itself off later | Battery optimisation or an aggressive task killer | Allow background activity for MoBridge Runtime; connect again |
+| Another controller owns the session | `ACCESSIBILITY_PREEMPTED` or `EXTERNAL_INSTRUMENTATION_ACTIVE` | Stop Appium, uiautomator, a test runner or a second agent |
+
+## Rules for the agent
+
+- Do not walk the person through guesses. Name the one setting the error points at.
+- Never claim a vendor path is certain. If the screen differs, ask for a description or a screenshot.
+- After the person finishes, run one `mobridge connect`; do not poll in a loop.
+- Do not tap the phone's Settings screens yourself to enable the service: Accessibility is a human consent step.

package/skills/mobridge-core/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: mobridge-core
+description: Use when operating an Android phone with MoBridge - open apps, tap, type, scroll, read or screenshot the screen
+version: 1.0.0
+---
+
+# MoBridge core
+
+MoBridge drives a real Android phone through one shared daemon. The `mobridge` CLI and the 5 MCP tools
+(`mobile.device.connect`, `mobile.screen.observe`, `mobile.screen.act`, `mobile.screen.capture`, `mobile.run`)
+go through the same daemon and the same companion app. Never call raw `adb`, `uiautomator` or `adb shell input`
+for UI work: the daemon already picks the right executor and verifies the effect.
+
+## When to use
+
+- Any request to open an app, tap, type, scroll, read the screen, take a screenshot or run a flow on a phone.
+- Start here, then load the sibling skill that matches the problem (see the table at the end).
+
+## Install or repair this skill pack
+
+The pack is installed by default with the MoBridge installer. To add or repair it:
+
+```bash
+npx -y mobridge-mcp install --yes
+mobridge skill status
+mobridge skill install --agent all
+```
+
+Restart the agent afterwards so it reloads the skills.
+
+## Workflow
+
+1. Connect once per session: `mobile.device.connect` (MCP) or `mobridge connect` (CLI). Read `deviceId`,
+   `ready`, `blockers` and the `usage` field of the result. With several phones pass the device on every call.
+2. Observe only when the screen is unknown: `mobridge screen observe` returns semantic JSON from Accessibility
+   (no image). Look only when needed: `mobridge screen capture` returns real pixels.
+3. Act with ONE verb per call and a query, never a guessed coordinate.
+4. Read the verdict. `VERIFIED` is success. `DISPATCHED` only means the action was sent.
+5. Observe again after navigation, when a match was ambiguous, or when an action failed.
+
+```bash
+mobridge connect
+mobridge screen observe
+mobridge screen act click --text "Login" --verify auto
+mobridge screen observe --actionable
+```
+
+If you already know the query, skip observe and act directly: the click waits for the node by itself.
+
+## Golden rules
+
+- A mutation must be verified. `--verify auto` (or omitting verify, or policy `AUTO` over MCP) lets MoBridge pick
+  the policy. Choose one yourself only when you know it: `WINDOW_CHANGED` for navigation, `NODE_STATE_CHANGED` or
+  `NODE_VALUE_EQUALS` for in-place changes.
+- After `RESULT_UNKNOWN` never repeat the mutation. Run `mobridge operation status <operationId>` and observe.
+- Every response must say `backend: "device"`. `simulated` means fixtures: stop, nothing touched a real phone.
+- Pick targets by query (`text`, `label`, `resourceId`, `role`, `nth`, `within`). On `AMBIGUOUS_MATCH` narrow
+  the query from `candidates`; never click the first.
+- A NodeRef keeps its `snapshotId` and generation. A stale NodeRef fails closed: resolve the original query again.
+- Pass an `operationId` on every MCP act. Reusing one with the same payload returns the earlier receipt with
+  `idempotentReplay: true` and executes nothing; a different payload gives `IDEMPOTENCY_MISMATCH`.
+- Two or more steps: use `mobridge run plan.jsonl` or `mobile.run`, not many single calls (see `mobridge-recipes`).
+- Secrets: `mobridge type --secret` reads stdin. Never put passwords in argv, plans or traces.
+
+## Reading a response
+
+| Field | Meaning |
+|---|---|
+| `status` | `VERIFIED`, `DISPATCHED`, `FAILED`, `TIMEOUT` (condition never met), `RESULT_UNKNOWN` |
+| `verification` | predicate, result `CONDITION_MET` / `CONDITION_NOT_MET` / `CONDITION_UNKNOWN`, evidence |
+| `observation.treeEvidence.state` | `CHANGED`, `UNCHANGED`, `UNKNOWN` for the accessibility tree (canvas and WebView pixels are not in it) |
+| `app` | `{appId, title, generation}` of the foreground app after the action: no extra observe needed |
+| `stuck` | same action on the same target 3 times with the tree unchanged: change approach |
+| `error.details.targetDiagnosis` | `moved`, `covered`, `gone`, `ambiguous`, `unknown` plus the reason |
+| `traceId` | full evidence: `mobridge trace <traceId>` |
+
+More fields and the query grammar: `references/queries.md`, `references/response-fields.md`.
+
+## When semantics are not enough
+
+- `VISION_REQUIRED` or `NEEDS_VISION` (games, canvas, unlabeled icons, ads): `mobridge screen capture`, look at the
+  image, then `mobridge screen act at --capture <captureId> --x X --y Y`. An old capture fails as `STALE_CAPTURE`;
+  use `--stale-policy dynamic` for video or animation.
+- Android 13+ secure windows block capture, not semantics: keep using the semantic path when it works.
+
+## Never
+
+- Never substitute another phone, guess a coordinate, replay a mutation, or report business success
+  (login worked, payment done) from a technical verdict: MoBridge proves the UI changed, not what it means.
+
+## Where to go next
+
+| Situation | Skill |
+|---|---|
+| Several steps, CLI plus MCP together, saving a flow | `mobridge-recipes` |
+| Any `error.code`, a stuck or flaky action | `mobridge-debugging` |
+| First install, companion APK, Accessibility, vendor quirks | `mobridge-companion-setup` |
+| Install/uninstall apps, grant permissions, force-stop, clear data | `mobridge-app-control` |
+| USB vs wireless, several phones, lost link | `mobridge-devices` |
+| Fewer tokens, faster runs, parallel reads, burst capture | `mobridge-efficiency` |
+| Compose, WebView, native, games, test matrix | `mobridge-surfaces` |
+
+## Verification
+
+- Success is a `VERIFIED` verdict on the action, or a fresh `observe` that shows the expected node. Never report success from `DISPATCHED`.
+- On `RESULT_UNKNOWN`, `mobridge operation status <operationId>` before any retry.
+- When something fails, apply `mobridge-debugging`; when the screen has no nodes, apply `mobridge-surfaces`.

package/skills/mobridge-core/references/queries.md

@@ -0,0 +1,69 @@
+# Queries, roles and verification policies
+
+## Query fields
+
+A query selects semantic nodes. Combine fields; every field you give must match.
+
+| Field | CLI flag | Notes |
+|---|---|---|
+| `text` | `--text` | Matches the node text, and falls back to its label when the node has no text (Compose and Flutter controls often carry only a label). |
+| `label` | `--label` | Content description / accessibility label only. |
+| `resourceId` | `--resource-id` | Exact, for example `com.example.app:id/email`. |
+| `role` | `--role` | See the role list below. |
+| `nth` | `--nth` | Zero-based pick among equal matches. |
+| `within` | `--within <json>` | Restrict to descendants of an ancestor query, for example `{"role":"LIST"}`. |
+| `state` | `--query <json>` | `clickable`, `enabled`, `checked` and similar flags. |
+
+Text objects carry a match mode: `{"text":{"value":"Home","match":"CONTAINS"}}`.
+
+| Match | Behaviour |
+|---|---|
+| `NORMALIZED_EXACT` | Default. Case- and accent-insensitive, trimmed. A longer on-screen text gives `NODE_NOT_FOUND`. |
+| `EXACT` | Byte-exact. |
+| `CONTAINS` | Substring. Use deliberately: it raises the `AMBIGUOUS_MATCH` risk. |
+
+```bash
+mobridge find --text "Sign in"
+mobridge find --role LIST
+mobridge find --text "Settings" --nth 0
+mobridge find --query '{"text":{"value":"Home","match":"CONTAINS"}}'
+mobridge find --text "Terms" --scroll --max-scrolls 5
+```
+
+`find` prints a NodeRef. Pipe it: `mobridge find --text "Sign in" | mobridge tap -` (only a single match is tapped).
+
+## Roles
+
+`observe` assigns each node one role. Common ones: `SCREEN` (root), `LIST`, `BUTTON`, `TEXT`, `IMAGE`, `INPUT`,
+`SWITCH`, `CHECKBOX`, `TAB`, `SLIDER`, `PROGRESS`, `WEB_VIEW`, `CANVAS`, `UNKNOWN`.
+
+- Generic `android.view.View` nodes (Compose, Flutter, WebView DOM) are classified from their flags: scrollable
+  becomes `LIST`, anything with text or a label becomes `TEXT`, an `android.widget.Image` becomes `IMAGE`.
+- `SurfaceView`, `TextureView` and Unity views are `CANVAS`: pixels with no accessibility tree inside.
+- A screen with no interactive and no labelled node reports `VISION_REQUIRED` instead of a misleading `NOT_FOUND`.
+
+## Verification policies
+
+| Policy | Use for |
+|---|---|
+| `AUTO` | Default. Chosen from the action type. |
+| `WINDOW_CHANGED` | Navigation to another screen or dialog. |
+| `PACKAGE_CHANGED` | Switching to another app. |
+| `NODE_STATE_CHANGED` | A toggle, checkbox or selection changed in place. |
+| `NODE_VALUE_EQUALS` | A field now holds a value (`type`). |
+| `NODE_APPEARED` / `NODE_DISAPPEARED` | An element showed up or went away. |
+| `COLLECTION_POSITION_CHANGED` | A scroll moved the list contents. |
+| `CLIPBOARD_EQUALS` | The clipboard holds the expected text. |
+| `EXPLICIT_CONDITION` | Your own condition object. |
+| `DISPATCH_ONLY` | No check. Never with `--allow-gesture`. |
+
+## Wait conditions
+
+A condition is always wrapped, never a bare node object:
+
+```bash
+mobridge wait '{"nodeExists":{"text":{"value":"Home","match":"CONTAINS"}}}' --timeout 5000
+mobridge wait '{"nodeAbsent":{"role":"PROGRESS"}}' --timeout 8000
+```
+
+`anyOf` and `allOf` combine conditions. A timeout is status `TIMEOUT` and exit code 10, not a failure of the call.

package/skills/mobridge-core/references/response-fields.md

@@ -0,0 +1,35 @@
+# Response fields worth reading
+
+Every call returns a compact envelope. Large evidence stays in the trace (`mobridge trace <traceId>`).
+
+## Envelope
+
+| Field | Meaning |
+|---|---|
+| `status` | Final verdict, see `mobridge-core`. Exit codes: 0 success, 10 `TIMEOUT`. |
+| `result` | The tool result (observe elements, act dispatch, capture info). |
+| `error` | `{code, message, details}`. The code table lives in `mobridge-debugging`. |
+| `traceId`, `requestId` | `traceId` finds evidence, `requestId` identifies this call only. |
+| `operationId` | Identity of one logical mutation. Survives CLI to MCP switches. |
+| `deviceId`, `backend` | Which phone answered. `backend` must be `device`. |
+| `timing` | Spans: CLI start-up, IPC, queue, accessibility, resolve, serialization. |
+
+## act result
+
+- `dispatch`: how it was sent (`ACCESSIBILITY_ACTION`, `GLOBAL_ACTION`, a gesture) and the transport.
+- `target`: role, label and `resolvedVia` (`SELF` or `ANCESTOR` when a click was lifted to a clickable parent).
+- `observation`: before and after snapshot ids, `stability`, `screenChanged`, `windowChanged`, `treeEvidence`,
+  `diffRef` (`before:after`, usable with `mobridge diff --from A --to B`) and `diffSummary`.
+- `verification`: predicate, source, `CONDITION_MET` / `CONDITION_NOT_MET` / `CONDITION_UNKNOWN`.
+- `app`: foreground app after the action.
+- `stuck`: appears after three identical actions with an unchanged tree.
+
+## Late verification
+
+A slow screen may settle after the first read. MoBridge re-reads once before it decides, so the final
+`status` already includes the late result. Trust `status` and `verification`, not the first snapshot.
+
+## run result
+
+`steps` lists completed steps. `notRun` lists the planned steps after the stop point that never executed.
+`PAUSED` carries a `resumeToken`; resume with the same plan, device and workflow id.