mobitru-mobile-cli 1.0.0-beta.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "mobitru-mobile-cli",
+  "version": "1.0.0-beta.0",
+  "description": "Mobitru CLI (mobile) — command-line tool for AI agents to automate mobile testing on Mobitru cloud (Appium-backed)",
+  "keywords": [
+    "mobitru",
+    "cli",
+    "mobile",
+    "automation",
+    "testing",
+    "appium",
+    "device-farm",
+    "ai-agent"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "ISC",
+  "author": "Mobitru",
+  "bin": {
+    "mobitru-mobile-cli": "./mobitru-mobile-cli.js"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "fastify": "^5.8.4",
+    "webdriverio": "^9.0.0",
+    "webdriver": "^9.19.2"
+  },
+  "files": [
+    "*.js",
+    "skills/**",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ]
+}

package/skills/SKILL.md

@@ -0,0 +1,650 @@
+---
+name: mobitru-mobile-cli
+description: Automate mobile testing on Mobitru cloud against real Android or iOS devices. Use when an agent needs to book a remote device (immediate or future), drive a native app or device browser via taps and accessibility snapshots, install and exercise APK/IPA artifacts, capture screen recordings or device logs, simulate network conditions (throttling, IP geolocation, GPS), capture HTTP traffic to HAR, or rotate the screen — all against a cloud-leased phone or tablet.
+allowed-tools: Bash(mobitru-mobile-cli:*) Bash(npx:*) Bash(npm:*)
+---
+
+# Mobile Automation with mobitru-mobile-cli
+
+This CLI drives a **real device leased from Mobitru cloud**. Every
+command operates on a remote phone or tablet — there is no local emulator.
+See [references/mobile-sessions.md](references/mobile-sessions.md) for the
+booking lifecycle, credentials setup, and cleanup window.
+
+## Quick start
+
+```bash
+# Find an available device for the platform you want
+mobitru-mobile-cli device-list android
+
+# Book one by its serial (default lease is 180 minutes)
+mobitru-mobile-cli device-use <DEVICE_SERIAL>
+
+# Capture the screen — refs (e1..eN) come back for every interactable element
+mobitru-mobile-cli snapshot
+
+# Tap by ref, type into the focused field, submit with --submit
+mobitru-mobile-cli tap e3
+mobitru-mobile-cli type "mobitru.com" --submit
+
+# Release the device when done (frees the cloud slot)
+mobitru-mobile-cli device-release
+```
+
+## Commands
+
+### Device lifecycle
+
+```bash
+mobitru-mobile-cli device-list android                         # platform: android or ios
+mobitru-mobile-cli device-use <serial>                         # native session, 180 min lease
+mobitru-mobile-cli device-use <serial> --duration=30           # custom lease in minutes
+mobitru-mobile-cli device-use <serial> --web                   # browser (web) session
+mobitru-mobile-cli device-release
+```
+
+### Bookings (future reservations)
+
+**Distinct from `device-use`.** `device-use` takes an immediately available
+device for the current session. **Bookings reserve a device for a future time
+window** without starting any session. CRUD against the workspace, never the
+active device.
+
+```bash
+mobitru-mobile-cli bookings-list                                 # all bookings (ISO dates)
+mobitru-mobile-cli bookings-list --till=2026-06-01T00:00:00Z     # filter: only those starting before <iso>
+mobitru-mobile-cli bookings-info <booking-id>                    # full record
+
+mobitru-mobile-cli booking-create \
+    --name="regression run" \
+    --start=2026-05-20T09:00:00Z \
+    --end=2026-05-20T10:00:00Z \
+    --devices=<DEVICE_SERIAL>                                     # comma-separate for multi-device
+mobitru-mobile-cli booking-create ... --private                  # mark booking as private
+
+mobitru-mobile-cli booking-cancel <booking-id>                   # → { cancelled: true, id }
+```
+
+> ⚠️ **`booking-create` response has empty `startISO`/`endISO`.** A Mobitru
+> server quirk — the ISO fields populate on `bookings-list` / `bookings-info`
+> but come back empty on the create response. Re-fetch via `bookings-info`
+> if you need ISO timestamps right after creation. Epoch-seconds fields
+> (`start`, `end`) are always populated.
+
+## Native vs Web sessions
+
+Each booking is **either** a native session (default — drives the installed app)
+**or** a web session (drives the device's browser — Chrome on Android, Safari on
+iOS — with DOM-level operations on a web page).
+
+Pick at booking time:
+
+```bash
+mobitru-mobile-cli device-use <serial>          # native (default)
+mobitru-mobile-cli device-use <serial> --web    # web
+```
+
+Switching session type on the **same device** is fast (~5-10s) — the booking is
+preserved, only the underlying session restarts. Switching to a **different
+device** still requires `device-release` and incurs the 2-5min cloud cleanup
+window.
+
+```bash
+mobitru-mobile-cli device-use X                 # native on X
+mobitru-mobile-cli device-use X --web           # in-place switch to web on X — fast
+mobitru-mobile-cli device-use X                 # in-place switch back to native — fast
+mobitru-mobile-cli device-release && mobitru-mobile-cli device-use Y --web   # different device — slow
+```
+
+| Command | Native | Web |
+|---|---|---|
+| `screenshot`, `snapshot`, `tap`, `tap-at`, `type`, `swipe`, `continuous-swipe` | ✅ | ✅ (acts on browser viewport / DOM) |
+| `screen-size`, `get-orientation`, `set-orientation` | ✅ | ✅ |
+| `recording-*`, `logs-*`, `crashlogs`, `artifacts-*` | ✅ | ✅ (cloud-side, session-agnostic) |
+| `geolocation-*`, `ip-location-*`, `throttling-*`, `http-inspection-*`, `har-download`, `profiler-*`, `inject-*` | ✅ | ✅ (cloud-side, session-agnostic) |
+| `bookings-*`, `booking-*`, `espresso-*`, `xcuitest-*` | ✅ | ✅ (workspace-level, no device required) |
+| `launch`, `terminate`, `is-installed`, `install-app`, `install-app-ota`, `uninstall-app` | ✅ | ❌ |
+| `press` (HOME/BACK/etc.) | ✅ | ❌ |
+| `open-url` | ❌ | ✅ |
+| `click-web-element <selector>` | ❌ | ✅ |
+
+> ⚠️ Calling a native-only command in a web session (or vice-versa) surfaces a
+> clean error like `Cannot open URL in non-web session`. Switch session type
+> instead of retrying.
+
+Snapshot refs are session-type-specific (native AX tree ≠ web DOM tree).
+Re-snapshot after switching. Recording and logs survive a switch unchanged —
+the cloud captures the device's screen regardless of which session is active.
+
+### Observation
+
+```bash
+# PNG screenshot saved to disk; stdout returns { path, bytes }
+mobitru-mobile-cli screenshot
+mobitru-mobile-cli screenshot --output=./screen.png
+
+# Device screen dimensions in device pixels
+mobitru-mobile-cli screen-size
+
+# Accessibility tree of interactable elements; full tree saved to disk,
+# stdout returns { path, bytes, refCount }. Refs are e1..eN.
+mobitru-mobile-cli snapshot
+mobitru-mobile-cli snapshot --output=./tree.json
+```
+
+### App management
+
+```bash
+# Check whether an app is installed (use before launch to fail fast)
+mobitru-mobile-cli is-installed com.android.chrome
+# → { "appId": "com.android.chrome", "installed": true }
+
+# Launch an app by package name (Android) or bundle ID (iOS)
+mobitru-mobile-cli launch com.android.chrome
+
+# Stop a running app (no-op if not running)
+mobitru-mobile-cli terminate com.android.chrome
+```
+
+### Artifacts & install (bring your own app)
+
+```bash
+# List artifacts uploaded to the workspace
+mobitru-mobile-cli artifacts-list
+
+# Inspect one (status, package name from manifest, target platform, …)
+mobitru-mobile-cli artifacts-info c829dd49-...
+
+# Upload an APK or IPA. Blocks until the cloud finishes processing.
+# Target is auto-detected by extension (.apk → android, .ipa → ios).
+mobitru-mobile-cli artifacts-upload ./app.apk
+mobitru-mobile-cli artifacts-upload ./app.ipa --alias="login-flow-v2"
+
+# Install onto the active device. Blocks until done.
+mobitru-mobile-cli install-app c829dd49-...
+
+# iOS only: install from an OTA manifest URL (skips the artifacts step entirely)
+mobitru-mobile-cli install-app-ota https://example.com/app.plist
+
+# Uninstall by package name / bundle ID
+mobitru-mobile-cli uninstall-app com.epam.mobitru
+
+# Download an artifact (logs zip, uploaded APK, etc.) by id
+mobitru-mobile-cli artifacts-download 03e71031-c92e-4e87-8d8a-9fe4804a1d06
+mobitru-mobile-cli artifacts-download <id> --output=./logs.zip
+```
+
+### Recording (screen video)
+
+```bash
+# Start a screen recording. Returns max duration in seconds.
+mobitru-mobile-cli recording-start
+# → { "limitSeconds": 900 }
+
+# Stop the recording. Returns recordingId for download.
+mobitru-mobile-cli recording-stop
+# → { "status": "recording has stopped", "recordingId": "6635051b-..." }
+
+# Download the MP4. Blocks until the cloud finishes finalizing the file —
+# no waiting/polling needed on your side. Default path is
+# <CWD>/.mobitru-mobile-cli/recording-<ts>.mp4.
+mobitru-mobile-cli recording-download 6635051b-...
+mobitru-mobile-cli recording-download <id> --output=./demo.mp4
+```
+
+> ⚠️ **Very short recordings may be discarded by the cloud.** If you call
+> `recording-stop` within a second or two of `recording-start`, the
+> `recordingId` may never become available and `recording-download` will
+> error out after ~30s. Record long enough for visible activity.
+
+> 💡 **Safety net: auto-stop on release.** If `device-release` or `stop`
+> is called while a recording is still in flight, the daemon auto-stops
+> it first and includes the resulting `recordingId` in the release
+> response:
+>
+> ```json
+> { "released": true, "serial": "...", "result": {...}, "recordingId": "..." }
+> ```
+>
+> You can then `recording-download <recordingId>` before the daemon
+> exits. Explicit `recording-stop` is still the preferred flow — it
+> returns the `recordingId` immediately and lets you download before
+> teardown. The auto-stop is a recovery for forgotten-stop cases. If the
+> auto-stop itself fails (e.g., cloud-side state mismatch), the release
+> response will lack `recordingId` and the recording is lost.
+
+### Logs & crashlogs
+
+```bash
+# Start / stop device logs (logcat on Android, syslog on iOS).
+# logs-stop returns the artifactId — pass it to artifacts-download.
+mobitru-mobile-cli logs-start
+mobitru-mobile-cli logs-stop
+# → { "artifactId": "03e71031-..." }
+mobitru-mobile-cli artifacts-download 03e71031-...
+
+# One-shot dump of device crashlogs (zip of crash reports). Empty/small
+# zip is normal if no crashes occurred.
+mobitru-mobile-cli crashlogs
+mobitru-mobile-cli crashlogs --output=./crash.zip
+```
+
+### Network simulation (throttling)
+
+Constrain the booked device's bandwidth and latency to test how an app behaves
+on slow networks. Effects persist until `throttling-disable` or device release.
+
+```bash
+mobitru-mobile-cli throttling-presets                            # list named presets (3g, 4g, edge, …)
+mobitru-mobile-cli throttling-status                             # current state
+mobitru-mobile-cli throttling-enable 3g                          # apply a named preset
+mobitru-mobile-cli throttling-enable custom \
+    --download 500 --upload 250 --latency 200                    # kbps / kbps / ms
+mobitru-mobile-cli throttling-disable
+```
+
+> 💡 `throttling-presets` is global (no booked device required) — list options
+> before booking if you want to plan ahead.
+
+### Location & IP geolocation
+
+Two **independent** dimensions on the same device:
+
+- **GPS** — the location reported to apps via the OS location service.
+- **IP location** — the outbound network egress (proxy-based). Affects
+  IP-geolocation services (e.g. `https://ip-api.com/json`).
+
+```bash
+# Device GPS (lat/lng, WGS84 — values clamped to [-90,90] / [-180,180])
+mobitru-mobile-cli geolocation-get
+mobitru-mobile-cli geolocation-set 48.8566 2.3522                # Paris
+
+# Outbound IP location — list available country proxies, then set/reset
+mobitru-mobile-cli ip-location-list                              # global, no device needed
+mobitru-mobile-cli ip-location-set us                            # ISO-3166-1 alpha-2
+mobitru-mobile-cli ip-location-set DEFAULT                       # reset to data-center IP
+```
+
+> ⚠️ GPS lat/lng may round-trip with **minor float drift** (e.g. `48.8566` →
+> `48.85660171508789`) because of the cloud's float storage precision.
+> Harmless; don't treat it as a mismatch.
+
+### HTTP traffic capture — HAR (Android only)
+
+Capture all device-originating HTTP traffic into a HAR file. Useful for
+debugging network calls, verifying API contracts, or inspecting third-party
+SDK chatter.
+
+```bash
+mobitru-mobile-cli http-inspection-start                         # → { "harId": "..." }
+# Exercise the app: launch, snapshot, tap, type — traffic accumulates server-side
+mobitru-mobile-cli http-inspection-stop                          # → { "harId": "..." } (same id)
+mobitru-mobile-cli har-download <har-id>                         # default: <CWD>/.mobitru-mobile-cli/har-<ts>.har
+mobitru-mobile-cli har-download <har-id> --output=./traffic.har
+```
+
+Flags on `http-inspection-start`:
+
+```bash
+--capture-binary               # include binary payloads (default: off)
+--no-capture-response-content  # skip textual response bodies (default: capture)
+```
+
+> ⚠️ **Android only.** Calling `http-inspection-start` against an iOS device
+> returns a clean cloud-side error. iOS HTTP capture is not exposed by
+> Mobitru today.
+
+> 💡 Stopping before any traffic occurred still produces a structurally
+> valid (but empty) HAR (~300 bytes of wrapper metadata).
+
+### App profiler (CPU/memory)
+
+Capture CPU and memory samples while exercising a running app. Output is a
+JSON file with device, app, and sampling metadata.
+
+```bash
+mobitru-mobile-cli launch com.android.chrome                     # the target MUST be running
+mobitru-mobile-cli profiler-start com.android.chrome             # → { appPackage, started: true }
+# Exercise the app — taps, navigation, scrolling…
+mobitru-mobile-cli profiler-stop                                 # default: <CWD>/.mobitru-mobile-cli/profiler-<ts>.profile
+mobitru-mobile-cli profiler-stop --output=./run.profile
+```
+
+> ⚠️ `profiler-start` returns **400 if the target app isn't running**.
+> Launch (or otherwise foreground) the app first, then start the profiler.
+
+> 💡 Despite the `.profile` extension, the output is JSON — open with any
+> text editor or pipe through `jq`.
+
+### Mock injection (camera image, biometric touch)
+
+For testing flows that depend on camera input (KYC scans, document capture,
+profile-photo upload) or biometric authentication (fingerprint, Touch ID),
+inject the desired result directly instead of relying on a real sensor.
+
+```bash
+# Camera mock — feeds an image as the next camera frame the app receives
+mobitru-mobile-cli inject-image ./id-card.png
+mobitru-mobile-cli inject-image photo.jpg --content-type=image/jpeg --name=passport.jpg
+
+# Biometric mock — simulates a successful or failed fingerprint/Face ID
+mobitru-mobile-cli inject-touch valid                            # successful auth
+mobitru-mobile-cli inject-touch invalid                          # failed auth
+```
+
+> ⚠️ **Requires app cooperation.** Both commands fail with **412 Precondition
+> Failed** ("Check if application supports the injection feature") unless the
+> target app was installed with `doInjection=true` AND is currently in the
+> matching state — i.e. requesting a camera frame for `inject-image`, or
+> awaiting biometric auth for `inject-touch`. Standard installs (via
+> `install-app`) do not enable injection.
+
+Inferred defaults for `inject-image`:
+
+- **Content type** by extension: `.png` → `image/png`, `.jpg`/`.jpeg` → `image/jpeg`, `.gif` → `image/gif`, `.webp` → `image/webp`, anything else → `image/png`. Override with `--content-type`.
+- **File name** = basename of the path. Override with `--name`.
+- **Max 5 MB** per the cloud limit (returned as a clean error if exceeded).
+
+### Espresso / XCUITest test runs
+
+Submit an instrumentation test run to the cloud and poll for status. Distinct
+from interactive `device-use` — the cloud-side runner allocates the device,
+installs both APKs/IPAs, and manages the run. No active `device-use` booking
+is required.
+
+```bash
+# Espresso (Android) — submit a run; cloud picks the device unless pinned
+mobitru-mobile-cli espresso-run \
+    --app=<app-artifact-id> \
+    --test=<test-artifact-id> \
+    --runner=androidx.test.runner.AndroidJUnitRunner
+mobitru-mobile-cli espresso-run ... --serial=<serial>            # pin to a device
+mobitru-mobile-cli espresso-run ... --filter="class:com.foo.LoginTests"
+mobitru-mobile-cli espresso-run ... --shards=4 --duration=60
+
+# XCUITest (iOS) — serial is required (cloud-side allocation isn't auto-pooled)
+mobitru-mobile-cli xcuitest-run \
+    --serial=<serial> \
+    --app=<app-artifact-id> \
+    --test=<test-artifact-id>
+mobitru-mobile-cli xcuitest-run ... --no-resign                   # skip Mobitru profile resign
+
+# List, status, cancel — both engines share the same shape
+mobitru-mobile-cli espresso-list
+mobitru-mobile-cli espresso-status <run-id>
+mobitru-mobile-cli espresso-cancel <run-id>
+
+mobitru-mobile-cli xcuitest-list
+mobitru-mobile-cli xcuitest-status <run-id>
+mobitru-mobile-cli xcuitest-cancel <run-id>
+```
+
+> 💡 **Test runs are asynchronous.** `*-run` returns immediately with a `pending`
+> status. Poll `*-status <id>` until the status transitions to `completed`,
+> `failed`, or `canceled`. Final artifacts (logs, reports) appear in the
+> `artifacts` field of the status response — use `artifacts-download` to fetch
+> them by id.
+
+> ⚠️ **Espresso supports `--serial` / `--device-name` / `--platform-version` as
+> optional;** XCUITest requires `--serial`. The asymmetry comes from how
+> Mobitru allocates iOS vs Android — the iOS pool doesn't auto-select.
+
+> 💡 **Full bring-your-own-app loop:**
+> `artifacts-upload app.apk` → grab `id` from output → `install-app <id>` →
+> `launch <package>` → exercise the app via Tier 1 commands →
+> `uninstall-app <package>` (optional) → `device-release`.
+> Both upload and install **block** until the cloud confirms success — no
+> polling logic needed on your side.
+
+> 💡 **Prefer `launch` over tapping a home-screen icon** when the goal is "open
+> app X". `launch` works regardless of which screen the device is on, doesn't
+> depend on the icon being visible (or not buried in an app drawer), and
+> won't tap the wrong same-labeled icon. Use snapshot+tap only when you
+> need to interact with something already on-screen.
+
+### Appium scripts (custom WebDriver tests)
+
+Submit a Node-style Appium test script (mocha bodies — `it(...)`, `describe(...)`) to run against the booked device. The script runs in the background on the daemon; you can keep doing other work and poll for status.
+
+```bash
+mobitru-mobile-cli device-use <serial>                           # booking required first
+mobitru-mobile-cli appium-run path/to/test.js                    # submit; returns immediately
+mobitru-mobile-cli appium-run path/to/test.js --timeout 600000   # wall-clock cap (ms)
+mobitru-mobile-cli appium-run path/to/test.js \
+    --capabilities '{"appium:noReset": true}'                    # extra/override caps
+
+mobitru-mobile-cli appium-status                                 # state of current/last job
+mobitru-mobile-cli appium-logs                                   # combined stdout+stderr
+mobitru-mobile-cli appium-cancel                                 # SIGTERM the child
+```
+
+**Script shape.** Write mocha-style `it(...)` / `describe(...)` bodies. A `driver` global is in scope — a WebDriverIO session bound to the booked device. Don't set `platformName`, `udid`, or `automationName` capabilities yourself; they're set for you. Pass extra/override caps via `--capabilities`.
+
+```js
+it("logs in", async () => {
+    await driver.$("~loginButton").click();
+    const text = await driver.$("~welcomeLabel").getText();
+    if (text !== "Welcome") { throw new Error("got: " + text); }
+});
+```
+
+**Statuses** (terminal): `succeeded`, `failed`, `cancelled`, `timed-out`. While running: `status === "running"` with a live `durationMs`. `appium-logs` returns the current/last run's combined stdout+stderr.
+
+> ⚠️ **Single-job-at-a-time.** While an `appium-run` job is in flight, a second `appium-run` is rejected, interactive verbs (`tap`, `swipe`, `screenshot`, `snapshot`, `type`, `press`, orientation, web) are rejected, and `device-use` / `device-release` are rejected. Cloud-side verbs (`artifacts-*`, `throttling-*`, `recording-*`, `crashlogs`, etc.) are still allowed. Wait for terminal status or call `appium-cancel`.
+
+> 💡 **If the CLI dies mid-run**, the orphan mocha self-exits within ~5s, but the cloud booking still holds the device until its lease expires. Pass a tight `--duration` to `device-use` so the worst-case lock window is bounded.
+
+### Interaction
+
+```bash
+# Tap on an element by ref (taps the center of the element's rect)
+mobitru-mobile-cli tap e3
+
+# Tap at raw pixel coordinates — for elements invisible to snapshot
+# (most commonly: empty Material text fields). See "Empty Material fields"
+# below for the gap-inference pattern that produces the coords.
+mobitru-mobile-cli tap-at 540 601
+
+# Type into the currently focused input. Tap the input first to give it focus.
+mobitru-mobile-cli type "user@example.com"
+mobitru-mobile-cli type "query" --submit                       # presses ENTER after
+
+# Hardware buttons — case-insensitive
+mobitru-mobile-cli press HOME
+mobitru-mobile-cli press BACK
+mobitru-mobile-cli press VOLUME_UP
+mobitru-mobile-cli press VOLUME_DOWN
+mobitru-mobile-cli press ENTER
+mobitru-mobile-cli press DPAD_CENTER                           # plus DPAD_UP/DOWN/LEFT/RIGHT
+
+# Directional swipe; default force is 0.5 (half-screen distance)
+mobitru-mobile-cli swipe up
+mobitru-mobile-cli swipe down --force=0.8
+
+# Multi-point drag (2..20 coordinate pairs). Useful for gestures the
+# direction-based swipe can't express — diagonals, signatures, paths.
+mobitru-mobile-cli continuous-swipe 100,400 100,1200            # straight drag
+mobitru-mobile-cli continuous-swipe 100,400 800,400 100,1200    # L-shape
+```
+
+> 💡 **`swipe` vs `continuous-swipe` — pick by scope.**
+> - `swipe <direction>` is a **full-screen** gesture. Use it for
+>   dismissing notification shades, pulling drawer menus, system-level
+>   interactions where you want the gesture to reach the OS.
+> - `continuous-swipe x,y x,y` runs **between exact coordinates**. Use
+>   it for **all in-app scrolling** (catalog lists, modals, inner
+>   regions). Read the visible content rect from `snapshot` and drag
+>   between two points well inside it.
+>
+> ⚠️ **`swipe up` is unsafe inside an app on Android 11+.** The OS's
+> gesture-navigation system reserves the bottom edge for "swipe up =
+> home", and the default `swipe up` originates in the lower third of
+> the screen — close enough that the OS grabs the gesture and exits
+> your app. For scrolling the current screen's content downward, use
+> `continuous-swipe` with both points inside the app's content area
+> (e.g. `continuous-swipe 540,1600 540,800` — starts well above the
+> gesture zone). `swipe down` from the top is safe (no system gesture
+> there). `swipe left/right` is also generally safe.
+
+### Orientation
+
+```bash
+mobitru-mobile-cli get-orientation
+mobitru-mobile-cli set-orientation portrait
+mobitru-mobile-cli set-orientation landscape
+```
+
+## Snapshots and refs
+
+`snapshot` returns a flat list of interactable elements with rects, labels,
+and text. Each element gets a ref like `e1`, `e2`, `e3` — numbered in the
+order they appear on screen. Pass that ref to `tap`.
+
+```bash
+mobitru-mobile-cli snapshot
+# → { "path": ".../snapshot-1778515305673.json", "bytes": 12480, "refCount": 32 }
+
+# Read the file to find what you want, e.g. an omnibox:
+# {
+#   "ref": "e3",
+#   "type": "android.widget.EditText",
+#   "label": "Search Google or type URL",
+#   "rect": { "x": 60, "y": 220, "width": 920, "height": 56 }
+# }
+
+mobitru-mobile-cli tap e3
+```
+
+Refs are valid only until the next `snapshot` (which renumbers from scratch).
+Re-snapshot after any action that changes the screen — opening a menu,
+navigating, scrolling — before tapping again.
+
+> 💡 The mobile accessibility tree is **not** the DOM. Labels come from
+> Android's `contentDescription` / iOS's `accessibilityLabel`. Elements
+> without semantic information may not appear. If you can't find what you
+> need by `snapshot`, fall back to `screenshot` + visual reasoning.
+
+### Empty input fields and the snapshot filter (Android-only)
+
+**Android.** `snapshot` only includes elements that carry at least one of:
+`text`, `content-desc`, or `hint`. An empty `EditText` with no
+`contentDescription` and no `android:hint` (common with Material
+`TextInputEditText`, where the floating label is rendered as a separate
+`TextView`) carries none of those and is filtered out — even when focused.
+
+**iOS.** Empty `XCUIElementTypeTextField` / `TextView` widgets are reported
+in the snapshot regardless of content. `tap eN` works directly; the
+gap-inference pattern below is not needed.
+
+Consequence for the agent: empty input fields are not addressable by ref.
+You won't find an `EditText` entry to feed to `tap eN`. Use **`tap-at`
+with coordinates inferred from neighboring anchors** instead, then type.
+Once the field has content, the next snapshot includes it with `focused:
+true` and the typed text.
+
+Inferring coordinates — three cases, in decreasing reliability:
+
+| Layout | Coordinate strategy |
+|---|---|
+| Label above + another visible anchor below the input (next label, button, divider) | Tap at the midpoint of the gap between the two anchors |
+| Label above, nothing visible below | Tap at `(label_x_center, label_y_end + 60)` — an offset that empirically lands inside the input |
+| No label nearby | Take a `screenshot`, identify the field visually, pick coords by sight |
+
+Example for the gap case:
+
+```bash
+mobitru-mobile-cli snapshot
+# Labels: First name at y=448..501, Last name at y=702..755
+# Empty First Name input lives in the gap y ∈ [501, 702]
+# Midpoint y = 601, horizontal center of the form x = 540
+mobitru-mobile-cli tap-at 540 601
+mobitru-mobile-cli type "Alice"
+mobitru-mobile-cli snapshot
+# First Name now appears: { ref: "eN", text: "Alice", focused: true, rect: ... }
+```
+
+> ⚠️ Don't rely on the snapshot's `focused` field to verify focus *before*
+> typing into an empty field — the field isn't in the snapshot to report
+> focus. Verify by either: (a) the next `type` succeeding (it errors with
+> `no such element` when no input is focused), or (b) inspecting a
+> `screenshot` (caret visible, soft keyboard open).
+
+## The agent loop
+
+```
+snapshot → identify the target by label/text/type → tap ref → action → snapshot
+```
+
+After every screen-changing action (`tap`, `tap-at`, `type`, `swipe`,
+`continuous-swipe`, `press`, `set-orientation`, `launch`, `terminate`),
+call `snapshot` again before the next ref-based command.
+
+## Common errors
+
+| Error | Cause | Recovery |
+|---|---|---|
+| `no active device — run device-use first` | No device booked in this daemon | `device-use <serial>` |
+| `Failed to send keys: ... no such element` | `type` called with nothing focused | Tap a text input first, then retry |
+| `ref "eN" not found. Run snapshot first.` | Stale ref after the screen changed | Re-`snapshot`, get the new ref |
+| `device "<serial>" is currently in use. Run device-release first.` | Trying to switch devices without releasing | `device-release` then `device-use <new-serial>` |
+| `Failed to take device: 404` on `device-use` | Device is in post-release cleanup | Wait 30-60s and retry; or pick a different serial |
+| `another command is in flight; CLI calls must be sequential` | An earlier command is still running | Wait — most commands finish in seconds; `install-app` ~20-30s; `artifacts-upload` scales with file size. If it persists past a minute, run `mobitru-mobile-cli stop` to force-reset (kills any in-flight upload/download). |
+
+## Artifact output
+
+Screenshots, snapshots, and other generated files land under
+`<CWD>/.mobitru-mobile-cli/` by default, where `<CWD>` is the directory the
+command runs in. Override per-command with `--output=<path>`. The override
+is resolved relative to the current shell CWD, not the artifacts dir — pass
+an absolute path to be unambiguous.
+
+Run `mobitru-mobile-cli config` to see the resolved `artifactDir`.
+Set `MOBILE_CLI_OUTPUT_DIR=<dir>` to override the default location across
+all commands.
+
+> ⚠️ The artifact dir is resolved **per-invocation** from the shell's CWD,
+> not stamped once at booking. If you `cd` between commands, downloads
+> land relative to the new CWD. Stay in one directory for the duration of
+> a session, or pass `--output=<absolute-path>` for downloads.
+
+## Session state
+
+```bash
+mobitru-mobile-cli status      # show current state — { running, activeDevice, sessionType, recordingActive, currentJob }
+mobitru-mobile-cli stop        # release the device and reset session state
+```
+
+> ⚠️ **Always `stop` (or `device-release`) when done.** A leaked session
+> holds the cloud booking until the device lease expires.
+
+## Installation
+
+```bash
+# Install globally
+npm install -g mobitru-mobile-cli
+
+# Or use without installing
+npx mobitru-mobile-cli --version
+```
+
+First-time credentials setup is required before `device-use` works — see
+[references/mobile-sessions.md](references/mobile-sessions.md).
+
+## Example: Web search via Chrome
+
+```bash
+mobitru-mobile-cli device-use <DEVICE_SERIAL>
+mobitru-mobile-cli launch com.android.chrome
+mobitru-mobile-cli snapshot
+# Find the omnibox (android.widget.EditText with label "Search Google or type URL")
+
+mobitru-mobile-cli tap e3
+mobitru-mobile-cli type "mobitru.com" --submit
+mobitru-mobile-cli screenshot
+
+mobitru-mobile-cli device-release
+```
+
+## Specific tasks
+
+* **Booking lifecycle, credentials, cleanup window** — [references/mobile-sessions.md](references/mobile-sessions.md)