adb-ready 0.5.0 → 0.6.0

package/docs/agent-integration.md

@@ -26,7 +26,7 @@ it. ADB Ready does not open an MCP network listener.
 
 ## Connect an agent
 
-Preview the exact project change first, then apply it:
+Preview the exact project changes first, then apply them:
 
 ```bash
 adb-ready agent setup codex --dry-run
@@ -35,7 +35,28 @@ adb-ready agent setup codex
 
 Replace `codex` with `claude-code`, `cursor`, or `vscode`. Existing unrelated
 configuration is preserved. An existing `adb-ready` entry with different
-settings is reported as a conflict and is never replaced automatically.
+settings is reported as a conflict and is never replaced automatically. The
+same setup installs ADB Ready's version-matched Agent Skill at
+`.agents/skills/adb-ready/SKILL.md`, or `.claude/skills/adb-ready/SKILL.md` for
+Claude Code. A custom skill is never overwritten; generated older versions are
+updated atomically with the MCP configuration.
+
+Narrow tool discovery when an agent needs only one workflow:
+
+```bash
+adb-ready agent setup codex --mcp-profile debug
+```
+
+| Profile | Intended work |
+| --- | --- |
+| `full` | Complete backward-compatible tool surface; the default |
+| `session` | Target readiness, app lifecycle, and durable development sessions |
+| `ui` | Target readiness, app lifecycle, semantic UI automation, and screenshots |
+| `debug` | Target readiness, app lifecycle, current/saved evidence, and failure diagnosis |
+
+Profiles reduce accidental tool selection and client context size; they are not
+an authorization boundary. Start a server directly with `adb-ready mcp
+--mcp-profile ui` when configuration is managed outside `agent setup`.
 
 ### Codex
 
@@ -49,15 +70,16 @@ default_tools_approval_mode = "writes"
 ```
 
 Codex CLI, the Codex IDE extension, and the ChatGPT desktop app share Codex MCP
