adb-ready 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -9,6 +9,116 @@ breaking changes.
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-11
+
+### Changed
+
+- Clarify package ownership and normalize the maintainer identity used by
+  repository history and published package metadata.
+- Reorganize the public README around six user outcomes and explicit entry
+  paths for coding agents, terminal users, and CI automation.
+- Add copy-and-paste installation paths for npm, pnpm, Yarn, and Bun.
+- Replace the simulated terminal snippet with an optimized product walkthrough
+  showing development startup, UI verification, and agent-driven recovery,
+  while keeping the marketing asset out of the installed npm package.
+- Require an explicit release tag when manually dispatching the release
+  workflow instead of retaining a stale version default.
+
+## [0.3.0] - 2026-09-11
+
+### Added
+
+- Scope saved sessions, latest-problem lookup, AI context, and MCP session
+  resources to the canonical current project by default, with an explicit
+  `--all-projects` escape hatch for cross-project audits.
+- Add privacy-safe cross-process Android target leases with heartbeats, bounded
+  expiry, stale-owner recovery, and ownership-checked cleanup for app, UI,
+  port, recording, and development-session mutations.
+- Let `dev --dry-run` resolve and validate the project, command, ports, and
+  lifecycle hooks without requiring ADB or allocating an Android target. An
+  explicit target selector still produces the target-resolved plan.
+- Add composable readiness contracts for boot, unlock, process, foreground
+  activity, exact UI selectors, host ports, HTTP responses, and bounded log
+  presence or absence. Expo and React Native sessions now verify Android boot
+  and Metro reachability before reporting ready.
+- Add `adb-ready run -- COMMAND` as a finite automation entrypoint: start the
+  configured development service, satisfy readiness, execute one timeout-bound
+  verification command, preserve its exit code, and clean owned resources.
+- Produce an atomic, redacted evidence bundle for every executed `run` with a
+  versioned manifest, structured result, NDJSON timeline, problems, logcat,
+  bounded AI context, JUnit XML, and GitHub step-summary Markdown.
+- Advertise and validate a versioned result-envelope output schema for every
+  MCP tool, return screenshot pixels as MCP image content, and issue stable
+  connection-scoped target handles that reject stale or cross-connection use.
+- Let MCP `ensure_ready` reconnect an explicitly addressed endpoint or the only
+  unambiguous paired wireless service before binding it.
+- Exercise the complete MCP contract on Node.js, Bun, and Deno across both the
+  legacy 2025-11-25 and modern 2026-07-28 protocol eras.
+- Add semantic UI find, assert, digest comparison, and selector-driven tap or
+  long-press workflows. Structured selectors support exact, prefix, and
+  contains matching plus enabled/actionable qualifiers; ambiguous mutations
+  fail instead of guessing.
+- Add project-scoped `start_dev_session`, `get_dev_session`, and
+  `stop_dev_session` MCP tools backed by opaque durable handles. Managed
+  sessions continue outside one tool call, survive client reconnects, report
+  heartbeats and terminal exit state, and stop only their verified owned
+  process group.
+- Add status, recency, preset, and count filters to project-scoped session
+  history.
+- Install a single APK or a complete split APK set through verified `install`
+  and `install-multiple` workflows in both CLI and MCP.
+- Detect and run Flutter and Capacitor Android projects on the exact selected
+  target, with boot readiness and no invented default port mappings.
+- Add intent-level UI read, field fill/clear, and container-scoped scroll
+  workflows for CLI and MCP. Field replacement is capability-gated before
+  mutation and verifies observable values instead of inferring success from
+  input exit codes.
+- Add a project-scoped MCP session index with status, preset, recency, limit,
+  and stable cursor pagination so agents can locate relevant saved evidence
+  without scanning unrelated history.
+- Add a bounded CLI/MCP screen audit that identifies enabled actionable nodes
+  without human-readable labels and controls without stable resource IDs,
+  returning concrete nodes instead of a subjective score.
+- Bind finite verification commands to the leased target through
+  `ANDROID_SERIAL`, `ADB_READY_TARGET_SERIAL`, and an explicit
+  `{target.serial}` argument placeholder for tools such as Maestro that require
+  their own device flag.
+- Report measured acquisition time alongside every before/after UI snapshot so
+  agents and CI can identify slow accessibility inspection without guessing.
+
+### Changed
+
+- Compact repeated successful health checks in bounded AI context while
+  preserving the complete redacted NDJSON timeline as source evidence.
+- Reorganize the interactive home around development, test automation, device,
+  debugging, and project tasks; preserve root presentation flags and use copy
+  that remains meaningful in narrow terminals.
+- Add the screen agent-readiness audit to the task-oriented Debug & evidence
+  menu without expanding the root menu.
+- Lead the public README with the agent outcome, immediate setup, and a concrete
+  first task before the implementation details.
+
+### Fixed
+
+- Return a structured capability overview for bare machine-mode invocation and
+  suggest high-confidence corrections for mistyped commands or options.
+- Apply retention limits per project before the global safety cap so one noisy
+  project cannot evict another project's recent diagnostic history.
+- Keep packaged command-matrix development sessions inside an isolated
+  temporary state directory instead of polluting the user's session store.
+- Correct the public installation guide so its compatibility note no longer
+  contradicts the documented split APK support.
+- Give accessibility hierarchy acquisition its own 15-second default deadline
+  in inspect and UI workflows while preserving an explicit global timeout.
+  This prevents ordinary slower OEM UI Automator dumps from failing at the
+  generic five-second ADB boundary.
+- Classify Android's successful-exit `could not get idle state` response as a
+  distinct `UI_NOT_IDLE` problem with a safe recovery instruction instead of
+  misreporting an inaccessible hierarchy.
+- Finalize an explicitly stopped managed development task as interrupted even
+  when Windows terminates the owned child before its signal handler can write
+  the terminal record.
+
 ## [0.2.0] - 2026-09-10
 
 ### Added
