docs: reposition README around mobile app automation for AI agents

[thymikee]

Summary

Repositions the README so it leads with the category and the three surfaces before differentiating on verification and evidence: category keywords first so humans and search engines can classify it, verification and evidence as the differentiator.

Before: the intro opened with the job statement, then a dense platform paragraph carrying per-platform caveats (HarmonyOS uses HDC and ArkUI uitest; Vega OS is VVD-only), then the Vercel attribution. Zero occurrences of "mobile app automation" or "MCP server" above the fold. MCP setup and the Node.js client were only reachable through docs links; capabilities and proof were below the entire Quick start.

After:

• Category line first: mobile app automation and verification for AI coding agents, through the CLI, built-in MCP server, or typed Node.js API. Then the job pitch with a keyword-richer platform sentence, then a works-with/proof line (documented client list; every named proof point links to public evidence).
• Quick start follows the hero directly; "What agents can do" and the loop diagram sit below the walkthrough.
• Quick start now has three labeled paths after the shared install step: CLI walkthrough (unchanged), MCP mcpServers config, and a ten-line createAgentDeviceClient() snippet mirroring examples/sdk/client-session.ts.
• New "What to ask your agent" section with five developer prompts; a one-sentence product ladder atop "Where to run"; two AEO-shaped FAQ entries.
• Per-platform transports and caveats moved to "How it works", with one sentence pointing at agent-device capabilities --platform <platform> as the authoritative depth check.
• Cloud/remote row points at the remote proxy and device clouds docs instead of agent-device.dev/cloud.
• npm description, server.json registry description (99/100 chars), and the rspress site description (110 chars) use the same category phrasing.
• Em dashes and evaluative filler removed per the Callstack humanizer skill; the tone-of-voice reference was checked and already passes.

Guard against the original drift (a contributor appending "HarmonyOS uses HDC…" to the intro because the Vega caveat had already set the pattern): the pattern-seeding sentences are gone, an inline HTML comment above the intro states the rule at the point of edit, and AGENTS.md "Docs & skills" gets a README-altitude rule.

Length: 207 lines / ~1580 words, up from 149 / ~1150; the growth is the MCP + Node quick starts, prompts, and proof line, with duplicated Node subpath and FAQ text removed.

Validation

Docs and metadata only, no runtime behavior changes. node scripts/sync-mcp-metadata.mjs --check passes for the new server.json description. Node snippet method names and optional udid verified against packages/contracts/src/client-app.ts and the SDK example. The repo's format gate (oxfmt) does not take markdown, and the prettier warnings on README/AGENTS pre-exist this change on main.

Not covered here: GitHub About text (repo settings), the agent-device.dev H1 and client-specific landing pages from the same analysis. 5 files touched; scope grew from a HarmonyOS-sentence cleanup to a README repositioning during the session.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-08-17 15:55 UTC

[github-actions]

Size Report

Metric	Base	Current	Diff
JS raw	2.26 MB	2.26 MB	0 B
JS gzip	744.0 kB	744.0 kB	0 B
npm tarball	861.6 kB	862.7 kB	+1.1 kB
npm unpacked	3.01 MB	3.01 MB	+3.6 kB

Startup median (7 runs, lower is better):

Scenario	Base	Current	Diff
CLI --version	31.0 ms	29.4 ms	-1.6 ms
CLI --help	68.1 ms	67.8 ms	-0.3 ms

Top changed chunks: no changes in the largest emitted chunks.

[thymikee]

The Node.js quick start can leave the session open if snapshot() or press() rejects after apps.open(). That retains the device claim and can make the next run fail with DEVICE_IN_USE. The runnable examples/sdk/client-session.ts correctly closes in finally; please give the README snippet the same try/finally shape so the copy-paste path preserves the documented open/close invariant.

[thymikee]

Done in the latest push: the snippet now wraps open → snapshot → press in try and calls client.sessions.close() in finally, matching examples/sdk/client-session.ts, so a rejection after apps.open() no longer retains the device claim.

🤖 Addressed by Claude Code

[thymikee]

Re-reviewed exact head 46ddfb8b. The prior Node example finding is resolved: open → snapshot → press is enclosed in try/finally, and client.sessions.close() now runs on failure, matching the runnable SDK example and preserving device-claim cleanup. The README’s MCP distinction is an architectural claim supported by the shared command runtime, while the new hero proof points link to concrete public evidence. All exact-head checks are green, including docs, integration, coverage, and platform smoke lanes. Code/docs review is clean and ready for human review.

Residual, non-blocking proof risk: the pre-existing “Who uses” section still contains several unlinked organization names; this head does not add those names. Do not apply labels.