diff --git a/README.md b/README.md index eb6c50902c..1b7dc63c50 100644 --- a/README.md +++ b/README.md @@ -94,7 +94,7 @@ Refs are valid only in the latest output: after a `--settle` command, use the re } ``` -See [AI Agent Setup](https://agent-device.dev/docs/agent-setup) for per-client setup and when to prefer plain CLI over MCP. +See [AI agent setup](https://agent-device.dev/docs/agent-setup) for per-client setup and when to prefer plain CLI over MCP. ### Script it from Node.js @@ -139,9 +139,9 @@ With the CLI installed, prompts like these work end to end: ## Next steps -- [AI Agent Setup](https://agent-device.dev/docs/agent-setup): skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others. -- [Quick Start](https://agent-device.dev/docs/quick-start): open an app, read its UI, and interact with it from the command line. -- [Replay & E2E](https://agent-device.dev/docs/replay-e2e) and [Debugging & Profiling](https://agent-device.dev/docs/debugging-profiling): repeatable tests and bug hunting. +- [AI agent setup](https://agent-device.dev/docs/agent-setup): skills, project rules, and per-client setup for Cursor, Codex, Claude Code, Windsurf, and others. +- [Quick start](https://agent-device.dev/docs/quick-start): open an app, read its UI, and interact with it from the command line. +- [Replay and E2E testing](https://agent-device.dev/docs/replay-e2e) and [Debugging and profiling](https://agent-device.dev/docs/debugging-profiling): repeatable tests and bug hunting. ## Where to run agent-device @@ -171,7 +171,7 @@ Sessions are scoped to the caller's git worktree, and host-local device claims s ### Is there an MCP server for mobile app automation? -Yes. `agent-device mcp` starts the official stdio MCP server. The Quick start above has the client config, and [AI Agent Setup](https://agent-device.dev/docs/agent-setup) covers per-client details. +Yes. `agent-device mcp` starts the official stdio MCP server. The Quick start above has the client config, and [AI agent setup](https://agent-device.dev/docs/agent-setup) covers per-client details. ### Does it work with React Native, Expo, Flutter, and native apps? diff --git a/website/astro.config.mjs b/website/astro.config.mjs index cdab2461ba..c70db27dad 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -7,7 +7,12 @@ import starlightLlmsTxt from 'starlight-llms-txt'; import { brandCss } from './src/site/brand.ts'; import { site as meta, noindexPaths } from './src/site/content.ts'; import { TITLE_DELIMITER } from './src/site/meta.ts'; -import { llmsDescription, llmsDetails, llmsOptionalLinks } from './src/site/llms.ts'; +import { + llmsDescription, + llmsDetails, + llmsOptionalLinks, + llmsSmallExclude, +} from './src/site/llms.ts'; const site = meta.url; const repo = meta.repo; @@ -15,8 +20,8 @@ const description = meta.description; // Where this site lives inside the repo, for the docs' "Edit page" links. const siteDir = 'website'; -const doc = (name, label) => ({ label, slug: `docs/${name}` }); -const group = (label, items) => ({ label, items: items.map(([name, text]) => doc(name, text)) }); +// Sidebar entries take the page's own title, so a page has one name everywhere. +const group = (label, names) => ({ label, items: names.map((name) => `docs/${name}`) }); export default defineConfig({ site, @@ -79,41 +84,37 @@ export default defineConfig({ ], sidebar: [ group('Getting started', [ - ['introduction', 'Introduction'], - ['installation', 'Installation'], - ['plugins', 'Provider plugins'], - ['agent-setup', 'AI agent setup'], - ['quick-start', 'Quick start'], + 'introduction', + 'installation', + 'plugins', + 'agent-setup', + 'quick-start', ]), group('Usage', [ - ['capabilities', 'Capabilities'], - ['commands', 'Commands'], - ['configuration', 'Configuration'], - ['selectors', 'Selectors'], - ['sessions', 'Sessions'], - ['batching', 'Batching'], - ['snapshots', 'Snapshots'], - ['replay-e2e', 'Replay and E2E testing'], - ['run-maestro-flows', 'Run Maestro flows'], - ['debugging-profiling', 'Debugging and profiling'], + 'capabilities', + 'commands', + 'configuration', + 'selectors', + 'sessions', + 'batching', + 'snapshots', + 'replay-e2e', + 'run-maestro-flows', + 'debugging-profiling', ]), group('Integrations', [ - ['client-api', 'Node.js API'], - ['build-an-integration', 'Build an integration'], - ['ai-sdk', 'AI SDK'], - ['eve', 'Eve'], - ['remote-proxy', 'Remote proxy'], - ['device-clouds', 'Device clouds'], - ['browserstack', 'BrowserStack'], - ['aws-device-farm', 'AWS Device Farm'], - ['testmu', 'TestMu AI'], - ['limrun', 'Limrun'], - ]), - group('Reference', [ - ['security-trust', 'Security and trust'], - ['known-limitations', 'Known limitations'], - ['migrating-gestures', 'Rewrite old gesture commands'], + 'client-api', + 'build-an-integration', + 'ai-sdk', + 'eve', + 'remote-proxy', + 'device-clouds', + 'browserstack', + 'aws-device-farm', + 'testmu', + 'limrun', ]), + group('Reference', ['security-trust', 'known-limitations', 'migrating-gestures']), ], plugins: [ starlightLlmsTxt({ @@ -121,6 +122,9 @@ export default defineConfig({ description: llmsDescription, details: llmsDetails, optionalLinks: llmsOptionalLinks, + // llms-small.txt leaves out the reference pages in llmsSmallExclude (their tables also + // flatten badly there); llms-full.txt keeps every page. + exclude: llmsSmallExclude.map((slug) => `docs/${slug}`), }), ], }), diff --git a/website/docs/docs/agent-setup.md b/website/docs/docs/agent-setup.md index af90f8eda3..26e593c08d 100644 --- a/website/docs/docs/agent-setup.md +++ b/website/docs/docs/agent-setup.md @@ -1,5 +1,5 @@ --- -title: AI Agent Setup +title: AI agent setup description: Configure Cursor, Codex, Claude Code, Windsurf, Cline, Goose, iOS Simulator and Android Emulator skills, and MCP for agent-device app verification. --- @@ -241,7 +241,7 @@ If the client supports project rules or custom instructions, paste the [recommen For supported targets, evidence features, and how `agent-device` differs from scripted test frameworks, see [Introduction](/docs/introduction). For command groups and platform behavior, see [Commands](/docs/commands). -For the local execution model, permissions, artifacts, and sensitive data guidance, see [Security & Trust](/docs/security-trust). +For the local execution model, permissions, artifacts, and sensitive data guidance, see [Security and trust](/docs/security-trust). ## Agent-readable docs diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index c1f8616267..61eca041fb 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -23,7 +23,7 @@ For MCP-aware clients that support direct tools, run: agent-device mcp ``` -For MCP client setup and what MCP does not expose, see [AI Agent Setup](/docs/agent-setup#mcp-server). +For MCP client setup and what MCP does not expose, see [AI agent setup](/docs/agent-setup#mcp-server). ## Output and warnings @@ -150,7 +150,7 @@ Remote daemons and tenants: - `--tenant`, `--session-isolation tenant`, `--run-id`, and `--lease-id` enforce lease admission on tenant-scoped daemons. - `--daemon-base-url http(s)://host:port[/base-path]` calls a remote HTTP daemon directly instead of starting a local one. Add `--daemon-auth-token ` (or `AGENT_DEVICE_DAEMON_AUTH_TOKEN`) for non-loopback daemon URLs. - Screenshots and recordings from a remote daemon are downloaded to the path you pass, so `screenshot page.png` and `record start session.mp4` work as they do locally. `record start` without a path downloads to `recording-.mp4` (`.webm` on web) in your working directory. -- To drive a Mac's simulators and devices from another machine, see [Remote Proxy](/docs/remote-proxy). For hosted devices in CI, see [BrowserStack](/docs/browserstack), [AWS Device Farm](/docs/aws-device-farm), or [TestMu AI](/docs/testmu). For `connect --remote-config`, see [Remote Metro workflow](#remote-metro-workflow). +- To drive a Mac's simulators and devices from another machine, see [Remote proxy](/docs/remote-proxy). For hosted devices in CI, see [BrowserStack](/docs/browserstack), [AWS Device Farm](/docs/aws-device-farm), or [TestMu AI](/docs/testmu). For `connect --remote-config`, see [Remote Metro workflow](#remote-metro-workflow). ```bash agent-device open "https://example.com" --platform ios # open link in web browser @@ -176,7 +176,7 @@ agent-device takeover release --session remote-session `takeover` holds the device until you press Ctrl+C. While it holds, state-changing commands fail with `DEVICE_IN_USE` and `details.reason: "human_control_active"`; read-only diagnostics still work. It needs a device-scoped remote lease, so local sessions aren't supported. Holds don't survive a daemon -restart; reconnect and take the hold again. See [Remote Proxy](/docs/remote-proxy#human-takeover). +restart; reconnect and take the hold again. See [Remote proxy](/docs/remote-proxy#human-takeover). ## Web Automation @@ -209,7 +209,7 @@ agent-device close --platform web - `web setup` installs a pinned `agent-browser` backend into the agent-device state directory (`--state-dir`, `AGENT_DEVICE_STATE_DIR`) and reuses it when present. Run it before first use and in CI bootstrap: web commands never install the backend themselves and use only that managed install. `web doctor` verifies it. - Supported: URL open, snapshot refs, `get text/attrs`, `is visible/hidden/exists/absent/focused/text`, `find text/selector`, click/press, hover, fill/type, wait, `network dump`, `audio probe`, screenshot, close, and replay scripts made from those commands. - `hover <@ref|selector|x y>` moves the pointer without pressing so hover-gated UI (row toolbars, menus) appears. Add `--settle` to read what it revealed; on web, `--settle` needs a selector or coordinate target because web refs carry no geometry. -- `audio probe start [durationSeconds] [bucketMs]` samples HTML media elements into RMS/peak dBFS buckets; see [Debugging & Profiling](/docs/debugging-profiling#audio-probes). +- `audio probe start [durationSeconds] [bucketMs]` samples HTML media elements into RMS/peak dBFS buckets; see [Debugging and profiling](/docs/debugging-profiling#audio-probes). - Not supported: tab/window/devtools control, network routing/interception/HAR, cookies/storage, downloads/uploads, arbitrary page scripting, multi-page orchestration, and raw browser diagnostics. Use `agent-browser` directly for those. ## Device isolation scopes @@ -338,7 +338,7 @@ agent-device snapshot -i --platform apple --target desktop - `open --platform macos --surface menubar` targets one app's menu bar extras. Prefer it for status-item apps, which often expose little through the `app` surface. - Prefer selectors and `@ref`s; window positions shift between runs, so raw x/y is less stable. Use `click --button secondary` for context menus, then run `snapshot -i` again. - On `frontmost-app` and `menubar`, `press` and `click` post synthetic mouse events (`desktop` is inspect-only). `--hold-ms` keeps the button down (at least 40 ms, default 60 ms), `--count` sends independent clicks, and `--double-tap` sends double-click pairs. Apps like Finder read two clicks at the default interval as one double-click; pass an `--interval-ms` longer than the system double-click time to keep them apart. Long schedules get the time they need, and a cancelled or interrupted click releases the button. `--jitter-px` is ignored on these surfaces. -- macOS also supports `clipboard read|write`, `trigger-app-event`, `logs`, `network dump`, `audio probe`, `alert`, and part of `settings` (see [Settings helpers](#settings-helpers)). `audio probe` samples host system audio and needs Screen Recording permission; see [Debugging & Profiling](/docs/debugging-profiling#audio-probes). +- macOS also supports `clipboard read|write`, `trigger-app-event`, `logs`, `network dump`, `audio probe`, `alert`, and part of `settings` (see [Settings helpers](#settings-helpers)). `audio probe` samples host system audio and needs Screen Recording permission; see [Debugging and profiling](/docs/debugging-profiling#audio-probes). - Mobile-only commands are unsupported on macOS: `boot`, `shutdown`, `home`, `orientation`, `app-switcher`, `action-button`, `fold`, `install`, `reinstall`, `uninstall`, `install-from-source`, and `push`. XCTest opens bring the named app to the front. `open --surface frontmost-app` takes no app target and opens the app that is already frontmost. `--foreground` requests an initial snapshot; it does not choose activation. Run `agent-device help macos` for the versioned contract. @@ -486,7 +486,7 @@ A `click` or `press` whose target the daemon resolves to a point (`@ref` or sele - `fill` clears then types. `type` appends to the focused field and accepts text only: use `fill @ref "text"` to target a field, or `press @ref` then `type "text"`. - Use plain `fill` or `type` first. Add `--delay-ms` only when a debounced or search-as-you-type field misses characters, or the app must receive each incremental update; delayed typing enters characters one at a time instead of using a clipboard-style fallback. - `fill --text-stdin` reads the text from stdin so a secret never appears in process arguments. Pipe it with `printf %s`. It reads at most 64 KiB, removes one trailing newline, and refuses a terminal, empty input, invalid UTF-8, or an extra text argument. Output shows the value as `${VAR}` with `--record-as ` and as `[REDACTED]` otherwise, including in error messages and details, and in the `requested`, `before`, and `after` read-back of an unconfirmed fill, which can hold a reformatted form of the value. With `--settle`, the diff line text and tail labels are replaced whole, so text around the value in the field is not shown either; refs and counts stay. While script recording is armed, pass `--record-as ` or `--no-record`; passing neither is an error. Batch steps don't accept it. -- The privacy controls for typed input (`--text-stdin` and `--record-as`) keep the literal out of agent-device's own responses, diagnostics, and recorded scripts. They do not rewrite what the platform records: on iOS, XCTest writes its own diagnostic logs and its `.xcresult` bundle, and typed text can appear in both, on a simulator or a physical device. Treat those as sensitive, and use test-only credentials when they may be kept or shared. See [Security & Trust](/docs/security-trust). +- The privacy controls for typed input (`--text-stdin` and `--record-as`) keep the literal out of agent-device's own responses, diagnostics, and recorded scripts. They do not rewrite what the platform records: on iOS, XCTest writes its own diagnostic logs and its `.xcresult` bundle, and typed text can appear in both, on a simulator or a physical device. Treat those as sensitive, and use test-only credentials when they may be kept or shared. See [Security and trust](/docs/security-trust). - Android text entry is owned by `agent-device`. Don't fall back to raw `adb`, clipboard, or paste; if non-ASCII is unsupported on the current backend, report the gap. Android `fill` verifies the text and fails instead of retrying when the IME captures input. Text-entry errors and what to do: @@ -515,7 +515,7 @@ agent-device wait 'id="field-phone" value="00 062 91 77"' - `click --button secondary` opens a macOS context menu; `--button middle` is unsupported on macOS. - `longpress` is supported on iOS and Android. `hover` is web only: it moves the pointer over a target without pressing so hover-gated UI appears, and `--settle` returns what it revealed. Touch platforms reject it; use `longpress` for the hold gesture. - `swipe` is a quick, fixed-duration throw. `gesture pan x y dx dy [durationMs]` is a deliberate timed drag with one pointer, or two with `--pointer-count 2`. Repeated swipes allow at most 200 repetitions, 10000ms pauses, and 60000ms in total. -- `gesture fling up|down|left|right x y [distance]` is a fast directional throw. Neither `swipe` nor `gesture fling` takes a duration, and `gesture rotate` takes no velocity; see [Rewrite Old Gesture Commands](/docs/migrating-gestures) to update old scripts. +- `gesture fling up|down|left|right x y [distance]` is a fast directional throw. Neither `swipe` nor `gesture fling` takes a duration, and `gesture rotate` takes no velocity; see [Rewrite old gesture commands](/docs/migrating-gestures) to update old scripts. - `gesture drag source destination [sourceHoldMs] [moveMs] [destinationHoldMs]` holds one pointer down from source to destination. Endpoints are selectors or refs, resolved before dispatch and recorded as selector chains. Defaults are 800, 500, and 0ms, capped at 10000ms in total. It works on Android touch devices and iOS/iPadOS; other backends refuse it before touching the screen. - `gesture pinch [x] [y]`, `gesture rotate [x] [y]` (the sign sets direction), `gesture transform x y dx dy scale degrees [durationMs]`, and two-finger `gesture pan` work in Android, iOS, and iPadOS app sessions, on simulators and physical devices. On Apple they use the XCTest runner, so iOS sessions reached through a WebDriver provider refuse them. One-finger `gesture pan` works wherever coordinate drags do. A path that does not fit the viewport fails before injection instead of being clamped. Use `orientation` to rotate the device. - `gesture tap x1 y1 x2 y2 [... x5 y5]` touches 2 to 5 distinct points and holds them for `--hold-ms` (default 50ms, at least 16ms) before lifting. `--count` repeats the same contacts up to 200 times with `--pause-ms` between repetitions; the series must fit in 60000ms, counting about 500ms of overhead per repetition. It works in Android and iOS/iPadOS app sessions; WebDriver providers refuse it unless they declare `tapGesture` support. On iOS the contacts touch down and lift together; on Android they touch down up to 8ms apart and lift 8ms apart in reverse order. Three or more fingers can trigger iOS system gestures such as undo, so verify app state afterwards. Use `press` for one finger. @@ -525,7 +525,7 @@ agent-device wait 'id="field-phone" value="00 062 91 77"' ### Scroll - `scroll [amount]` takes the finger path as a fraction of the viewport (`0.5` is half), or `--pixels ` for a fixed distance. Large distances are clamped. The app's scroll physics decide the final offset, so a scroll does not land on an exact position. -- `scroll --until ` repeats passes until the selector is on screen and fails if the content runs out first. It stops after at most 12 gestures by default. For a longer list, use `scroll down --until 'id="row-512"' --max-passes 90` (1–200 gestures). The pass limit does not extend the 90-second request timeout. Large pass budgets can hit that timeout; inspect the current screen and continue with another search if that happens. Add an amount (`scroll down 0.8 --until `) to widen each pass. Use it in `.ad` scripts too, instead of fixed amounts that depend on screen size; see [Replay & E2E](/docs/replay-e2e). +- `scroll --until ` repeats passes until the selector is on screen and fails if the content runs out first. It stops after at most 12 gestures by default. For a longer list, use `scroll down --until 'id="row-512"' --max-passes 90` (1–200 gestures). The pass limit does not extend the 90-second request timeout. Large pass budgets can hit that timeout; inspect the current screen and continue with another search if that happens. Add an amount (`scroll down 0.8 --until `) to widen each pass. Use it in `.ad` scripts too, instead of fixed amounts that depend on screen size; see [Replay and E2E testing](/docs/replay-e2e). - Default snapshot text summarizes off-screen interactive content instead of listing refs. `scroll --settle` (and `back --settle`) waits for the UI to go quiet and returns the diff with fresh refs, so you don't need another `snapshot -i`. Settle is best-effort and never fails the action. - On Android, settle ignores an allowlist of system-bar containers and shade/keyguard status headers; other SystemUI overlays remain content. Appium settle also applies package rules for keyboard and system chrome. - With a keyboard up on iOS or Android, the swipe stays above the keyboard (reported as `keyboardAvoided` and `keyboardMinY`) and the keyboard stays open. If too little room is left, the command refuses with `scroll_keyboard_occludes_surface`; run `keyboard dismiss` first. @@ -614,7 +614,7 @@ agent-device replay ./session.ad --keep-session # Suppress its terminal close - A failing step returns a `REPLAY_DIVERGENCE` report; `replay --from --plan-digest ` resumes at plan step `n` (`test` rejects `--from`). See [Resume a failed replay](/docs/replay-e2e#resume-a-failed-replay). - `replay -u`/`--update` is accepted and does nothing; it does not rewrite the script. -See [Replay & E2E](/docs/replay-e2e) for recording and CI workflow details, and [Run Maestro flows](/docs/run-maestro-flows) for Maestro YAML. +See [Replay and E2E testing](/docs/replay-e2e) for recording and CI workflow details, and [Run Maestro flows](/docs/run-maestro-flows) for Maestro YAML. ## Batch @@ -864,7 +864,7 @@ agent-device clipboard write "" # clear clipboard - `clipboard read` returns the target's clipboard text; `clipboard write ` replaces it. Treat read output as sensitive: it can contain copied secrets. - Works with the session device or a device selector (`--platform`, `--device`, `--udid`, `--serial`). - Supported on macOS, iOS simulators, and Android builds whose clipboard service answers `cmd clipboard`. iOS physical devices return `UNSUPPORTED_OPERATION`. -- On Android 16 (API 36), both actions return `UNSUPPORTED_OPERATION` and `capabilities` omits `clipboard`; see [Known Limitations](/docs/known-limitations#android-no-clipboard-access-over-adb-on-android-16). +- On Android 16 (API 36), both actions return `UNSUPPORTED_OPERATION` and `capabilities` omits `clipboard`; see [Known limitations](/docs/known-limitations#android-no-clipboard-access-over-adb-on-android-16). ## Keyboard @@ -903,7 +903,7 @@ agent-device perf trace stop --kind perfetto --out app.perfetto-trace - Name one area: `frames`, `memory`, `cpu`, or `trace`. Bare `perf`, `perf sample`, `perf metrics`, and the `metrics` alias fail with guidance to the focused replacements. - `perf frames` returns frame/jank health (`droppedFramePercent`, `worstWindows`). `perf memory sample` returns a compact process memory sample in kilobytes. `perf memory snapshot` writes a heap or memgraph artifact and returns its path. - `perf cpu profile` and `perf trace` record Apple (`--kind xctrace`) or Android (`--kind simpleperf`, `--kind perfetto`) profiles and traces, and return artifact paths plus compact metadata; raw contents stay on disk. -- `cdp` samples and snapshots the React Native JavaScript heap through Metro CDP; see [Debugging & Profiling](/docs/debugging-profiling#react-native-js-memory-through-cdp). +- `cdp` samples and snapshots the React Native JavaScript heap through Metro CDP; see [Debugging and profiling](/docs/debugging-profiling#react-native-js-memory-through-cdp). - App startup duration is returned in `open`'s `startup` result. - Perf commands need an app session with a package or bundle ID; run `open ` first. - Platform support: @@ -948,7 +948,7 @@ agent-device react-devtools profile commit - Profiling connects through the app's Metro dev server and needs no app or Metro setup. It works with development builds of React Native 0.74 and later on Android emulators, iOS simulators, `agent-device proxy` connections, and remote bridge sessions. On a remote bridge it uses the Metro server next to the agent: the session's binding from `metro prepare`, or `--metro-host`/`--metro-port`. Metro accepts the debugger connection only from its own machine, so the bridge or `metroPublicBaseUrl` cannot carry it. - `--app ` picks the app when several share the dev server, and `--metro-device ` picks the device when one app runs on several. `--metro-port` and `--metro-host`, or `--bundle-url` for a dev server behind a URL path, pick the dev server when it is neither the session's Metro server nor `localhost:8081`. - With `--json`, `profile stop` returns the findings and the path of the saved profile. -- See [Debugging & Profiling](/docs/debugging-profiling#react-native-performance-profiling) for the findings and the workflow. +- See [Debugging and profiling](/docs/debugging-profiling#react-native-performance-profiling) for the findings and the workflow. ## React Native overlays @@ -1059,7 +1059,7 @@ agent-device record stop # Stop active recording - `record contact-sheet [--out ]` turns an exported MP4 into one PNG grid of the frames where the screen visibly changed, each labeled with its elapsed time. It needs no session or device. The default output is `.contact-sheet.png`, and `--out` cannot point at the recording itself. `--json` adds per-cell times and change shares plus `sampledFrameCount`, `decodedFrameCount`, and `skippedSampleCount`. - A contact sheet samples at most 48 times across the clip (every 250ms for short clips) and prints at most 24 cells, so a transient between samples can be missing; `warning` says when cells were thinned or samples skipped. It runs only on macOS hosts (`details.reason: contact_sheet_unsupported_host` elsewhere) and refuses WebM with `contact_sheet_container_unsupported`. -**Session app logs:** See [Debugging & Profiling](/docs/debugging-profiling#logs) for the clean-repro and grep workflow. +**Session app logs:** See [Debugging and profiling](/docs/debugging-profiling#logs) for the clean-repro and grep workflow. ```bash agent-device logs path # Print session log file path (e.g. ~/.agent-device/sessions/default/app.log) @@ -1170,8 +1170,8 @@ agent-device artifacts --provider browserstack --provider-session --json ``` -- `artifacts` lists the provider-hosted artifacts your provider returns, such as videos, logs, and dashboard links, as `cloudArtifacts` (what each provider returns: [Device Clouds](/docs/device-clouds#compare-providers)), separate from the local `artifacts` that screenshot, record, install, and replay return. Plain text prints ready URLs. -- Looking up a past session needs `--provider-session ` and `--provider `. For credentials, see [Device Clouds](/docs/device-clouds#compare-providers). AWS Device Farm infers the region from the session ARN when possible. When an embedding host registers the cloud runtime in-process, `artifacts` infers the active provider session before disconnect. +- `artifacts` lists the provider-hosted artifacts your provider returns, such as videos, logs, and dashboard links, as `cloudArtifacts` (what each provider returns: [Device clouds](/docs/device-clouds#compare-providers)), separate from the local `artifacts` that screenshot, record, install, and replay return. Plain text prints ready URLs. +- Looking up a past session needs `--provider-session ` and `--provider `. For credentials, see [Device clouds](/docs/device-clouds#compare-providers). AWS Device Farm infers the region from the session ARN when possible. When an embedding host registers the cloud runtime in-process, `artifacts` infers the active provider session before disconnect. - `disconnect --json` and `close --json` include provider release data when the runtime returns final artifacts. Providers may finalize URLs only after the session stops, so retry `artifacts` if the first response is `pending`. ## iOS physical-device prerequisites diff --git a/website/docs/docs/debugging-profiling.md b/website/docs/docs/debugging-profiling.md index 434e0c2c0f..a71e5cbab8 100644 --- a/website/docs/docs/debugging-profiling.md +++ b/website/docs/docs/debugging-profiling.md @@ -1,5 +1,5 @@ --- -title: Debugging & Profiling +title: Debugging and profiling --- When UI automation is not enough, use these commands to collect runtime evidence from the app or device. diff --git a/website/docs/docs/device-clouds.md b/website/docs/docs/device-clouds.md index 9021cd5953..0231108651 100644 --- a/website/docs/docs/device-clouds.md +++ b/website/docs/docs/device-clouds.md @@ -1,5 +1,5 @@ --- -title: Device Clouds +title: Device clouds description: Choose a hosted device provider for agent and CI workflows. --- diff --git a/website/docs/docs/installation.md b/website/docs/docs/installation.md index ef97dd4a3b..ae7cc70a55 100644 --- a/website/docs/docs/installation.md +++ b/website/docs/docs/installation.md @@ -39,7 +39,7 @@ A global install gives agents a stable `agent-device` command. Start with the co agent-device help workflow ``` -For Cursor, Codex, Claude Code, Windsurf, Cline, Goose, skills, and project rules, see [AI Agent Setup](/docs/agent-setup); to expose commands as MCP tools with `agent-device mcp`, see [MCP server](/docs/agent-setup#mcp-server). If an agent can't find `agent-device` after a global install, see [Fix a missing agent-device command](/docs/agent-setup#fix-a-missing-agent-device-command). For the first app automation commands, see [Quick Start](/docs/quick-start). +For Cursor, Codex, Claude Code, Windsurf, Cline, Goose, skills, and project rules, see [AI agent setup](/docs/agent-setup); to expose commands as MCP tools with `agent-device mcp`, see [MCP server](/docs/agent-setup#mcp-server). If an agent can't find `agent-device` after a global install, see [Fix a missing agent-device command](/docs/agent-setup#fix-a-missing-agent-device-command). For the first app automation commands, see [Quick start](/docs/quick-start). ## Update the CLI diff --git a/website/docs/docs/introduction.md b/website/docs/docs/introduction.md index 3debf9a95c..4b16b6ac21 100644 --- a/website/docs/docs/introduction.md +++ b/website/docs/docs/introduction.md @@ -47,7 +47,7 @@ Start with the core workflow guide in the installed CLI help. [Commands](/docs/c agent-device help workflow ``` -Use [AI Agent Setup](/docs/agent-setup) for Cursor, Codex, Claude Code, Windsurf, Cline, Goose, skills, and MCP setup. Use [Commands](/docs/commands) for detailed command groups and platform behavior. +Use [AI agent setup](/docs/agent-setup) for Cursor, Codex, Claude Code, Windsurf, Cline, Goose, skills, and MCP setup. Use [Commands](/docs/commands) for detailed command groups and platform behavior. ## Where it fits @@ -60,8 +60,8 @@ MCP clients can drive devices directly through the `agent-device mcp` server, wh ## Next steps - Install the CLI: [Installation](/docs/installation) -- Set up an agent client: [AI Agent Setup](/docs/agent-setup) -- Run the first commands: [Quick Start](/docs/quick-start) +- Set up an agent client: [AI agent setup](/docs/agent-setup) +- Run the first commands: [Quick start](/docs/quick-start) - Inspect all command groups: [Commands](/docs/commands) -- Collect runtime evidence: [Debugging & Profiling](/docs/debugging-profiling) -- Record deterministic flows: [Replay & E2E](/docs/replay-e2e) +- Collect runtime evidence: [Debugging and profiling](/docs/debugging-profiling) +- Record deterministic flows: [Replay and E2E testing](/docs/replay-e2e) diff --git a/website/docs/docs/known-limitations.md b/website/docs/docs/known-limitations.md index f87e91b715..42b0d9275c 100644 --- a/website/docs/docs/known-limitations.md +++ b/website/docs/docs/known-limitations.md @@ -1,5 +1,5 @@ --- -title: Known Limitations +title: Known limitations --- Platform constraints that change what you see during automation, and what to do instead. diff --git a/website/docs/docs/migrating-gestures.md b/website/docs/docs/migrating-gestures.md index bfe03c3cd8..7d9f8786f2 100644 --- a/website/docs/docs/migrating-gestures.md +++ b/website/docs/docs/migrating-gestures.md @@ -1,5 +1,5 @@ --- -title: Rewrite Old Gesture Commands +title: Rewrite old gesture commands --- `swipe`, `gesture fling`, and `gesture swipe` don't take a duration, and `gesture rotate` doesn't diff --git a/website/docs/docs/quick-start.md b/website/docs/docs/quick-start.md index 829a59ff74..d44b9377a8 100644 --- a/website/docs/docs/quick-start.md +++ b/website/docs/docs/quick-start.md @@ -1,10 +1,10 @@ --- -title: Quick Start +title: Quick start --- Open an app, read its UI, and interact with it from the command line. -Before you start, [install `agent-device`](/docs/installation) and the platform tools for your target: Xcode for iOS, the Android SDK and ADB for Android, or the HarmonyOS Command Line Tools for HarmonyOS. To set up Cursor, Codex, Claude Code, Windsurf, Cline, Goose, or another coding agent, see [AI Agent Setup](/docs/agent-setup). To give an agent the whole documentation as one text file, use [llms-full.txt](https://agent-device.dev/llms-full.txt). +Before you start, [install `agent-device`](/docs/installation) and the platform tools for your target: Xcode for iOS, the Android SDK and ADB for Android, or the HarmonyOS Command Line Tools for HarmonyOS. To set up Cursor, Codex, Claude Code, Windsurf, Cline, Goose, or another coding agent, see [AI agent setup](/docs/agent-setup). To give an agent the whole documentation as one text file, use [llms-full.txt](https://agent-device.dev/llms-full.txt). Device automation follows this pattern: @@ -121,7 +121,7 @@ agent-device find role button click ## Replay a flow -To record and replay deterministic scripts, see [Replay & E2E](/docs/replay-e2e). +To record and replay deterministic scripts, see [Replay and E2E testing](/docs/replay-e2e). ## Scroll diff --git a/website/docs/docs/remote-proxy.md b/website/docs/docs/remote-proxy.md index 8930ad80e4..719a8de824 100644 --- a/website/docs/docs/remote-proxy.md +++ b/website/docs/docs/remote-proxy.md @@ -1,5 +1,5 @@ --- -title: Remote Proxy +title: Remote proxy description: Run agent-device on a Mac with simulator or device access and control it from another machine through an HTTP tunnel. --- diff --git a/website/docs/docs/replay-e2e.md b/website/docs/docs/replay-e2e.md index 6b13f59163..5e1b8bf4a1 100644 --- a/website/docs/docs/replay-e2e.md +++ b/website/docs/docs/replay-e2e.md @@ -1,5 +1,5 @@ --- -title: Replay & E2E Testing +title: Replay and E2E testing --- Record a session as an `.ad` script, then run it again with `replay` or run a folder of scripts as an E2E suite with `test`. diff --git a/website/docs/docs/run-maestro-flows.md b/website/docs/docs/run-maestro-flows.md index 02f8654530..7b74be7541 100644 --- a/website/docs/docs/run-maestro-flows.md +++ b/website/docs/docs/run-maestro-flows.md @@ -8,7 +8,7 @@ title: Run Maestro flows - Flows run on iOS and Android only. - `runScript`, `evalScript`, and JavaScript conditions execute flow code on the machine running the agent-device daemon, without a security sandbox. Run only flows you trust to run there. -For recording and replaying native `.ad` scripts, see [Replay & E2E testing](/docs/replay-e2e). +For recording and replaying native `.ad` scripts, see [Replay and E2E testing](/docs/replay-e2e). ## Run a Maestro flow diff --git a/website/docs/docs/security-trust.md b/website/docs/docs/security-trust.md index e3e32d488d..55b82e65aa 100644 --- a/website/docs/docs/security-trust.md +++ b/website/docs/docs/security-trust.md @@ -1,5 +1,5 @@ --- -title: Security & Trust +title: Security and trust description: Security and trust guidance for agent-device local app automation, device permissions, screenshots, recordings, logs, network dumps, audio probes, traces, and reports. --- diff --git a/website/docs/docs/sessions.md b/website/docs/docs/sessions.md index d32b365ec9..683b032505 100644 --- a/website/docs/docs/sessions.md +++ b/website/docs/docs/sessions.md @@ -195,4 +195,4 @@ To free a device: [`targetActivation` disclosure](/docs/commands#foreground-repairs-on-ios). - For remote `connect --remote-config` sessions, see [Commands](/docs/commands#remote-metro-workflow). -For replay scripts and deterministic E2E guidance, see [Replay & E2E](/docs/replay-e2e). +For replay scripts and deterministic E2E guidance, see [Replay and E2E testing](/docs/replay-e2e). diff --git a/website/src/components/site/DocsSearch.astro b/website/src/components/site/DocsSearch.astro index db7795bb96..5271942d47 100644 --- a/website/src/components/site/DocsSearch.astro +++ b/website/src/components/site/DocsSearch.astro @@ -20,12 +20,14 @@ import PixelIcon from './PixelIcon.astro';