@@ -81,7 +191,9 @@ breaking changes.
   explainable configuration precedence.
 - Human, plain, JSON, and NDJSON output across Node, Bun, and Deno entrypoints.
 
-[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/Adam014/adb-ready/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/Adam014/adb-ready/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/Adam014/adb-ready/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Adam014/adb-ready/compare/v0.1.2...v0.2.0
 [0.1.2]: https://github.com/Adam014/adb-ready/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/Adam014/adb-ready/compare/v0.1.0...v0.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 ADB Ready contributors
+Copyright (c) 2026 Adam Stádník
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -2,10 +2,10 @@
 
 # ADB Ready
 
-**Make Android development accessible to coding agents.**
+**The local Android runtime for coding agents.**
 
-An MCP-native, local-first CLI that gives agents and developers safe, typed
-control of Android targets, apps, UI, logs, evidence, and development sessions.
+Prepare one Android target, run your project, operate the app, and return
+verified evidence—for developers, agents, and CI.
 
 [![MCP](https://img.shields.io/badge/MCP-native-7c3aed)](./docs/agent-integration.md)
 [![CI](https://github.com/Adam014/adb-ready/actions/workflows/ci.yml/badge.svg)](https://github.com/Adam014/adb-ready/actions/workflows/ci.yml)
@@ -13,234 +13,222 @@ control of Android targets, apps, UI, logs, evidence, and development sessions.
 [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
 [![Bun](https://img.shields.io/badge/Bun-tested-14151a?logo=bun&logoColor=white)](https://bun.sh/)
 [![Deno](https://img.shields.io/badge/Deno_2-tested-111827?logo=deno&logoColor=white)](https://deno.com/)
+[![Flutter](https://img.shields.io/badge/Flutter-supported-02569B?logo=flutter&logoColor=white)](./docs/dev-sessions.md)
+[![Capacitor](https://img.shields.io/badge/Capacitor-supported-119EFF?logo=capacitor&logoColor=white)](./docs/dev-sessions.md)
 [![Platforms](https://img.shields.io/badge/hosts-macOS_%C2%B7_Linux_%C2%B7_Windows-64748b)](./COMPATIBILITY.md)
 
-[Quick start](#quick-start) · [AI agents](#android-tools-built-for-ai-agents) · [Why ADB Ready](#why-adb-ready) ·
-[Workflows](#find-your-workflow) · [Documentation](#documentation) ·
-[Compatibility](#compatibility)
+[Quick start](#quick-start) · [What it does](#what-adb-ready-does) ·
+[AI agents](#with-a-coding-agent) · [CI](#in-ci-and-automation) ·
+[Documentation](#documentation)
+
+<img src="https://raw.githubusercontent.com/Adam014/adb-ready/main/docs/assets/adb-ready-demo.gif" alt="ADB Ready prepares an Android development session, verifies the app UI, and lets a coding agent recover lost localhost access." width="1120" />
 
 </div>
 
-```text
-$ adb-ready dev
+## Quick start
 
-✓ Android target selected       Pixel 9 · wireless
-✓ Localhost ports ready         8081 → 8081
-✓ Development command started   pnpm run start --android
-● Session healthy               watching target, ports, and logs
-```
+Install ADB Ready in the Android project your team wants to run:
 
-Stop rebuilding your Android setup every time a cable moves, Wi-Fi reconnects,
-or ADB picks the wrong device. ADB Ready turns scattered ADB operations into
-one deterministic workflow that developers, scripts, and AI agents can share.
+**npm** · default
 
 ```bash
+npm install --save-dev adb-ready
 npx adb-ready dev
 ```
 
-## Android tools built for AI agents
+<details>
+<summary><strong>Use pnpm, Yarn, or Bun</strong></summary>
 
-ADB Ready turns coding agents from passive log readers into safe Android
-operators. Its local MCP server exposes **19 schema-validated tools** for target
-readiness, app lifecycle, UI inspection, evidence capture, and verified UI
-actions—without giving the model a generic shell or unrestricted ADB access.
+#### pnpm
 
 ```bash
-# Connect the current project to your coding agent
-npx adb-ready agent setup codex
+pnpm add --save-dev adb-ready
+pnpm exec adb-ready dev
 ```
 
-Codex, Claude Code, Cursor, VS Code/Copilot, Windsurf, and other MCP clients can:
+#### Yarn
 
-- find and bind one deterministic Android target;
-- resolve, install, launch, restart, and inspect the project app;
-- inspect current UI, tap, type, swipe, press keys, and wait for state changes;
-- capture screenshots and read bounded, redacted session evidence; and
-- verify actions against fresh device state instead of assuming they worked.
+```bash
+yarn add --dev adb-ready
+yarn adb-ready dev
+```
 
-Everything stays local unless your chosen AI client sends tool results to its
-model provider. Stale UI references are rejected, destructive app removal is
-not exposed to agents, and every tool returns structured evidence.
+#### Bun
 
-[Connect an AI agent in minutes →](./docs/agent-integration.md)
+```bash
+bun add --dev adb-ready
+bunx adb-ready dev
+```
 
-## Why ADB Ready?
+</details>
 
-### Start once. Stay ready.
+ADB Ready handles the state around ADB that a person, script, or coding agent
+should not guess: which device belongs to the run, whether the app is ready,
+which ports and processes the session owns, and what evidence survives a
+failure. It orchestrates your real ADB and framework tools; it does not replace
+them or require an ADB Ready account, hosted service, or model API key.
 
-ADB Ready finds one usable Android target, prepares its ports, launches your
-project with the correct `ANDROID_SERIAL`, and watches the session while you
-work.
+Running `adb-ready` without a command opens the interactive workflow home.
+`adbr` is the shorter alias for the same CLI.
 
-### Recover without the ritual.
+## What ADB Ready does
 
-When a wireless target or reverse mapping disappears, recovery is bounded,
-target-safe, and independently verified. It never silently restarts the shared
-ADB server or rewrites another tool's mapping.
+- [**Run the project**](./docs/dev-sessions.md) — select one target, prepare
+  ports, launch the framework, and keep the session healthy.
+- [**Connect the device**](./docs/targets-and-wireless.md) — discover, pair,
+  reconnect, and deterministically bind a physical device or emulator.
+- [**Operate the app**](./docs/apps-and-evidence.md#app-lifecycle) — resolve,
+  install, launch, restart, deep-link, and inspect the project app.
+- [**Verify the UI**](./docs/ui-automation.md) — find semantic elements, act
+  by intent, assert state, and capture the screen.
+- [**Debug with evidence**](./docs/logs-and-context.md) — keep focused logs,
+  session history, screenshots, recordings, and redacted context together.
+- [**Automate a real device**](./docs/automation.md#run-one-bounded-verification)
+  — gate a finite command on readiness and return stable results, reports, and
+  artifacts.
 
-### Give agents evidence, not terminal noise.
+## Choose how you work
 
-Focused logcat, structured problems, and a saved redacted timeline keep the
-important failure evidence together. Agents receive bounded, machine-readable
-context and typed actions instead of guessing from an unstructured terminal.
+### With a coding agent
 
-### Keep your existing stack.
+Connect the current project to Codex, Claude Code, Cursor, VS Code/Copilot,
+Windsurf, or another MCP client:
 
-ADB Ready orchestrates the real ADB, framework, and package manager you already
-use. It does not replace Android Studio or force your project onto Bun.
+```bash
+npx adb-ready agent setup codex
+```
 
-| Projects                              | Package managers        | CLI runtimes         |
-| ------------------------------------- | ----------------------- | -------------------- |
-| Expo · React Native · Gradle · custom | npm · pnpm · Yarn · Bun | Node.js · Bun · Deno |
+Then ask for the outcome you want:
 
-## Quick start
+> Start this Expo app on my Android phone, wait until the login screen is
+> actually ready, verify my change, and keep the failure evidence.
 
-You need Android SDK Platform-Tools and Node.js 22 or newer for the standard npm
-entrypoint.
+The local MCP server gives agents typed tools for target readiness, durable
+development sessions, app lifecycle, semantic UI, logs, screenshots, and saved
+evidence. Every result is schema-validated and checked against fresh device
+state. Agents do not receive a generic shell, unrestricted raw ADB, or app
+removal.
+
+[Connect an AI agent in minutes →](./docs/agent-integration.md)
+
+### From your terminal
+
+Check the host, inspect visible targets, and start the complete development
+loop:
 
 ```bash
-# Check ADB and the host
 npx adb-ready doctor
-
-# See connected and wireless targets
 npx adb-ready devices
-
-# Start the complete development session
 npx adb-ready dev
 ```
 
-Add it to a project when the team should share one version:
+Expo, React Native, Flutter, Capacitor, Gradle, and custom commands all run
+against the same selected target through `ANDROID_SERIAL`. Add local services
+with repeated `--port` flags or replace the detected command after `--`:
 
 ```bash
-npm install --save-dev adb-ready
-npx adb-ready init
-npx adb-ready dev
+adb-ready dev --port 8081 --port 8000
+adb-ready dev -- pnpm run android:local
+adb-ready dev --dry-run --json
 ```
 
-Running `adb-ready` without a command opens the interactive workflow home.
-`adbr` is the shorter alias for the same CLI.
-
-[Read the five-minute setup →](./docs/getting-started.md)
-
-## Find your workflow
-
-| I want to…                                                  | Start here                                                                          |
-| ----------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| launch Expo, React Native, Gradle, or my own command        | [`adb-ready dev`](./docs/dev-sessions.md)                                           |
-| pair or reconnect an Android device over Wi-Fi              | [Targets and Wireless debugging](./docs/targets-and-wireless.md)                    |
-| choose the right device when several are connected          | [Deterministic target selection](./docs/targets-and-wireless.md#explicit-selection) |
-| expose Metro, a local API, or a debugger to Android         | [Port workflows](./docs/dev-sessions.md#port-ownership)                             |
-| install, inspect, launch, restart, or deep-link my app      | [App lifecycle](./docs/apps-and-evidence.md#app-lifecycle)                          |
-| save a verified screenshot or bounded screen recording      | [Evidence capture](./docs/apps-and-evidence.md#evidence-capture)                    |
-| give a developer or agent one bounded app/UI snapshot       | [Structured inspection](./docs/apps-and-evidence.md#structured-inspection)          |
-| safely tap, type, swipe, press keys, or wait for Android UI | [Safe UI automation](./docs/ui-automation.md)                                       |
-| see only the Android logs that matter                       | [Focused logcat](./docs/logs-and-context.md#focused-logcat)                         |
-| understand why the last session failed                      | [Session problems](./docs/logs-and-context.md#session-history)                      |
-| prepare safe evidence for an AI assistant                   | [Diagnostic context](./docs/logs-and-context.md#diagnostic-context)                 |
-| connect Codex, Claude Code, Cursor, Copilot, or Windsurf    | [`adb-ready agent setup`](./docs/agent-integration.md#connect-an-agent)             |
-| share project settings without a custom shell script        | [Configuration](./docs/configuration.md)                                            |
-| use ADB Ready from CI or another tool                       | [Automation contract](./docs/automation.md)                                         |
-| fix a known setup or target problem                         | [Troubleshooting](./docs/troubleshooting.md)                                        |
-
-## What happens in `adb-ready dev`?
+[Reach your first ready session →](./docs/getting-started.md)
 
-```text
-find or recover one target
-        ↓
-verify only the ports your project needs
-        ↓
-start the project on that same target
-        ↓
-watch target · ports · logs · child process
-        ↓
-recover safely or explain exactly what needs you
-```
+### In CI and automation
 
-- Expo and React Native receive reverse port `8081` by default.
-- Add any local service with repeated `--port` flags.
-- Pass any command after `--`; it runs directly without an implicit shell.
-- Existing matching mappings are reused. Conflicts are never overwritten.
-- On exit, only resources created by that session are cleaned up.
-- The final exit code and a bounded, redacted session record are preserved.
+Wait for declared readiness, execute one bounded verification command, preserve
+its exit code, and clean only resources created by the run:
 
 ```bash
-adb-ready dev --port 8081 --port 8000
-adb-ready dev -- pnpm run android:local
-adb-ready dev --dry-run --json
+npx adb-ready run -- npm run test:e2e
 ```
 
-## Built for humans, agents, and automation
-
-The interactive CLI provides keyboard navigation, live state, reduced-motion
-support, narrow-terminal fallbacks, and clear recovery feedback. Scripts get a
-separate deterministic contract:
+Each executed run retains a redacted evidence bundle with its result,
+timeline, problems, focused logcat, AI context, JUnit XML, and GitHub step
+summary. Scripts also get deterministic JSON and NDJSON contracts:
 
 ```bash
 adb-ready devices --json --non-interactive
 adb-ready logs --package com.example.app --format ndjson
-adb-ready context --since 5m --only problems,recovery,logs
+adb-ready sessions list --status failed --since 24h --limit 5
 ```
 
-- machine data on `stdout`, human diagnostics on `stderr`;
-- versioned JSON results and NDJSON events;
-- no prompt, animation, or terminal takeover in redirected/CI execution;
-- stable problem categories, meaningful exit codes, timeouts, and dry runs; and
-- explicit target, ADB path, and remote ADB server overrides.
+[Build a readiness-gated device job →](./docs/automation.md)
 
-Local AI agents use the same contracts through a schema-validated MCP stdio
-server. The package includes a version-matched public tool schema, while target
-binding, fresh-state checks, redaction, and verification remain enforced by ADB
-Ready itself. [Explore the agent contract →](./docs/agent-integration.md)
+## One target. One verified loop.
 
-## Documentation
+```text
+find or recover one Android target
+        ↓
+bind the complete run to that target
+        ↓
+prepare only the ports the project needs
+        ↓
+start the framework and wait for declared readiness
+        ↓
+watch target · ports · logs · child process
+        ↓
+recover safely or return bounded failure evidence
+```
 
-| Guide                                                            | What it answers                                                       |
-| ---------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [Getting started](./docs/getting-started.md)                     | How do I reach my first ready session?                                |
-| [Development sessions](./docs/dev-sessions.md)                   | What does ADB Ready own, watch, recover, and clean up?                |
-| [Targets and Wireless debugging](./docs/targets-and-wireless.md) | How are devices paired, connected, and selected safely?               |
-| [Apps and evidence](./docs/apps-and-evidence.md)                 | How do I control one app and capture verified device evidence?        |
-| [AI agent integration](./docs/agent-integration.md)              | How do Codex, Claude Code, Cursor, or Copilot use safe Android tools? |
-| [Safe UI automation](./docs/ui-automation.md)                    | How do humans and agents act on current UI with verifiable evidence?  |
-| [Logs and AI context](./docs/logs-and-context.md)                | What is captured, redacted, saved, and exported?                      |
-| [Configuration](./docs/configuration.md)                         | How do projects, profiles, hooks, and precedence work?                |
-| [Automation](./docs/automation.md)                               | What are the JSON, NDJSON, stdout, and exit-code contracts?           |
-| [Threat model](./docs/threat-model.md)                           | Which trust boundaries, controls, and residual risks apply?           |
-| [Troubleshooting](./docs/troubleshooting.md)                     | What should I do for each common failure?                             |
-| [Compatibility](./COMPATIBILITY.md)                              | Which hosts, runtimes, and environments are covered?                  |
-| [Example configs](./examples/README.md)                          | What can I copy for Expo, React Native, Gradle, or custom projects?   |
-
-Run `adb-ready --help` for the full command list or
-`adb-ready help COMMAND` for focused options.
+- Existing matching port mappings are reused; conflicts are not overwritten.
+- Wireless and port recovery is bounded and independently verified.
+- An ADB server restart is never hidden inside recovery.
+- On exit, ADB Ready cleans only resources owned by that session.
+- The final exit code and a project-scoped session record are preserved.
+
+## Keep your existing stack
 
-## Compatibility
+| Projects | Package managers | CLI runtimes | Hosts |
+| --- | --- | --- | --- |
+| Expo · React Native · Flutter · Capacitor · Gradle · custom | npm · pnpm · Yarn · Bun | Node.js · Bun · Deno | macOS · Linux · Windows |
 
-ADB Ready targets macOS, Linux, and Windows, with Node.js, Bun, and Deno runtime
-smoke coverage. The package is architecture-neutral JavaScript with no native
-addon or artificial OS/CPU block. A working ADB executable remains the only
+The standard npm entrypoint requires Android SDK Platform-Tools and Node.js 22
+or newer. The published package is architecture-neutral JavaScript with no
+native addon or artificial OS/CPU block. A working ADB executable remains the
 Android transport backend.
 
 [See tested and upstream-capable support tiers →](./COMPATIBILITY.md)
 
 ## Trust by default
 
-- The shared ADB server is never restarted implicitly.
-- Destructive or global actions are never hidden inside recovery.
+- One selected target is used consistently for every operation in a session.
+- Target leases prevent concurrent ADB Ready processes from mutating the same
+  target without an explicit takeover.
+- Destructive or device-wide actions require an explicit command or
+  confirmation.
 - Pairing codes never enter command-line arguments.
-- Session data is bounded, redacted, private to the user, and never uploaded.
-- Package contents are allowlisted and checked before release.
-- npm publication is prepared for short-lived OIDC credentials and provenance.
-- AI clients receive typed bounded tools; raw shell/ADB and destructive app
-  removal are not exposed through MCP.
-- UI references are bound to the current hierarchy digest, so stale targets are
-  rejected before input is sent.
+- Session data is bounded, redacted, private to the local user, and never
+  uploaded by ADB Ready.
+- Stale UI references are rejected before input is sent.
+- Machine data stays on `stdout`; human diagnostics stay on `stderr`.
+
+[Review the complete threat model →](./docs/threat-model.md)
+
+## Documentation
+
+| Guide | Start here when you want to… |
+| --- | --- |
+| [Getting started](./docs/getting-started.md) | Reach the first ready development session. |
+| [Development sessions](./docs/dev-sessions.md) | Configure frameworks, commands, ports, readiness, and cleanup. |
+| [Targets and Wireless debugging](./docs/targets-and-wireless.md) | Pair, connect, recover, or explicitly select a target. |
+| [Apps and evidence](./docs/apps-and-evidence.md) | Control the app and capture screenshots or recordings. |
+| [Safe UI automation](./docs/ui-automation.md) | Find, act on, and verify the current Android UI. |
+| [Logs and AI context](./docs/logs-and-context.md) | Diagnose a failure with bounded, redacted evidence. |
+| [AI agent integration](./docs/agent-integration.md) | Connect an MCP-capable coding agent. |
+| [Automation](./docs/automation.md) | Use readiness, exit codes, JSON, NDJSON, JUnit, and CI artifacts. |
+| [Configuration](./docs/configuration.md) | Share project presets, hooks, aliases, and policies. |
+| [Troubleshooting](./docs/troubleshooting.md) | Resolve a known setup, target, UI, or session problem. |
+| [Compatibility](./COMPATIBILITY.md) | Check hosts, runtimes, package managers, and support tiers. |
+| [Example configs](./examples/README.md) | Copy a framework or custom-project configuration. |
+
+Run `adb-ready --help` for the complete command list or
+`adb-ready help COMMAND` for focused options.
 
 ## Project
 
 [Changelog](./CHANGELOG.md) · [Contributing](./CONTRIBUTING.md) ·
 [Security](./SECURITY.md) · [MIT License](./LICENSE)
 
-ADB Ready is Android-only. The current development line combines target
-readiness, ports, session recovery, logs, verified app lifecycle, and local
-evidence capture. It intentionally exposes typed workflows instead of a generic
-remote shell.
+ADB Ready is Android-only. It exposes target-bound workflows rather than a
+generic remote shell.