docs: clarify agent setup and text entry guidance

README.md

@@ -52,11 +52,15 @@ Install the CLI:
 
 ```bash
 npm install -g agent-device@latest
+agent-device doctor
 agent-device --version
 agent-device help workflow
 ```
 
-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.
+Run `agent-device doctor` yourself after installation to check local setup before
+handing the CLI to an agent. 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.
 
 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.
 

skills/agent-device/SKILL.md

@@ -38,8 +38,6 @@ agent-device help dogfood
 
 Default loop: `open -> snapshot/-i -> get/is/find or press/fill/scroll/wait -> verify -> close`.
 
-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.
-
 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.
 
 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

@@ -107,7 +107,8 @@ test('usage includes agent workflows, config, environment, and examples footers'
   assert.match(usageText, /open "Expo Go" <url> --platform ios/);
   assert.match(usageText, /Do not use plain snapshot or snapshot --diff for this recovery check/);
   assert.match(usageText, /Install flows: install\/install-from-source first/);
-  assert.match(usageText, /fill 'id="field-email"' "qa@example\.com" replaces/);
+  assert.match(usageText, /use fill <target> <text> --settle to replace a field value/);
+  assert.match(usageText, /Use type <text> only to append after focusing a field with press/);
   assert.match(usageText, /do not use fill <target> ""/);
   assert.match(usageText, /Android IME capture: if fill says input was captured/);
   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'
   assert.match(usageText, /After mutation: refs are stale/);
   assert.match(usageText, /use its selector directly; otherwise refresh with snapshot -i/);
   assert.match(usageText, /verify the action with diff snapshot -i or snapshot --diff/);
+  assert.match(usageText, /fill <targetOrX> <yOrText> \[text\]\s+Replace text in/);
+  assert.match(usageText, /type <text>\s+Append text to the focused field/);
   assert.match(usageText, /Sparse or AX-unavailable snapshot/);
   assert.match(usageText, /macOS context menus use click <ref> --button secondary/);
   assert.match(
@@ -456,6 +459,8 @@ test('usageForCommand resolves manual QA help topic', async () => {
   assert.match(help, /Run snapshot -i to get current refs/);
   assert.match(help, /press\/fill\/click\/longpress <ref-or-selector> --settle/);
   assert.match(help, /A bare screenshot\/snapshot is not verification/);
+  assert.match(help, /use fill <target> <text> --settle to replace/);
+  assert.match(help, /use type only to append to an already-focused field/);
   assert.match(help, /Do not use placeholders such as @ref/);
 });
 
@@ -556,10 +561,8 @@ test('usageForCommand resolves react-native help topic', async () => {
   assert.match(help, /help react-devtools/);
   assert.match(help, /Help workflow owns the full Expo URL command shapes/);
   assert.match(help, /For app\/package launches, run metro prepare/);
-  assert.match(help, /agent-device doctor --platform android/);
-  assert.match(help, /agent-device doctor --platform android --app com\.example\.app/);
-  assert.match(help, /agent-device doctor --platform ios/);
-  assert.match(help, /agent-device doctor --remote --remote-config \.\/remote\.json/);
+  assert.match(help, /Do not run doctor as routine QA\/dogfood prep/);
+  assert.match(help, /Use doctor only when the user asks for setup diagnostics/);
   assert.match(help, /same host context that owns the dev server/);
   assert.match(help, /sandbox probe is not authoritative/);
   assert.match(help, /adb reverse only affects Android device-to-host traffic/);

src/cli/parser/cli-help.ts

@@ -93,7 +93,7 @@ const AGENT_QUICKSTART_LINES = [
   'Android RN/Expo/Re.Pack dev server: direct Android localhost URL opens with a port auto-configure host reachability.',
   '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.',
   'Install flows: install/install-from-source first, then open the installed id with --relaunch.',
-  'Text: fill \'id="field-email"\' "qa@example.com" replaces; type appends after press.',
+  'Text fields: use fill <target> <text> --settle to replace a field value. Use type <text> only to append after focusing a field with press.',
   'Clearing text: do not use fill <target> ""; use a visible clear/reset control or report that clearing is unsupported.',
   '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.',
   '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:
 
 Targets:
   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".
+  For text fields, use fill <target> <text> --settle to replace the field value; use type only to append to an already-focused field.
   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.
   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.
 
@@ -187,9 +188,6 @@ Core loop:
   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.
   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.
 
-Fresh machine or first iOS run:
-  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.
-
 Command shape:
   Plans should use agent-device commands, not raw platform tools, pseudo commands, package-manager aliases, or helper prose.
   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:
   Remote/cloud config, leases, and local service tunnels: help remote.
 
 React Native dev loop:
-  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):
-    agent-device doctor --platform android
-    agent-device doctor --platform ios
-    agent-device doctor --platform android --app com.example.app
-    agent-device doctor --remote --remote-config ./remote.json
+  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.
   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.
   JS-only change with Metro or Re.Pack connected:
     agent-device metro reload

src/commands/interaction/metadata.ts

@@ -57,11 +57,11 @@ const FIND_ACTION_VALUES = [
 const interactionCommandDescriptions = {
   click: 'Click or tap a semantic UI target by ref, selector, or point.',
   press: 'Press a semantic UI target by ref, selector, or point.',
-  fill: 'Fill text into a semantic UI target by ref, selector, or point.',
+  fill: 'Replace text in a semantic UI target by ref, selector, or point.',
   longpress: 'Long press by ref, selector, or point.',
   swipe: 'Swipe between two points.',
   focus: 'Focus input at coordinates.',
-  type: 'Type text in the focused field.',
+  type: 'Append text to the focused field.',
   scroll: 'Scroll in a direction or to an edge.',
   get: 'Get element text or attributes.',
   is: 'Assert UI state.',

src/commands/management/doctor.ts

@@ -10,7 +10,7 @@ import { managementCliOutputFormatters } from './output.ts';
 
 const doctorCommandMetadata = defineFieldCommandMetadata(
   'doctor',
-  'Diagnose device, app, Metro, and React Native readiness before a run.',
+  'Diagnose device, app, Metro, and React Native setup/readiness issues.',
   {
     targetApp: commandInput.stringField(
       'Installed app package/bundle id or app name to verify without opening a session.',
@@ -29,8 +29,8 @@ const doctorCliSchema = {
   usageOverride:
     'doctor [--platform ios|android|macos|linux|web|apple] [--app <id-or-name>] [--remote]',
   helpDescription:
-    '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.',
-  summary: 'Preflight device, app, dev-server, and RN/Expo readiness',
+    '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.',
+  summary: 'Diagnose device, app, dev-server, and RN/Expo readiness',
   allowedFlags: ['targetApp', 'remote'],
 } as const satisfies CommandSchemaOverride;
 

website/docs/docs/installation.md

@@ -11,10 +11,14 @@ Install `agent-device` on the machine where the coding agent will run terminal c
 
 ```bash
 npm install -g agent-device@latest
+agent-device doctor
 agent-device --version
 agent-device help
 ```
 
+Run `agent-device doctor` yourself after installation to check local device,
+toolchain, and dev-server readiness before handing the CLI to an agent.
+
 Use global install for normal agent workflows. It gives agents a stable `agent-device` command and version-matched help topics:
 
 ```bash
@@ -32,6 +36,7 @@ Interactive CLI runs periodically check for a newer published `agent-device` pac
 
 ```bash
 npm install -g agent-device@latest
+agent-device doctor
 agent-device --version
 ```