adb-ready 0.5.1 → 0.7.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,
@@ -184,6 +198,20 @@ Preview the complete project plan before a device is allocated:
 adb-ready run --preset expo --dry-run --json -- npm run test:e2e
 ```
 
+### Fan out over an explicit pool
+
+Named project pools repeat the same bounded verifier without weakening the
+single-target run contract:
+
+```bash
+adb-ready run --pool smoke --max-concurrency 2 -- npm run test:e2e
+```
+
+Each member keeps its own target lease, session, result envelope, evidence, and
+cleanup. Required failures fail the aggregate; optional failures remain
+visible. Queueing is bounded and host-local, never an inferred distributed
+lock. See [Target pools and fan-out](./target-pools.md).
+
 ### Start an existing AVD and deploy the intended build
 
 For a complete local or CI-owned emulator job, name one existing AVD and either
@@ -196,7 +224,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 +253,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
 
@@ -241,3 +279,78 @@ problems, JUnit, and evidence contract after owned-resource cleanup.
 USB passthrough, emulators, remote ADB servers, and device labs remain the CI
 environment's responsibility. ADB Ready reports the observed boundary instead
 of simulating a connected device.
+
+### GitHub-hosted emulator
+
+The repository continuously runs a complete finite ADB Ready job on a real
+headless Linux emulator. The runner layer creates and owns the AVD; ADB Ready
+binds to its exact serial, verifies boot and unlock state, executes the bounded
+check, writes normalized NDJSON and evidence, and leaves emulator teardown to
+the owning layer.
+
+Use the maintained, commit-pinned workflow and fixture as the starting point:
+
+- [Android emulator workflow](../.github/workflows/android-emulator.yml)
+- [CI emulator fixture](../examples/ci-emulator/)
+
+The evidence upload uses `if: always()` so a product assertion or verifier
+failure retains the same manifest, result, JUnit, native files, and GitHub step
+summary as a successful run. A failure before ADB Ready starts cannot produce
+an ADB Ready bundle and is reported by the provisioning step instead.
+
+### Self-hosted physical target
+
+Use the maintained [physical-device recipe](../examples/ci-physical/) when a
+dedicated self-hosted runner owns one pre-authorized Android phone or tablet.
+The workflow is manual-only, routes through an explicit `android-device`
+runner label, queues competing GitHub jobs, and still relies on ADB Ready's
+host-local target lease as the final ownership boundary.
+
+The configured serial must match one `adb devices -l` row exactly. Missing,
+`unauthorized`, `offline`, replaced, and concurrently owned targets fail before
+the verifier can mutate another device. ADB Ready does not restart the shared
+ADB server, approve Android's RSA dialog, or claim a distributed lock across
+runner machines.
+
+Do not expose a physical self-hosted runner to untrusted pull requests. Keep
+the runner and its custom label scoped to trusted repositories or runner
+groups, and keep the phone unlocked only when the project's assertions require
+it. The example verifier is read-only and intentionally captures no screenshot
+from a personal device.
+
+### Gradle-owned virtual devices
+
+When the Android build declares Gradle Managed Devices, keep lifecycle
+ownership with Gradle instead of treating its transient emulator as an ADB
+Ready target:
+
+```bash
+adb-ready test gradle
+adb-ready test gradle :app:pixel2api35DebugAndroidTest --dry-run
+adb-ready test gradle :app:pixel2api35DebugAndroidTest --software-rendering
+```
+
+ADB Ready preflights the exact task and normalizes fresh JUnit, HTML, shard,
+and Gradle failure evidence without replacing the build's device definitions
+or test DSL. See [Gradle Managed Devices](./gradle-managed-devices.md) for task
+groups, sharding, outcomes, and the ownership boundary.
+
+### Firebase-owned remote devices
+
+Use Firebase Test Lab when the provider should own remote physical or virtual
+targets while ADB Ready owns the deterministic invocation, outcome language,
+and bounded evidence handoff:
+
+```bash
+adb-ready test firebase devices --project my-project
+adb-ready test firebase instrumentation \
+  --project my-project \
+  --app app-debug.apk \
+  --test-apk app-debug-androidTest.apk \
+  --test-device model=Pixel2.arm,version=35 \
+  --dry-run --json
+```
+
+See [Firebase Test Lab](./firebase-test-lab.md) for live catalog policy,
+provider-owned lifecycle, result buckets, normalized outcomes, and explicit
+remote cancellation.

package/docs/configuration.md

@@ -58,6 +58,7 @@ existing file unless `--force` is explicit. Use `--dry-run` first.
 | `timeoutMs` | Default bounded operation timeout |
 | `output` | Interactive, animation, color, and Unicode preferences |
 | `targets.aliases` | Friendly name to exact ADB serial mapping |
+| `targets.pools` | Named explicit target sets with bounded concurrency and queue policy |
 | `dev` | Development-session configuration |
 | `profiles` | Named, optionally inherited overrides |
 
@@ -81,6 +82,11 @@ existing file unless `--force` is explicit. Use `--dry-run` first.
 Unknown keys and invalid nested values fail validation rather than being
 silently ignored.
 
+Target pools accept typed `adb`, `avd`, `remote-adb`, or `firebase` members.
+Every pool requires an explicit `maxConcurrency`; member IDs and resource
+identities must be unique. See [Target pools and fan-out](./target-pools.md) for
+the complete schema, execution semantics, and trust boundaries.
+
 `init` detects and writes `packageManager` only for Expo, React Native, and
 Capacitor presets, where it selects the project CLI. Flutter and native Gradle
 use their own launchers, so an unrelated package-manager executable available

package/docs/firebase-test-lab.md

@@ -0,0 +1,126 @@
+# Firebase Test Lab
+
+Use this workflow when Firebase should own the remote Android targets. ADB
+Ready validates exact dimensions against the live catalog, starts one bounded
+instrumentation or Robo matrix through `gcloud`, normalizes its outcome, and
+keeps local evidence. It does not create projects, manage billing, provision
+credentials, or replace Firebase's test formats.
+
+## Prerequisites
+
+Install the current [Google Cloud CLI](https://cloud.google.com/sdk/docs/install),
+authenticate it in the surrounding developer or CI environment, and enable
+Firebase Test Lab for the selected Google Cloud project. Credentials remain in
+Google's credential store; ADB Ready never writes access tokens into config,
+output, or evidence.
+
+Inspect the authenticated live catalog before choosing a matrix:
+
+```bash
+adb-ready test firebase devices --project my-project
+adb-ready test firebase devices --project my-project --json
+```
+
+Catalog output joins each model to its supported Android versions and reports
+form, form factor, capacity, and provider tags. A requested unavailable,
+inaccessible, deprecated, reduced-stability, zero-capacity, or low-capacity
+dimension fails before artifact upload. Deprecated, reduced-stability, and
+low-capacity choices require their matching explicit `--allow-*` policy.
+
+## Instrumentation
+
+Preview the exact direct `gcloud` invocation first:
+
+```bash
+adb-ready test firebase instrumentation \
+  --project my-project \
+  --app app/build/outputs/apk/debug/app-debug.apk \
+  --test-apk app/build/outputs/apk/androidTest/debug/app-debug-androidTest.apk \
+  --test-device model=Pixel2.arm,version=35,locale=en,orientation=portrait \
+  --dry-run --json
+```
+
+Remove `--dry-run` to create the matrix. Repeat `--test-device` for additional
+explicit dimensions. Local paths and private `gs://bucket/object` artifact
+references are supported; signed URLs are rejected so credentials cannot be
+retained accidentally.
+
+## Robo
+
+Robo needs the app artifact but no instrumentation APK:
+
+```bash
+adb-ready test firebase robo \
+  --project my-project \
+  --app app-debug.apk \
+  --test-device model=Pixel2.arm,version=35
+```
+
+`--test-timeout 10m` controls the provider-side timeout for each execution.
+`--run-timeout 30m` bounds only ADB Ready's local observation.
+
+## Results and evidence
+
+For deterministic CI retention, use a bucket your job can read and write:
+
+```bash
+adb-ready test firebase instrumentation \
+  --project my-project \
+  --app app-debug.apk \
+  --test-apk app-debug-androidTest.apk \
+  --test-device model=Pixel2.arm,version=35 \
+  --results-bucket gs://my-test-results \
+  --results-dir ci/$GITHUB_RUN_ID
+```
+
+ADB Ready always retains redacted `gcloud` output and the structured result
+under `.adb-ready/artifacts/firebase-<run-id>/`. With an explicit result bucket,
+it also lists only that exact prefix and downloads a bounded allowlist of native
+JUnit, HTML, JSON, log, screenshot, video, coverage, and protobuf artifacts:
+
+- at most 100 provider files;
+- at most 20 MiB per file;
+- at most 50 MiB total;
+- exact post-download size verification; and
+- a local `provider-files.json` source manifest.
+
+The structured result reports `complete`, `unavailable`, `remote-running`, or
+`not-configured` evidence collection. Failure to copy requested provider
+evidence is a warning alongside the original test outcome; it never rewrites a
+test assertion into a false pass or a different provider outcome.
+
+Without an explicit bucket, the Firebase console URL remains the provider
+result reference and only local normalized evidence is copied.
+
+## Outcomes and cancellation
+
+ADB Ready preserves the documented `gcloud firebase test android run` result
+classes instead of flattening them:
+
+- `passed`;
+- `flaky` — provider roll-up succeeded but at least one test was flaky;
+- `assertion-failed`;
+- `inconclusive`;
+- `unsupported`;
+- `cancelled`;
+- `infrastructure-failed`;
+- `auth-failed`; and
+- local `observation-timed-out` or `observation-stopped`.
+
+Stopping or timing out local observation intentionally leaves an identified
+remote matrix running. Cancel exactly one matrix with a separate explicit
+action:
+
+```bash
+adb-ready test firebase cancel MATRIX_ID --project my-project --dry-run
+adb-ready test firebase cancel MATRIX_ID --project my-project
+```
+
+Cancellation obtains a short-lived access token from the authenticated
+`gcloud` process in memory and calls the official Testing API. The token is not
+stored or printed.
+
+See Firebase's current [Android CLI guide](https://firebase.google.com/docs/test-lab/android/command-line),
+[available-device guidance](https://firebase.google.com/docs/test-lab/android/available-testing-devices),
+and [result documentation](https://firebase.google.com/docs/test-lab/android/analyzing-results)
+for provider setup, billing, quotas, and native result semantics.

package/docs/gradle-managed-devices.md

@@ -0,0 +1,105 @@
+# Gradle Managed Devices
+
+Use this workflow when the Android build already declares virtual devices or
+device groups in Gradle. Gradle remains the lifecycle owner: it provisions the
+emulator, installs the app and tests, applies sharding, runs instrumentation,
+and tears the target down. ADB Ready does not select, lease, or send commands to
+that transient emulator.
+
+## Discover declared tasks
+
+Run discovery from the Gradle project root:
+
+```bash
+adb-ready test gradle
+```
+
+ADB Ready invokes the checked-in `gradlew` or `android/gradlew` Wrapper and
+lists only task descriptions that identify a managed device or device group.
+If the Wrapper lives elsewhere, pass it explicitly:
+
+```bash
+adb-ready test gradle --gradle tools/gradlew
+```
+
+Task names belong to the project. Typical Android Gradle Plugin names resemble
+`pixel2api35DebugAndroidTest` and
+`phoneAndTabletGroupDebugAndroidTest`; ADB Ready does not invent a device,
+variant, or group name.
+
+## Preview and run one task
+
+Preview the exact direct process invocation without starting Gradle:
+
+```bash
+adb-ready test gradle :app:pixel2api35DebugAndroidTest --dry-run --json
+```
+
+Then execute the same bounded task:
+
+```bash
+adb-ready test gradle :app:pixel2api35DebugAndroidTest --run-timeout 20m
+```
+
+Before execution, ADB Ready asks Gradle to resolve that exact task. A missing
+task fails before test infrastructure starts. The task is passed directly to
+the Wrapper without a shell.
+
+## Groups, sharding, and server rendering
+
+A declared group task runs through the same boundary:
+
+```bash
+adb-ready test gradle :app:phoneAndTabletGroupDebugAndroidTest
+```
+
+Request Gradle's managed-device sharding property when the build and Android
+Gradle Plugin support it:
+
+```bash
+adb-ready test gradle :app:pixel2api35DebugAndroidTest --shards 4
+```
+
+On a headless host, opt into Gradle's documented SwiftShader property:
+
+```bash
+adb-ready test gradle :app:pixel2api35DebugAndroidTest --software-rendering
+```
+
+ADB Ready passes these properties for the current invocation. It never edits
+Gradle files, creates SDK components, or changes a project's declared devices.
+
+## Results and evidence
+
+After execution, ADB Ready reads native files from the Android Gradle Plugin
+managed-device result and report directories. It retains bounded XML,
+HTML, JSON, logs, text, screenshots, and video under:
+
+```text
+.adb-ready/artifacts/gradle-managed-<run-id>/
+```
+
+Machine output keeps these outcomes distinct:
+
+- `passed` — Gradle exited successfully and retained JUnit has no failures;
+- `assertion-failed` — fresh JUnit reports a failed or errored test;
+- `infrastructure-failed` — Gradle could not complete provisioning or execution
+  and no test assertion explains the failure;
+- `timed-out` — the configured finite timeout expired;
+- `cancelled` — the caller interrupted the task;
+- `GRADLE_MANAGED_TASK_NOT_FOUND` — exact task preflight failed.
+
+The original Gradle result and report trees remain the source artifacts. The
+ADB Ready copy is bounded, redacted where textual, and convenient for CI upload
+or an agent. Failed tasks can only classify assertions from files written by
+that execution. A successful up-to-date Gradle task may retain the output that
+Gradle validated from its cache, explicitly marked with `gradle-cache`
+provenance.
+
+## Responsibility boundary
+
+Use `adb-ready test gradle` for Gradle-owned virtual devices. Use
+`adb-ready run` when ADB Ready must own one already visible ADB target, prepare
+ports and a development service, run a finite verifier, and clean only its own
+resources. Connected-device tasks therefore remain under `run`; they are not
+misrepresented as Gradle Managed Devices.

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