Skip to content

Commit 3fb9a4c

Browse files
committed
docs: clarify agent setup and text entry guidance
1 parent 106c238 commit 3fb9a4c

7 files changed

Lines changed: 26 additions & 22 deletions

File tree

‎README.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,11 +52,15 @@ Install the CLI:
5252

5353
```bash
5454
npm install -g agent-device@latest
55+
agent-device doctor
5556
agent-device --version
5657
agent-device help workflow
5758
```
5859

59-
The installed CLI help is the source of truth for agents. Start with `agent-device help workflow`, then follow the topic-specific help when a task needs dogfooding, debugging, replay, or React Native profiling.
60+
Run `agent-device doctor` yourself after installation to check local setup before
61+
handing the CLI to an agent. The installed CLI help is the source of truth for
62+
agents. Start with `agent-device help workflow`, then follow the topic-specific
63+
help when a task needs dogfooding, debugging, replay, or React Native profiling.
6064

6165
Prerequisites depend on the target platform: Node.js 22+, Xcode for iOS/tvOS/macOS targets, Android SDK + ADB for Android, and macOS Accessibility permission for desktop automation. Web automation requires Node 24+. See [Installation](https://oss.callstack.com/agent-device/docs/installation) for platform setup.
6266

‎skills/agent-device/SKILL.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,6 @@ agent-device help dogfood
3838

3939
Default loop: `open -> snapshot/-i -> get/is/find or press/fill/scroll/wait -> verify -> close`.
4040

41-
On a fresh machine (first iOS run), start with `agent-device doctor --platform ios`: it preflights the environment and warms the iOS runner build cache in the background so the first `open` is fast.
42-
4341
Use this skill only to route into version-matched CLI help. Let the selected help topic provide exact command shapes, platform limits, and current workflow guidance; use `help workflow` as the full reference when a task-specific topic is too narrow.
4442

4543
For precise location workflows, read the installed `settings` help before planning so coordinate support and platform limits come from the active CLI version.

‎src/cli/parser/__tests__/cli-help-topics.test.ts‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,8 @@ test('usage includes agent workflows, config, environment, and examples footers'
107107
assert.match(usageText, /open "Expo Go" <url> --platform ios/);
108108
assert.match(usageText, /Do not use plain snapshot or snapshot --diff for this recovery check/);
109109
assert.match(usageText, /Install flows: install\/install-from-source first/);
110-
assert.match(usageText, /fill 'id="field-email"' "qa@example\.com" replaces/);
110+
assert.match(usageText, /use fill <target> <text> --settle to replace a field value/);
111+
assert.match(usageText, /Use type <text> only to append after focusing a field with press/);
111112
assert.match(usageText, /do not use fill <target> ""/);
112113
assert.match(usageText, /Android IME capture: if fill says input was captured/);
113114
assert.match(usageText, /Implicit default sessions are scoped to the current worktree/);
@@ -116,6 +117,8 @@ test('usage includes agent workflows, config, environment, and examples footers'
116117
assert.match(usageText, /After mutation: refs are stale/);
117118
assert.match(usageText, /use its selector directly; otherwise refresh with snapshot -i/);
118119
assert.match(usageText, /verify the action with diff snapshot -i or snapshot --diff/);
120+
assert.match(usageText, /fill <targetOrX> <yOrText> \[text\]\s+Replace text in/);
121+
assert.match(usageText, /type <text>\s+Append text to the focused field/);
119122
assert.match(usageText, /Sparse or AX-unavailable snapshot/);
120123
assert.match(usageText, /macOS context menus use click <ref> --button secondary/);
121124
assert.match(
@@ -456,6 +459,8 @@ test('usageForCommand resolves manual QA help topic', async () => {
456459
assert.match(help, /Run snapshot -i to get current refs/);
457460
assert.match(help, /press\/fill\/click\/longpress <ref-or-selector> --settle/);
458461
assert.match(help, /A bare screenshot\/snapshot is not verification/);
462+
assert.match(help, /use fill <target> <text> --settle to replace/);
463+
assert.match(help, /use type only to append to an already-focused field/);
459464
assert.match(help, /Do not use placeholders such as @ref/);
460465
});
461466

@@ -556,10 +561,8 @@ test('usageForCommand resolves react-native help topic', async () => {
556561
assert.match(help, /help react-devtools/);
557562
assert.match(help, /Help workflow owns the full Expo URL command shapes/);
558563
assert.match(help, /For app\/package launches, run metro prepare/);
559-
assert.match(help, /agent-device doctor --platform android/);
560-
assert.match(help, /agent-device doctor --platform android --app com\.example\.app/);
561-
assert.match(help, /agent-device doctor --platform ios/);
562-
assert.match(help, /agent-device doctor --remote --remote-config \.\/remote\.json/);
564+
assert.match(help, /Do not run doctor as routine QA\/dogfood prep/);
565+
assert.match(help, /Use doctor only when the user asks for setup diagnostics/);
563566
assert.match(help, /same host context that owns the dev server/);
564567
assert.match(help, /sandbox probe is not authoritative/);
565568
assert.match(help, /adb reverse only affects Android device-to-host traffic/);

‎src/cli/parser/cli-help.ts‎

Lines changed: 3 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ const AGENT_QUICKSTART_LINES = [
9393
'Android RN/Expo/Re.Pack dev server: direct Android localhost URL opens with a port auto-configure host reachability.',
9494
'Expo Go/dev clients: use the provided URL when given; on iOS use open "Expo Go" <url> --platform ios, then snapshot -i --platform ios to verify project UI. Do not use plain snapshot or snapshot --diff for this recovery check. Android URL opens infer the foreground package for logs/perf when possible.',
9595
'Install flows: install/install-from-source first, then open the installed id with --relaunch.',
96-
'Text: fill \'id="field-email"\' "[email protected]" replaces; type appends after press.',
96+
'Text fields: use fill <target> <text> --settle to replace a field value. Use type <text> only to append after focusing a field with press.',
9797
'Clearing text: do not use fill <target> ""; use a visible clear/reset control or report that clearing is unsupported.',
9898
'Android IME capture: if fill says input was captured by the keyboard/IME, inspect keyboard state and switch/disable handwriting before retrying; do not loop fill/type.',
9999
'Implicit default sessions are scoped to the current worktree; if a prompt names a Session, include --session <name> on every command in that flow.',
@@ -168,6 +168,7 @@ Loop:
168168
169169
Targets:
170170
Prefer refs from the latest snapshot -i or settled diff. Use durable selectors when the label/id is known: label="Search", id="submit", role=button label="Follow".
171+
For text fields, use fill <target> <text> --settle to replace the field value; use type only to append to an already-focused field.
171172
Do not use placeholders such as @ref, @eN, <button>, or <selector> in a final command plan. If the ref is unknown, first run snapshot -i.
172173
Coordinates are fallback-only after refs/selectors fail or accessibility omits the target; use screenshot or snapshot -i --json to choose a visible center point.
173174
@@ -187,9 +188,6 @@ Core loop:
187188
Start with the top-level Agent Starting Point for the default settle-first loop. This topic is the full reference for command shapes, refs, selectors, waits, recovery, and platform limits.
188189
If you intentionally skip --settle or use a command that does not support it, verify a mutation with diff snapshot (or diff snapshot -i) instead of a full snapshot: it diffs the rendered snapshot lines against the previous one in this session and prints only what changed.
189190
190-
Fresh machine or first iOS run:
191-
Run agent-device doctor --platform ios first. Besides preflight checks it warms the iOS XCTest runner build cache in the background, so the first open skips the runner build (~10s). To block until fully warm instead, run agent-device prepare ios-runner.
192-
193191
Command shape:
194192
Plans should use agent-device commands, not raw platform tools, pseudo commands, package-manager aliases, or helper prose.
195193
If the user asks for a command plan, final output should be command lines only: no intro sentence, numbered list, Markdown fence, shell pipe, grep/head/tail helper, or explanatory bullets.
@@ -690,11 +688,7 @@ Choose the next help topic:
690688
Remote/cloud config, leases, and local service tunnels: help remote.
691689
692690
React Native dev loop:
693-
Before QA/dogfood runs, use doctor to separate environment setup from app failures (on iOS simulators doctor also warms the runner build cache in the background):
694-
agent-device doctor --platform android
695-
agent-device doctor --platform ios
696-
agent-device doctor --platform android --app com.example.app
697-
agent-device doctor --remote --remote-config ./remote.json
691+
Do not run doctor as routine QA/dogfood prep. Use doctor only when the user asks for setup diagnostics or a command failure points to an unhealthy device, runner, dev-server, or remote environment.
698692
For "start from screen X" flows, prefer open --relaunch before the first snapshot so the app does not reuse a prior in-progress navigation state.
699693
JS-only change with Metro or Re.Pack connected:
700694
agent-device metro reload

‎src/commands/interaction/metadata.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -57,11 +57,11 @@ const FIND_ACTION_VALUES = [
5757
const interactionCommandDescriptions = {
5858
click: 'Click or tap a semantic UI target by ref, selector, or point.',
5959
press: 'Press a semantic UI target by ref, selector, or point.',
60-
fill: 'Fill text into a semantic UI target by ref, selector, or point.',
60+
fill: 'Replace text in a semantic UI target by ref, selector, or point.',
6161
longpress: 'Long press by ref, selector, or point.',
6262
swipe: 'Swipe between two points.',
6363
focus: 'Focus input at coordinates.',
64-
type: 'Type text in the focused field.',
64+
type: 'Append text to the focused field.',
6565
scroll: 'Scroll in a direction or to an edge.',
6666
get: 'Get element text or attributes.',
6767
is: 'Assert UI state.',

‎src/commands/management/doctor.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import { managementCliOutputFormatters } from './output.ts';
1010

1111
const doctorCommandMetadata = defineFieldCommandMetadata(
1212
'doctor',
13-
'Diagnose device, app, Metro, and React Native readiness before a run.',
13+
'Diagnose device, app, Metro, and React Native setup/readiness issues.',
1414
{
1515
targetApp: commandInput.stringField(
1616
'Installed app package/bundle id or app name to verify without opening a session.',
@@ -29,8 +29,8 @@ const doctorCliSchema = {
2929
usageOverride:
3030
'doctor [--platform ios|android|macos|linux|web|apple] [--app <id-or-name>] [--remote]',
3131
helpDescription:
32-
'Preflight for QA and dogfood runs. Reports local device inventory, active sessions, optional app discovery, scoped toolchain info, and Metro reachability inferred from cwd/runtime. On iOS simulators it also warms the XCTest runner build cache in the background when missing, so the first open on a fresh machine skips the runner build — run doctor first on new setups. Pass --app to verify a target app on the one matching booted device without opening a session. Use --remote to check remote connection setup without probing local devices. Default output is compact; use --json for full checks and evidence.',
33-
summary: 'Preflight device, app, dev-server, and RN/Expo readiness',
32+
'Setup and recovery diagnostic for device, app, dev-server, and RN/Expo readiness issues. Reports local device inventory, active sessions, optional app discovery, scoped toolchain info, and Metro reachability inferred from cwd/runtime. On iOS simulators it also warms the XCTest runner build cache in the background when missing. Pass --app to verify a target app on the one matching booted device without opening a session. Use --remote to check remote connection setup without probing local devices. Default output is compact; use --json for full checks and evidence.',
33+
summary: 'Diagnose device, app, dev-server, and RN/Expo readiness',
3434
allowedFlags: ['targetApp', 'remote'],
3535
} as const satisfies CommandSchemaOverride;
3636

‎website/docs/docs/installation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,14 @@ Install `agent-device` on the machine where the coding agent will run terminal c
1111

1212
```bash
1313
npm install -g agent-device@latest
14+
agent-device doctor
1415
agent-device --version
1516
agent-device help
1617
```
1718

19+
Run `agent-device doctor` yourself after installation to check local device,
20+
toolchain, and dev-server readiness before handing the CLI to an agent.
21+
1822
Use global install for normal agent workflows. It gives agents a stable `agent-device` command and version-matched help topics:
1923

2024
```bash
@@ -32,6 +36,7 @@ Interactive CLI runs periodically check for a newer published `agent-device` pac
3236

3337
```bash
3438
npm install -g agent-device@latest
39+
agent-device doctor
3540
agent-device --version
3641
```
3742

0 commit comments

Comments
 (0)