adb-ready 0.6.0 → 0.8.0

package/docs/automation.md

@@ -198,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
@@ -265,3 +279,78 @@ fragile parsing of human log messages.
 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/completions.md

@@ -0,0 +1,61 @@
+# Shell completion
+
+ADB Ready generates static tab-completion scripts for both `adb-ready` and its
+short alias, `adbr`. Generation is instant and offline: it does not load project
+configuration, start ADB, or inspect a device.
+
+## Bash
+
+```bash
+mkdir -p ~/.local/share/bash-completion/completions
+adb-ready completion bash > ~/.local/share/bash-completion/completions/adb-ready
+```
+
+Start a new shell. If the user completion directory is not loaded by your Bash
+installation, source the generated file from `~/.bashrc`.
+
+## zsh
+
+```zsh
+mkdir -p ~/.zfunc
+adb-ready completion zsh > ~/.zfunc/_adb-ready
+```
+
+Add the directory before `compinit` in `~/.zshrc`:
+
+```zsh
+fpath=(~/.zfunc $fpath)
+autoload -Uz compinit && compinit
+```
+
+## fish
+
+```fish
+mkdir -p ~/.config/fish/completions
+adb-ready completion fish > ~/.config/fish/completions/adb-ready.fish
+```
+
+fish loads the file automatically in new shell sessions.
+
+## PowerShell
+
+```powershell
+New-Item -ItemType Directory -Force (Split-Path $PROFILE) | Out-Null
+adb-ready completion powershell | Out-File -Append -Encoding utf8 $PROFILE
+```
+
+Reload the profile with `. $PROFILE` or open a new PowerShell session.
+
+## Nushell
+
+```nu
+mkdir ($nu.data-dir | path join "vendor" "autoload")
+adb-ready completion nushell | save --force ($nu.data-dir | path join "vendor" "autoload" "adb-ready.nu")
+```
+
+Nushell loads vendor autoload files in new sessions. The generated declarations
+complete public commands while preserving ordinary file completion for command
+arguments.
+
+Regenerate the script after upgrading ADB Ready so newly added commands become
+available to the shell.

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/target-pools.md