-configuration. See the [official Codex MCP guide](https://learn.chatgpt.com/docs/extend/mcp).
+configuration. Codex loads project `.codex/config.toml` only after the project
+is trusted; ADB Ready never changes trust on the user's behalf. See the
+[official Codex configuration guide](https://developers.openai.com/codex/config-basic).
 
 ### Claude Code
 
-Run this from the project root:
+Run the project setup from the project root:
 
 ```bash
-claude mcp add --scope project adb-ready -- node ./node_modules/adb-ready/dist/cli.js mcp
-claude mcp get adb-ready
+adb-ready agent setup claude-code
 ```
 
 Claude Code stores project-scoped servers in `.mcp.json` and asks users to
@@ -126,16 +148,17 @@ starts in the Android project root.
 
 Ask the agent to follow this sequence:
 
-1. Call `doctor` when host or ADB health is unknown.
-2. Call `ensure_ready`; provide an exact device serial, configured alias, or
+1. Call `get_capabilities` and stay within the active profile.
+2. Call `doctor` when host or ADB health is unknown.
+3. Call `ensure_ready`; provide an exact device serial, configured alias, or
    transport ID when more than one ready target exists.
-3. Start the configured stack with `start_dev_session` when it is not already
+4. Start the configured stack with `start_dev_session` when it is not already
    running; retain its task handle and poll `get_dev_session` without holding a
    tool call open.
-4. Resolve the project app with `resolve_app`.
-5. Use `inspect_app` or `inspect_ui` for bounded current evidence.
-6. Perform one typed action, then inspect again instead of assuming success.
-7. Use `get_session_problems` or `compile_debug_context` for an existing
+5. Resolve the project app with `resolve_app`.
+6. Use `inspect_app` or `inspect_ui` for bounded current evidence.
+7. Perform one typed action, then inspect again instead of assuming success.
+8. Use `get_session_problems` or `compile_debug_context` for an existing
    development session.
 
 The first successful `ensure_ready` binds one target to that MCP connection and
@@ -156,17 +179,18 @@ UI Automation service per target.
 
 | Capability | MCP tools |
 | --- | --- |
-| Host and target readiness | `doctor`, `list_targets`, `ensure_ready` |
+| Discovery and readiness | `get_capabilities`, `doctor`, `list_targets`, `ensure_ready` |
 | Durable development lifecycle | `start_dev_session`, `get_dev_session`, `stop_dev_session` |
 | App identity and lifecycle | `resolve_app`, `install_app`, `launch_app`, `restart_app`, `open_url` |
-| Current evidence | `inspect_app`, `inspect_ui`, `capture_screenshot` |
-| Safe UI queries and actions | `audit_ui`, `get_ui`, `find_ui`, `assert_ui`, `compare_ui`, `tap_ui`, `long_press_ui`, `scroll_ui`, `swipe_ui`, `fill_ui`, `clear_ui`, `type_text_ui`, `press_key_ui`, `wait_for_ui` |
+| Current evidence | `inspect_app`, `inspect_failures`, `inspect_ui`, `capture_screenshot` |
+| Safe UI queries and actions | `audit_ui`, `get_ui`, `find_ui`, `assert_ui`, `compare_ui`, `tap_ui`, `long_press_ui`, `scroll_ui`, `swipe_ui`, `fill_ui`, `clear_ui`, `type_text_ui`, `press_key_ui`, `wait_for_ui`, `inspect_keyboard`, `dismiss_keyboard`, `inspect_permission_dialog`, `respond_to_permission_dialog` |
 | Saved diagnostics | `list_sessions`, `get_session_problems`, `compile_debug_context` |
 
 MCP resources keep larger read-only context outside tool calls:
 
 | Resource | Content |
 | --- | --- |
+| `adb-ready://capabilities` | active profile, profile tool membership, and long-running task compatibility |
 | `adb-ready://targets` | current target inventory and this connection's bound target |
 | `adb-ready://sessions` | bounded saved-session manifests |
 | `adb-ready://sessions/{sessionId}` | one session manifest |
@@ -176,13 +200,33 @@ MCP resources keep larger read-only context outside tool calls:
 Every tool advertises an output schema and returns the same versioned result
 envelope used by CLI JSON output. Screenshot capture additionally returns MCP
 `image` content so a vision-capable agent can inspect the pixels directly; the
-verified project-local PNG remains the evidence source of record.
+verified project-local PNG remains the evidence source of record. Agent
+screenshots default to a 1024×1024 maximum and 4 MiB base64 content budget, with
+explicit crop/dimension controls and a deliberate `fullResolution` opt-in.
+Standard MCP annotations describe read-only, destructive, idempotent, and
+open-world behavior. The namespaced `dev.adbready/tool` metadata adds profile,
+category, target-binding, mutation, and sensitive-data signals. Annotations are
+advisory for clients; ADB Ready still enforces the operation at runtime.
 
 The npm package also ships `schema/agent-tools-v1.json`, generated from the
 server's real `tools/list` response during every build. Integrations can inspect
 version-matched input and output schemas plus safety annotations without
 starting ADB.
 
+The package also ships `skills/adb-ready/SKILL.md`. It is generated from the
+same real `tools/list` contract during the build, so its workflow cannot name a
+tool missing from that package version. The skill teaches task order and safety;
+the MCP server remains the controlled execution surface.
+
+## Long-running task compatibility
+
+ADB Ready does not advertise the MCP Tasks extension yet. Its durable
+`start_dev_session`, `get_dev_session`, and `stop_dev_session` handles remain
+available across supported clients and reconnects. `get_capabilities` reports
+this compatibility path explicitly. Native Tasks will be advertised only after
+capability negotiation and end-to-end interoperability are proven in at least
+two supported clients; unnegotiated clients never receive a Tasks claim.
+
 `list_sessions` is project-scoped by default and supports status, preset,
 recency, and result-count filters. When more matches remain, pass its opaque
 `nextCursor` back as `cursor`; an expired cursor fails explicitly instead of
@@ -197,6 +241,9 @@ silently restarting the list.
 - UI hierarchy and app inspection are marked sensitive and remain bounded.
 - UI references are checked against a fresh hierarchy digest before mutation;
   stale references are rejected.
+- Secret UI text is referenced by local environment-variable name rather than
+  sent in MCP arguments; Unicode input is capability-checked before mutation
+  and restores the prior Android IME.
 - Data clearing and uninstall are intentionally absent from the agent surface.
 - Tool annotations help clients request approval, but ADB Ready enforces its
   own target, path, and destructive-action rules.

package/docs/apps-and-evidence.md

@@ -123,6 +123,7 @@ Capture a PNG directly from the selected target:
 ```bash
 adb-ready capture screenshot
 adb-ready capture screenshot --out artifacts/login.png
+adb-ready capture screenshot --crop 120,300,840,900 --max-width 640
 ```
 
 Capture a bounded MP4 recording:
@@ -146,7 +147,10 @@ instead of publishing unusable evidence; create visible activity and retry.
 
 Some multi-display Android builds, including foldables, emit a short textual
 warning before the screenshot bytes. ADB Ready removes only a bounded text
-preamble and still requires a valid PNG signature before publishing the file.
+preamble and still decodes the complete PNG, verifies its chunks and checksums,
+and validates its dimensions before publishing the file. `--crop` uses source
+pixels in `X,Y,WIDTH,HEIGHT` order. `--max-width` and `--max-height` preserve
+aspect ratio and never upscale.
 
 The result contains:
 
@@ -154,12 +158,21 @@ The result contains:
 - media type and byte size;
 - measured duration and video frame count for recordings;
 - SHA-256 digest;
+- capture timestamp, source/output dimensions, effective crop, PNG encoding,
+  and whether crop or resize intentionally truncated the original frame;
 - selected target and capture-command provenance.
 
 Binary data is stored as a file rather than embedded into JSON or AI context.
 Screenshots and recordings can contain private information; ADB Ready does not
 upload or implicitly attach them to diagnostic context.
 
+MCP screenshot results are different by design: `capture_screenshot` returns
+image content to the requesting client, so it defaults to a proportional
+1024×1024 maximum and a 4 MiB base64 content budget. Agents may provide a
+smaller `crop`, `maxWidth`, or `maxHeight`. `fullResolution: true` is an
+explicit escape hatch for clients that can safely accept the complete image;
+it cannot be combined with dimension limits.
+
 ## Target selection and automation
 
 All commands accept the standard target selectors:

package/docs/automation.md

@@ -158,7 +158,7 @@ leaving a development server open:
 
 ```bash
 adb-ready run --preset expo --run-timeout 10m -- \
-  maestro '--device={target.serial}' test .maestro/smoke.yaml
+  maestro test .maestro/smoke.yaml
 ```
 
 ADB Ready selects and exclusively leases one target, prepares the configured
@@ -168,9 +168,23 @@ retries a failed product assertion as if it were an infrastructure failure.
 
 The literal `{target.serial}` inside a verification argument is replaced only
 after ADB Ready selects and leases the target. The child also receives the
-same value as `ANDROID_SERIAL` and `ADB_READY_TARGET_SERIAL`. This keeps tools
-such as Maestro pinned explicitly without invoking a shell; tools that already
-honor `ANDROID_SERIAL`, including common Gradle/ADB workflows, need no placeholder.
+same value as `ANDROID_SERIAL` and `ADB_READY_TARGET_SERIAL`, plus a private
+`ADB_READY_VERIFIER_OUTPUT_DIR` for native artifacts. Tools that already honor
+`ANDROID_SERIAL`, including common Gradle/ADB workflows, need no placeholder.
+
+For a direct `maestro test` command, ADB Ready uses Maestro's supported global
+`--device` option to bind the leased serial. Unless the command already names
+them, it also requests Maestro JUnit, test-output, and debug-output files. An
+explicit Maestro device that differs from the leased target fails before
+Maestro starts; ADB Ready never silently retargets it.
+
+Android CLI does not expose a single `journey run` command or a stable Journey
+report format. Journeys are evaluated by an agent using the installed Android
+CLI skill. ADB Ready therefore does not invent such a command. It keeps the
+agent workflow target-bound through MCP, and when a finite verifier invokes
+the official `android layout` or `android screen capture` primitives directly,
+ADB Ready supplies their supported `--device` and `--output` options. The
+Journey XML remains owned by Android CLI and the agent.
 
 Every executed run prints the path to a project-local evidence directory under
 `.adb-ready/artifacts/`. Its manifest references the structured result,
@@ -196,7 +210,7 @@ adb-ready run \
   --artifact android/app/build/outputs/apk/debug/app-debug.apk \
   --package com.example.app \
   --run-timeout 10m \
-  -- maestro '--device={target.serial}' test .maestro/smoke.yaml
+  -- maestro test .maestro/smoke.yaml
 
 adb-ready run --avd Pixel_9_API_36 --deploy --variant debug -- \
   ./gradlew connectedDebugAndroidTest
@@ -225,8 +239,18 @@ line-oriented `artifact_*`, `deployment_*`, and `emulator_*` fields; `--json`
 and `--ndjson` retain the complete structured automation data.
 
 The evidence manifest also includes the verifier's bounded, redacted native
-stdout and stderr. Preparation failures still publish the same result,
-problems, JUnit, and evidence contract after owned-resource cleanup.
+stdout and stderr. Supported native JUnit, screenshots, videos, logs, JSON,
+and HTML reports are copied under `verifier-native/`, checksummed, marked
+sensitive, and bounded to 100 files, 20 MiB per file, and 50 MiB total.
+Symlinks and unsupported file types are never followed. Text artifacts are
+redacted; binary screenshots and video remain local sensitive evidence.
+Preparation failures still publish the same result, problems, JUnit, and
+evidence contract after owned-resource cleanup.
+
+Structured results classify the verifier independently as `passed`,
+`assertion-failed`, `tool-failed`, `target-failed`, `timed-out`, `cancelled`,
+or `unavailable`. This classification uses process and session state, not
+fragile parsing of human log messages.
 
 ## CI example
 

package/docs/getting-started.md

@@ -28,7 +28,12 @@ npx adb-ready doctor
 ```
 
 Run `npx adb-ready` without a command for the interactive workflow home. Its
-layout automatically switches to a compact form in narrow terminal panes.
+layout automatically switches to a compact form in narrow terminal panes. Open
+**Start** for development sessions, bounded verification, wireless connection,
+pairing, or **Set up first device**. The guided setup walks through a physical
+Android device over USB, Android 11+ Wireless debugging, or an existing Android
+emulator, then hands off to the normal verified target workflow. The remaining
+sections keep device operations, debugging, and project setup separate.
 
 The full source build can be tested from a repository checkout:
 

package/docs/logs-and-context.md

@@ -62,6 +62,40 @@ and never promoted to application problems. A configured `app.android.package`
 or `dev --package APP_ID` scopes the stream directly; Expo sessions retarget it
 to the package that Android resolves for the verified launch URL.
 
+## Correlated crash, ANR, and native evidence
+
+Inspect one installed application across Android's available failure sources:
+
+```bash
+adb-ready inspect failures com.example.app
+adb-ready inspect failures --package com.example.app --since 30m --max-records 25 --json
+```
+
+This read-only workflow verifies the selected package and target, records the
+UID and current PID when Android exposes them, uses the target's own clock and
+UTC offset, then correlates a bounded recent window from:
+
+- package-scoped `ApplicationExitInfo` exposed by ActivityManager;
+- UID-scoped `main`, `system`, and `crash` logcat buffers;
+- exact package/process matches in supported app crash, native crash, and ANR
+  DropBox tags.
+
+Java/Kotlin exceptions, native crashes, React Native fatal errors, and ANRs are
+classified separately. Stable numeric `ApplicationExitInfo` reason codes drive
+classification; its human description remains evidence rather than a parsing
+contract. Old exits outside `--since` and DropBox blocks for other packages are
+excluded. Matching evidence from different Android sources is returned as one
+incident with `corroboratedBy`, rather than inflating one crash into multiple
+findings. The default window is 15 minutes and default result limit is 20;
+accepted bounds are one second to seven days and 1 to 100 incidents.
+
+Android versions and OEM builds do not expose every source equally. The result
+contains an availability, record count, truncation state, and limitation for
+each source. Missing history or a DropBox permission denial does not become a
+false application failure, and unrelated system/process failures are never
+promoted into the selected app's findings. Returned evidence is sensitive and
+redacted before retention or rendering.
+
 ## Session history
 
 Development sessions incrementally persist redacted NDJSON and an atomic

package/docs/targets-and-wireless.md

@@ -3,6 +3,10 @@
 ADB Ready models USB devices, emulators, TCP transports, and TLS Wireless
 debugging transports behind one deterministic selection contract.
 
+For a first connection, run `adb-ready` and open **Start → Set up first
+device**. The interactive guide explains the Android-side steps, then reuses the
+same verified `devices`, `pair`, or `connect` workflow documented below.
+
 ## Inspect visible targets
 
 ```bash

package/docs/threat-model.md

@@ -39,6 +39,12 @@ selection fails. An MCP connection binds one target and refuses a silent
 switch. UI references include the current hierarchy digest and are revalidated
 immediately before mutation.
 
+MCP profiles narrow discovery for a workflow and reduce accidental tool
+selection, but they are not an authorization boundary. Every exposed operation
+still applies its own target, path, input, ownership, and destructive-action
+checks. Tool annotations and namespaced sensitivity metadata help clients choose
+approval policy; they are hints, not security enforcement.
+
 ### Unsafe file mutation
 
 Capture and setup paths are constrained to the project, checked for unsafe
@@ -52,6 +58,20 @@ redacted. Pairing codes use protected input or stdin and never enter process
 arguments. Screenshots and UI hierarchies require explicit calls and never join
 AI context automatically.
 
+Screenshot capture rejects malformed PNG structure, invalid checksums,
+unsupported encodings, and excessive source dimensions before publishing a
+file. MCP image results are cropped or proportionally bounded by default and
+must fit an encoded payload budget; full-resolution delivery is an explicit
+client choice. These controls bound transport and context size, not the visual
+sensitivity of the selected pixels.
+
+Failure inspection accepts only a verified installed package, binds every
+probe to the same target, uses package-scoped exit history and log filtering,
+and retains DropBox blocks only when an exact package or package-process line
+matches. Unavailable or permission-limited sources are reported rather than
+replaced by target-wide evidence. Source bytes, time windows, record counts,
+and returned excerpts are bounded and redacted.
+
 ### Unbounded or misleading automation
 
 Process output, recordings, UI trees, session storage, context, retries, and
@@ -59,6 +79,12 @@ waits are bounded. Results distinguish process acceptance (`ok`) from observed
 postconditions (`verified`). An unchanged UI is reported as a verification gap,
 not silently upgraded to verified success.
 
+Keyboard dismissal requires two independent Android visibility signals to
+agree before Back is sent and after it completes. Runtime-permission responses
+require one recognized PermissionController dialog and one exact resource ID;
+localized labels, generic system dialogs, biometric prompts, notification
+setup, and ambiguous OEM states are never accepted speculatively.
+
 ### Network exposure
 
 The 0.2 MCP server uses stdio and opens no listener. ADB itself may connect to a
@@ -73,6 +99,13 @@ ADB Ready's isolation boundary.
 - autonomous destructive recovery;
 - automatic screenshot or UI-text upload.
 
+Protected UI text is accepted from CLI stdin or by environment-variable name
+through MCP. It is not placed in host argv, result envelopes, plans, journals,
+screenshots created by the action, or AI context. It still exists transiently
+in ADB Ready memory and the child-process pipe, and the selected Android target,
+input method, app, or OEM auditing may observe it. ADB Ready does not claim to
+turn a normal visible field or an untrusted target into a secure channel.
+
 ## Residual risk
 
 A trusted ADB server can control connected Android targets, and an approved AI

package/docs/troubleshooting.md

@@ -34,6 +34,11 @@ adb-ready context --since 5m --only problems,recovery,logs
 | `UI_HIERARCHY_BUSY` | Another process held the selected target's single UI Automation service through the UI timeout | Let that capture finish or increase the UI timeout, then retry |
 | `UI_HIERARCHY_LOCK_UNAVAILABLE` | The per-user coordination directory is not writable | Restore write access to the ADB Ready state directory, then retry |
 | `UI_NOT_IDLE` | Android UI Automator could not observe a quiet accessibility window | Pause continuous UI changes or navigate to a stable screen, then retry |
+| `UI_UNICODE_INPUT_UNAVAILABLE` | Unicode/multiline input was requested but ADBKeyBoard is not installed and enabled | Install a compatible official ADBKeyBoard release, enable it in Android settings, and retry; ADB Ready will not enable an IME silently |
+| `UI_INPUT_METHOD_UNKNOWN` | Android did not expose the current IME, so it cannot be restored safely | Select a keyboard on the target before retrying Unicode input |
+| `UI_KEYBOARD_STATE_AMBIGUOUS` | InputMethodManager and WindowInsets disagree about keyboard visibility | Wait for the transition to settle, then inspect again; ADB Ready will not press Back while state is uncertain |
+| `UI_KEYBOARD_STATE_UNSUPPORTED` | The Android build omitted one of the two required keyboard signals | Dismiss the keyboard in the app or use a target that exposes both dumpsys states |
+| `UI_PERMISSION_DIALOG_UNSUPPORTED` | The current PermissionController or OEM dialog is not one exact supported runtime-permission prompt | Handle the dialog manually; notification, biometric, Settings, and unknown OEM dialogs are not auto-accepted |
 | `SESSION_RECOVERY_FAILED` | The bounded target/port recovery budget was exhausted | Inspect `problems`, network state, and saved recovery events |
 | `SESSION_PERSISTENCE_FAILED` | The private session record could not be written | Check user-state directory permissions and capacity |
 | `FRAMEWORK_LAUNCHER_NOT_FOUND` | The detected Flutter or Gradle project has no runnable launcher | Install Flutter and expose `flutter` on PATH, or restore the project's checked-in Gradle Wrapper |
@@ -135,6 +140,37 @@ Resolve the user-action problem, then start a new session. Increase the recovery
 budget only when the environment is known to need more time; do not use an
 unbounded timeout.
 
+## Screenshot capture is rejected
+
+`SCREENSHOT_BOUNDS_INVALID` means the requested `--crop X,Y,WIDTH,HEIGHT` lies
+outside the decoded source image. Capture once without a crop and read the
+reported `image.source` dimensions, then retry with coordinates inside them.
+
+`SCREENSHOT_PAYLOAD_TOO_LARGE` protects an MCP client from an unexpectedly
+large image. Crop the relevant region or lower `maxWidth`/`maxHeight`; use
+`fullResolution: true` only when the client can deliberately accept it.
+
+`SCREENSHOT_INVALID` or `SCREENSHOT_ENCODING_UNSUPPORTED` means ADB did not
+produce a complete standard non-interlaced 8-bit PNG. Confirm that the selected
+display is available and not blocked by a secure surface, then retry without
+assuming that a PNG signature alone proves usable evidence.
+
+## Failure inspection has unavailable sources
+
+`adb-ready inspect failures APP_ID` succeeds when the app and target are
+verified even if an optional Android evidence source is absent. Read the
+`sources` list: each entry distinguishes available, truncated,
+permission-limited, and unsupported evidence.
+The top-level `truncated` flag means the requested incident limit bounded the
+combined result; a source-level flag means Android output or log retention was
+bounded before correlation.
+
+Application exit history requires Android 11/API 30 or a compatible OEM
+backport. DropBox visibility varies by Android build and shell permissions.
+ADB Ready does not substitute unrelated target-wide crashes. Use a recent
+`--since` window, reproduce the failure, and retry; use focused `adb-ready logs`
+when the app is still running and live output is required.
+
 ## Report a reproducible issue
 
 For ordinary bugs, open a GitHub issue with the ADB Ready version, host/runtime,

package/docs/ui-automation.md

@@ -30,6 +30,33 @@ parallel, and selector processing or input does not hold the capture lock. If
 another process does not finish within the configured UI timeout, the command
 returns `UI_HIERARCHY_BUSY` instead of misreporting an inaccessible screen.
 
+Choose an acquisition profile when the default one-shot observation is not the
+right tradeoff:
+
+```bash
+adb-ready inspect ui --acquisition balanced
+adb-ready inspect ui --acquisition fast --interactive-only
+adb-ready inspect ui --acquisition strict
+```
+
+- `balanced` takes one fresh platform-idle snapshot within the normal bounded
+  UI timeout and is the default.
+- `fast` keeps the same safe target-scoped platform backend but limits the
+  attempt to three seconds. It reports a timeout or non-idle screen instead of
+  pretending that an empty result is a valid screen.
+- `strict` requires two consecutive matching hierarchy digests within at most
+  three captures. A continuously changing screen returns
+  `UI_HIERARCHY_UNSTABLE`.
+
+Every successful structured snapshot reports its observation time, duration,
+attempt count, stability status, source and idle strategy, requested filters,
+node limits, truncation, observed display bounds and rotation, and detected
+semantic limitations. An empty hierarchy is an explicit `UI_HIERARCHY_EMPTY`
+failure. WebView, Compose, and Flutter
+markers are reported only when their corresponding platform view is actually
+observed; they describe framework accessibility boundaries rather than guessing
+why an otherwise unreadable window failed.
+
 ## Audit one screen for people and agents
 
 ```bash
@@ -92,6 +119,7 @@ field happens to be focused:
 adb-ready ui get 'id=com.example:id/email' --json
 adb-ready ui fill 'id=com.example:id/email' 'person@example.com'
 adb-ready ui fill 'id=com.example:id/search' 'pixel' --submit
+adb-ready ui fill 'id=com.example:id/name' 'Příliš žluťoučký 🦊' --input-mode unicode
 adb-ready ui clear 'id=com.example:id/search'
 ```
 
@@ -128,9 +156,84 @@ node whose `scrollable` property is true; without a selector it uses the screen.
 Supported keys are `back`, `home`, `enter`, `menu`, `volume-up`, and
 `volume-down`.
 
-Android's text-input command passes through a device shell. ADB Ready therefore
-accepts only 1–256 ASCII letters, numbers, spaces, and `._@+,:/-`. Unsupported
-characters are rejected instead of being reinterpreted by a shell.
+Text input is bounded to 1–256 Unicode code points and 4096 UTF-8 bytes. The
+default `--input-mode auto` uses Android's built-in `input text` only for the
+conservative ASCII set of letters, numbers, spaces, and `._@+,:/-`. Use
+`--input-mode ascii` to require that path explicitly.
+
+Unicode, emoji, RTL, CJK, and multiline input use the open-source
+[ADBKeyBoard](https://github.com/senzhk/ADBKeyBoard) broadcast contract because
+Android's built-in input command does not reliably represent those values. The
+IME must already be installed and enabled on the selected target. ADB Ready
+checks that contract before touching the screen, temporarily selects the IME,
+and restores the exact previous IME in a `finally` path. It never downloads,
+installs, enables, or leaves a keyboard selected silently. If the helper or a
+restorable current IME is unavailable, the action fails before typing.
+
+Some apps drop text delivered too quickly. Pace either backend by Unicode code
+point with a whole-millisecond delay from 0 to 2000:
+
+```bash
+adb-ready ui type 'مرحبا بالعالم' --input-mode unicode --typing-delay 40
+```
+
+### Protected input
+
+Do not put passwords or tokens in a command argument. Pipe one value to stdin:
+
+```bash
+printf '%s' "$TEST_PASSWORD" |
+  adb-ready ui fill 'id=com.example:id/password' --secret-stdin --submit
+```
+
+`--secret-stdin` reads at most 4096 bytes to EOF, removes one final line ending,
+and preserves embedded newlines. Plaintext is excluded from host process
+arguments, operation plans, terminal output, structured results, event
+journals, screenshots created by this action, and AI context. The value exists
+only in process memory and the pipe used to deliver it to the selected target.
+For Unicode, the on-device shell receives base64 rather than plaintext.
+
+This is a bounded host-side guarantee, not a secure-input claim about Android
+or the app: the selected IME and target receive the value, a normal visible
+field may display it, and device/OEM auditing can observe shell activity. Use a
+password field and assert a non-secret postcondition. A protected field cannot
+expose its value for exact verification, so ADB Ready returns
+`text-not-observable` rather than inventing success.
+
+## Keyboard and runtime-permission dialogs
+
+Inspect or dismiss the software keyboard without sending a blind Back action:
+
+```bash
+adb-ready ui keyboard status --json
+adb-ready ui keyboard dismiss
+```
+
+ADB Ready requires Android's InputMethodManager `mInputShown` state and its
+WindowInsets `type=ime` visibility to both exist and agree. `dismiss` sends Back
+only after both report visible, then reads both services again and succeeds only
+after both report hidden. An already hidden keyboard is a verified no-op.
+Missing or conflicting signals return `UI_KEYBOARD_STATE_UNSUPPORTED` or
+`UI_KEYBOARD_STATE_AMBIGUOUS`; ADB Ready does not guess from inset height or
+press Back against an unknown screen.
+
+Inspect one standard Android runtime-permission prompt before choosing an exact
+decision:
+
+```bash
+adb-ready ui permission inspect --json
+adb-ready ui permission respond allow-while-using
+adb-ready ui permission respond allow-once --dry-run --json
+adb-ready ui permission respond deny
+```
+
+Inspection returns only the decisions actually present on the current dialog.
+Responses match PermissionController package and resource IDs, never translated
+button labels or coordinates copied from another device. A fresh hierarchy must
+show that the specific prompt changed or disappeared after the tap. Multiple,
+unknown, or OEM-specific states fail closed. Notification permission setup,
+biometric prompts, Settings mutation, and generic system-dialog acceptance are
+intentionally outside this workflow.
 
 ## Find, assert, compare, and wait
 
@@ -143,8 +246,9 @@ adb-ready ui assert 'text=Loading' --state gone
 adb-ready ui compare 7c4a31b8d2ef0000000000000000000000000000000000000000000000000000
 ```
 
-`compare` consumes the complete digest returned by inspection or another UI
-action and reports whether the current hierarchy changed.
+The CLI `compare` command consumes the complete digest returned by inspection
+or another UI action and reports whether the current hierarchy changed. It
+does not persist the earlier sensitive hierarchy.
 
 Waits use exact, explicit selectors:
 
@@ -186,11 +290,31 @@ the next state is known.
 ## AI agents
 
 The MCP server exposes the same intent-level workflow through `audit_ui`, `get_ui`,
-`find_ui`, `fill_ui`, `clear_ui`, `scroll_ui`, `assert_ui`, and `compare_ui`.
+`find_ui`, `fill_ui`, `clear_ui`, `scroll_ui`, `assert_ui`, `compare_ui`,
+`inspect_keyboard`, `dismiss_keyboard`, `inspect_permission_dialog`, and
+`respond_to_permission_dialog`.
 Its structured selectors can match exact values, prefixes, or substrings and
 qualify enabled/actionable state. An optional one-based occurrence is accepted
 only when repeated nodes are intentional. Arguments are schema-validated, each
 MCP connection stays bound to one target, and no raw ADB or shell tool is
 exposed.
 
+`type_text_ui` and `fill_ui` accept `inputMode` and `typingDelayMs`. For a
+secret, set `secretEnv` to the *name* of an environment variable already passed
+to the local MCP server and omit `text`. ADB Ready reads the value locally; the
+MCP request, tool result, and retained agent conversation contain only the
+variable name. Supplying both fields, neither field, or a missing/empty variable
+fails before device mutation.
+
+`inspect_ui` retains at most eight sensitive snapshots in memory for that MCP
+connection only. `compare_ui` accepts one of those complete digests and returns
+a bounded semantic diff: added, removed, updated, and moved nodes with current
+selector context. `changed` describes the requested filtered view, while
+`digestChanged` also reveals changes outside that view. Unchanged screens return
+empty change lists. Bases expire
+after five minutes and are never written to disk; missing or expired digests
+require a fresh `inspect_ui`. A diff is rejected rather than guessed when its
+target, display bounds or rotation, hierarchy filters, acquisition contract, or
+completeness differs from the base.
+
 [Connect an agent →](./agent-integration.md)

package/llms.txt

@@ -8,13 +8,14 @@
 - Diagnose: `adb-ready doctor`
 - Start a session: `adb-ready dev`
 - Machine output: `adb-ready COMMAND --json --non-interactive`
-- MCP stdio server: `node ./node_modules/adb-ready/dist/cli.js mcp`
-- Agent setup: `adb-ready agent setup CLIENT --dry-run`
-- MCP resources: `adb-ready://targets` and `adb-ready://sessions`
+- MCP stdio server: `node ./node_modules/adb-ready/dist/cli.js mcp [--mcp-profile PROFILE]`
+- Agent setup plus version-matched Agent Skill: `adb-ready agent setup CLIENT --dry-run`
+- Finite verifier with normalized evidence: `adb-ready run -- maestro test FLOW`
+- MCP resources: `adb-ready://capabilities`, `adb-ready://targets`, and `adb-ready://sessions`
 
 ## Agent contract
 
-1. Call `ensure_ready` before target-bound MCP tools.
+1. Call `get_capabilities`, then `ensure_ready` before target-bound MCP tools.
 2. Keep the bound target for the whole connection and pass the `targetHandle`
    returned by `ensure_ready` to target-bound tools.
 3. Use `start_dev_session`, then poll `get_dev_session` by its opaque handle;
@@ -29,6 +30,9 @@
 8. Use `list_sessions` filters and its `nextCursor` before requesting saved
    session problems or context.
 9. Never substitute a raw shell or ADB call for a missing typed tool.
+10. MCP Tasks are not advertised; use the durable start/get/stop session tools.
+11. For a finite verification job, use `run`; consume its structured verifier
+    outcome and retained `verifier-native/` references instead of parsing prose.
 
 ## Documentation