@@ -0,0 +1,151 @@
+# Target pools and fan-out
+
+Use a target pool when the same bounded verification must run against an
+explicit set of Android targets. Pool mode is opt-in. A normal `adb-ready run`
+still selects exactly one target.
+
+Every acquired member receives its own single-target session, target lease,
+verifier result, cleanup, and evidence bundle. The pool result aggregates those
+unchanged member envelopes in declaration order.
+
+## Declare a local pool
+
+```json
+{
+  "$schema": "./node_modules/adb-ready/schema/config-v1.schema.json",
+  "version": 1,
+  "targets": {
+    "pools": {
+      "smoke": {
+        "maxConcurrency": 2,
+        "failFast": false,
+        "leaseWaitMs": 30000,
+        "members": [
+          { "id": "desk", "kind": "adb", "serial": "R3CT..." },
+          { "id": "api36", "kind": "avd", "name": "Pixel_9_API_36" },
+          {
+            "id": "lab",
+            "kind": "remote-adb",
+            "host": "android-lab.internal",
+            "port": 5037,
+            "serial": "10.20.0.15:5555"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Run the same verifier on every member:
+
+```bash
+adb-ready run --pool smoke -- npm run test:e2e
+```
+
+Preview every member without inspecting ADB, starting an AVD, or running the
+verifier:
+
+```bash
+adb-ready run --pool smoke --dry-run --json -- npm run test:e2e
+```
+
+The pool owns concurrency policy; it never infers an unbounded worker count.
+Override it for one invocation only when the CI runner has known capacity:
+
+```bash
+adb-ready run --pool smoke --max-concurrency 1 --fail-fast \
+  --lease-wait 45s -- npm run test:e2e
+```
+
+## Member kinds
+
+| Kind | Required fields | Ownership |
+| --- | --- | --- |
+| `adb` | `id`, exact `serial` | Uses an already ADB-visible target. |
+| `avd` | `id`, exact existing AVD `name` | Reuses or starts that AVD; stops only an emulator process started by this run. |
+| `remote-adb` | `id`, `host`, exact `serial`; optional `port` | Uses the explicit ADB server without changing the global local server. |
+| `firebase` | `id`, `model`, `version`; optional `locale`, `orientation` | Firebase owns the remote target and lifecycle. Use only with `test firebase`. |
+
+Member IDs and resource identities must be unique inside a pool. Members are
+required by default. Set `"required": false` only when that dimension is truly
+informational; an optional failure remains visible but does not fail the
+aggregate.
+
+## Firebase dimensions
+
+A Firebase-only pool submits one independently observable matrix per declared
+dimension. This gives every dimension a stable member result and lets ADB Ready
+bound submission concurrency.
+
+```json
+{
+  "version": 1,
+  "targets": {
+    "pools": {
+      "firebase-smoke": {
+        "maxConcurrency": 2,
+        "failFast": true,
+        "members": [
+          { "id": "pixel-api35", "kind": "firebase", "model": "akita", "version": "35" },
+          { "id": "tablet-api34", "kind": "firebase", "model": "tangorpro", "version": "34" }
+        ]
+      }
+    }
+  }
+}
+```
+
+```bash
+adb-ready test firebase instrumentation \
+  --pool firebase-smoke \
+  --project my-project \
+  --app app-debug.apk \
+  --test-apk app-debug-androidTest.apk
+```
+
+Dimensions are checked against the live Firebase catalog before upload. With
+`failFast`, ADB Ready stops submitting queued dimensions after a required
+failure. It does not cancel matrices already running remotely. Use
+`adb-ready test firebase cancel` for an intentional provider cancellation.
+
+## Queueing and leases
+
+ADB Ready serializes contending work with an owner-recorded, heartbeating lease.
+`leaseWaitMs` bounds how long a pool member waits; cancellation exits the queue
+without taking ownership. Expired leases and leases owned by a dead process on
+the same host are recovered conservatively.
+
+The built-in coordination backend is a per-user filesystem on one host. It is
+not a distributed lock. CI jobs on different machines need runner-level
+routing or another explicit external coordination system. ADB Ready never
+infers cross-host ownership.
+
+An explicit remote ADB server is also a trust boundary: its socket is not
+encrypted by ADB Ready. Protect it with a trusted private network, VPN, SSH
+tunnel, or equivalent transport; never expose port 5037 to an untrusted
+network.
+
+## Aggregate result
+
+Human output shows the status of every member. JSON and NDJSON preserve every
+nested result envelope, including its command ID, structured problems,
+timestamps, and evidence path. The aggregate cannot report success when any
+required member failed, disappeared, was cancelled, or never started.
+
+Useful automation fields:
+
+```text
+data.pool
+data.maxConcurrency
+data.failFast
+data.coordination
+data.members[].id
+data.members[].status
+data.members[].exitCode
+data.members[].result
+data.summary
+```
+
+Pool configuration is declarative data. It cannot add executable hooks or
+shell fragments, and every verifier continues to use direct argv execution.

package/docs/targets-and-wireless.md

@@ -96,6 +96,21 @@ This is useful for WSL, containers, VMs, SSH-forwarded workstations, and device
 labs. ADB Ready does not start, kill, or reconfigure that shared server
 implicitly.
 
+Before every command sent through an explicit `--adb-host` or `--adb-port`, ADB
+Ready opens a bounded read-only connection and requests only `host:version`.
+The real `adb` process starts only when the server protocol matches the local
+client. This matters because the upstream ADB client automatically sends
+`host:kill` when it encounters a mismatched server version (see the
+[AOSP ADB client implementation](https://android.googlesource.com/platform/packages/modules/adb/+/refs/heads/main/client/adb_client.cpp)).
+ADB Ready instead returns `ADB_REMOTE_SERVER_PROTOCOL_MISMATCH` and leaves the
+shared server untouched.
+
+The preflight also distinguishes an unreachable route, timeout, cancellation,
+and a non-ADB response. It is repeated before each command so replacement of a
+server during a long session fails closed. This is a narrow safety handshake,
+not a replacement ADB transport; all device operations still use the selected
+`adb` executable.
+
 ## Network limitations
 
 Wireless discovery and connection can be blocked by guest Wi-Fi, client
@@ -110,6 +125,12 @@ adb-ready doctor --verbose
 adb-ready devices
 ```
 
+For WSL, a container, VM, or remote runner, first verify that its network
+namespace can reach the exact protected ADB host and port. A successful DNS
+lookup or mDNS discovery does not prove that the TCP route is usable. ADB Ready
+reports this as `ADB_REMOTE_SERVER_UNREACHABLE` rather than an empty target
+list.
+
 If discovery is unavailable but the device shows a reachable connection
 endpoint, pass it explicitly. Do not assume port `5555`; modern Wireless
 debugging ports are dynamic.

package/docs/troubleshooting.md

@@ -21,6 +21,9 @@ adb-ready context --since 5m --only problems,recovery,logs
 | `ADB_NOT_FOUND` | No usable ADB executable was resolved | Install Platform-Tools or pass `--adb PATH` |
 | `ADB_SERVER_UNAVAILABLE` | The selected local or remote server could not be queried | Check the configured host/port and run `adb start-server` explicitly if appropriate |
 | `ADB_VERSION_MISMATCH` | Client and server report incompatible versions | Align Platform-Tools versions; review before restarting the shared server |
+| `ADB_REMOTE_SERVER_UNREACHABLE` | The explicit server socket has no usable route | Check WSL/container/VM/VPN/firewall/tunnel routing; do not expose port 5037 publicly |
+| `ADB_REMOTE_SERVER_PROTOCOL_MISMATCH` | Remote and local ADB protocols differ | Align Platform-Tools deliberately; ADB Ready will not let upstream ADB kill the shared server |
+| `ADB_REMOTE_SERVER_INVALID_RESPONSE` | The endpoint or local client could not complete the read-only protocol preflight | Verify the host, port, tunnel destination, and local Platform-Tools installation |
 | `TARGET_UNAUTHORIZED` | Android has not authorized this host | Unlock the device and accept its RSA debugging prompt |
 | `TARGET_NO_PERMISSIONS` | The host cannot access the USB device | Fix host USB permissions or rules, then reconnect |
 | `TARGET_OFFLINE` | ADB knows the transport but it is not ready | Check cable/network state and retry `devices` |

package/examples/README.md

@@ -15,8 +15,14 @@ adb-ready dev --dry-run
 - [`flutter/adb-ready.config.json`](./flutter/adb-ready.config.json)
 - [`capacitor/adb-ready.config.json`](./capacitor/adb-ready.config.json)
 - [`custom/adb-ready.config.json`](./custom/adb-ready.config.json)
+- [`ci-emulator/`](./ci-emulator/) — maintained GitHub-hosted emulator
+  acceptance with a finite run and retained failure evidence
+- [`ci-physical/`](./ci-physical/) — manual self-hosted physical-device job
+  with explicit serial selection, host-local leasing, and bounded evidence
 - [`automation/README.md`](./automation/README.md) — one finite AVD, deployment,
   verifier, evidence, and cleanup job
+- [`target-pools/`](./target-pools/) — bounded fan-out across explicit local,
+  AVD, remote-ADB, or Firebase members
 
 Prefer `adb-ready init` when starting from an existing detected project. Add
 only the ports, hooks, and retention rules that the project genuinely needs.

package/examples/ci-emulator/README.md

@@ -0,0 +1,32 @@
+# GitHub-hosted Android emulator
+
+This fixture powers ADB Ready's maintained emulator acceptance workflow. It
+demonstrates the ownership boundary used in ordinary CI:
+
+1. the runner provisions and owns one Android emulator;
+2. ADB Ready binds a finite run to its exact serial;
+3. the fixture verifies Android boot and identity, opens Settings, and captures
+   native evidence; and
+4. ADB Ready retains normalized NDJSON, JUnit, screenshot, window, and manifest
+   evidence before the runner tears its emulator down.
+
+The workflow is [`android-emulator.yml`](../../.github/workflows/android-emulator.yml).
+Every external Action is pinned to a full commit. The job uses no repository
+secret and uploads evidence with `if: always()`.
+
+Do not copy the fixture's custom development process into an application. Keep
+your real project command and readiness assertions, then use the same bounded
+shape:
+
+```bash
+npx adb-ready run \
+  --device emulator-5554 \
+  --run-timeout 10m \
+  --json \
+  --non-interactive \
+  -- npm run test:e2e
+```
+
+ADB Ready does not implicitly create SDKs or AVDs. If another workflow layer
+created the emulator, ADB Ready attaches without claiming ownership and leaves
+emulator teardown to that layer.

package/examples/ci-emulator/adb-ready.config.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "../../schema/config-v1.schema.json",
+  "version": 1,
+  "dev": {
+    "preset": "custom",
+    "command": {
+      "executable": "node",
+      "args": ["examples/ci-emulator/dev-service.mjs"]
+    },
+    "reversePorts": [],
+    "logs": false,
+    "cleanupPorts": true,
+    "watch": true,
+    "ready": {
+      "timeoutMs": 60000,
+      "pollIntervalMs": 1000,
+      "all": [{ "kind": "boot" }, { "kind": "unlocked" }]
+    }
+  }
+}