agent-device 0.13.3 → 0.14.1

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -285,20 +285,44 @@ extension RunnerTests {
   }
 
   private func tapKeyboardDismissControl(app: XCUIApplication) -> Bool {
-    for label in ["Hide keyboard", "Dismiss keyboard"] {
+    let keyboardFrame = app.keyboards.firstMatch.frame
+    for label in ["Hide keyboard", "Dismiss keyboard", "Done"] {
       let candidates = [
         app.keyboards.buttons[label],
         app.keyboards.keys[label],
-        app.toolbars.buttons[label],
+        app.keyboards.toolbars.buttons[label],
       ]
       if let hittable = candidates.first(where: { $0.exists && $0.isHittable }) {
         hittable.tap()
         return true
       }
+
+      let toolbarButtonPredicate = NSPredicate(
+        format: "label == %@ OR identifier == %@",
+        label,
+        label
+      )
+      let toolbarButtons = app.toolbars.buttons
+        .matching(toolbarButtonPredicate)
+        .allElementsBoundByIndex
+      if let hittable = toolbarButtons.first(where: {
+        $0.exists && $0.isHittable && isKeyboardAccessoryControl($0, keyboardFrame: keyboardFrame)
+      }) {
+        hittable.tap()
+        return true
+      }
     }
     return false
   }
 
+  private func isKeyboardAccessoryControl(_ element: XCUIElement, keyboardFrame: CGRect) -> Bool {
+    let frame = element.frame
+    guard !frame.isEmpty && !keyboardFrame.isEmpty else {
+      return false
+    }
+    return frame.intersects(keyboardFrame) || abs(frame.maxY - keyboardFrame.minY) <= 80
+  }
+
   private func moveCaretToEnd(element: XCUIElement) {
     let frame = element.frame
     guard !frame.isEmpty else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.13.3",
+  "version": "0.14.1",
   "description": "Agent-driven CLI for mobile UI automation, network inspection, and performance diagnostics across iOS, Android, tvOS, and macOS.",
   "license": "MIT",
   "author": "Callstack",
@@ -13,6 +13,7 @@
     "url": "https://github.com/callstackincubator/agent-device/issues"
   },
   "type": "module",
+  "packageManager": "pnpm@10.33.2",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
   "exports": {
@@ -44,6 +45,10 @@
       "import": "./dist/src/android-apps.js",
       "types": "./dist/src/android-apps.d.ts"
     },
+    "./android-snapshot-helper": {
+      "import": "./dist/src/android-snapshot-helper.js",
+      "types": "./dist/src/android-snapshot-helper.d.ts"
+    },
     "./contracts": {
       "import": "./dist/src/contracts.js",
       "types": "./dist/src/contracts.d.ts"
@@ -58,7 +63,7 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.19"
   },
   "bin": {
     "agent-device": "bin/agent-device.mjs"
@@ -71,19 +76,31 @@
     "build:xcuitest:ios": "AGENT_DEVICE_XCUITEST_PLATFORM=ios AGENT_DEVICE_IOS_CLEAN_DERIVED=1 sh ./scripts/build-xcuitest-apple.sh",
     "build:xcuitest:macos": "AGENT_DEVICE_XCUITEST_PLATFORM=macos sh ./scripts/build-xcuitest-apple.sh",
     "build:xcuitest:tvos": "AGENT_DEVICE_XCUITEST_PLATFORM=tvos AGENT_DEVICE_IOS_CLEAN_DERIVED=1 sh ./scripts/build-xcuitest-apple.sh",
+    "build:android-snapshot-helper": "sh ./scripts/build-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
+    "package:android-snapshot-helper": "sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") .tmp/android-snapshot-helper",
+    "package:android-snapshot-helper:npm": "rm -rf android-snapshot-helper/dist && sh ./scripts/package-android-snapshot-helper.sh $(node -p \"require('./package.json').version\") v$(node -p \"require('./package.json').version\") android-snapshot-helper/dist",
     "build:macos-helper": "swift build -c release --package-path macos-helper",
     "build:all": "pnpm build:node && pnpm build:xcuitest",
     "ad": "node bin/agent-device.mjs",
     "lint": "oxlint . --deny-warnings",
-    "format": "oxfmt --write src test skills package.json tsconfig.json .oxlintrc.json .oxfmtrc.json",
+    "format": "oxfmt --write src test skills package.json tsconfig.json tsconfig.lib.json rslib.config.ts vitest.config.ts .github/actions/setup-node-pnpm/action.yml .oxlintrc.json .oxfmtrc.json '!test/skillgym/.skillgym-results/**'",
+    "fallow": "fallow --summary",
+    "fallow:baseline": "(fallow dead-code --save-baseline fallow-baselines/dead-code.json --summary || true) && (fallow dupes --save-baseline fallow-baselines/dupes.json --summary || true) && (fallow health --save-baseline fallow-baselines/health.json --summary || true)",
+    "check:fallow": "fallow audit",
     "check:quick": "pnpm lint && pnpm typecheck",
     "check:tooling": "pnpm lint && pnpm typecheck && pnpm build",
     "check:unit": "pnpm test:unit && pnpm test:smoke",
-    "check": "pnpm check:tooling && pnpm check:unit",
-    "prepack": "pnpm build:all",
+    "check": "pnpm check:tooling && pnpm check:fallow && pnpm check:unit",
+    "prepack": "pnpm build:all && pnpm package:android-snapshot-helper:npm",
     "typecheck": "tsc -p tsconfig.json",
+    "test-app:install": "pnpm install --dir examples/test-app --ignore-workspace",
+    "test-app:start": "pnpm --dir examples/test-app start",
+    "test-app:ios": "pnpm --dir examples/test-app ios",
+    "test-app:android": "pnpm --dir examples/test-app android",
+    "test-app:typecheck": "pnpm --dir examples/test-app typecheck",
     "test": "vitest run",
     "test:unit": "vitest run",
+    "test:skillgym": "pnpm build && skillgym run ./test/skillgym/suites/agent-device-smoke-suite.ts --config ./test/skillgym/skillgym.config.ts",
     "test:smoke": "node --test test/integration/smoke-*.test.ts",
     "test:integration": "node --test test/integration/*.test.ts",
     "test:replay:ios": "node --experimental-strip-types src/bin.ts test test/integration/replays/ios/simulator",
@@ -102,6 +119,8 @@
     "!ios-runner/**/*.xcuserstate",
     "macos-helper",
     "!macos-helper/**/.build",
+    "android-snapshot-helper/dist",
+    "!android-snapshot-helper/dist/*.idsig",
     "src/platforms/linux/atspi-dump.py",
     "skills",
     "README.md",
@@ -132,18 +151,19 @@
     "performance"
   ],
   "dependencies": {
-    "fast-xml-parser": "^5.5.10",
+    "fast-xml-parser": "^5.7.2",
     "pngjs": "^7.0.0"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.58.1",
+    "vitest": "^4.1.2",
     "@rslib/core": "0.20.1",
     "@types/node": "^22.0.0",
     "@types/pngjs": "^6.0.5",
+    "fallow": "^2.52.0",
     "oxfmt": "^0.42.0",
     "oxlint": "^1.57.0",
+    "skillgym": "^0.5.0",
     "typescript": "^6.0.2",
-    "vite": "^8.0.7",
-    "vitest": "^4.1.2"
+    "vite": "^8.0.10"
   }
 }

package/skills/agent-device/SKILL.md

@@ -1,76 +1,34 @@
 ---
 name: agent-device
-description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, extracting UI info, or collecting logs, network inspection, and perf snapshots across mobile, TV, and desktop targets.
+description: Automates Apple-platform apps (iOS, tvOS, macOS) and Android devices. Use when navigating apps, taking snapshots/screenshots, tapping, typing, scrolling, extracting UI info, collecting logs/network/perf evidence, or planning agent-device CLI commands.
 ---
 
 # agent-device
 
-Use this skill as a router with mandatory defaults. Read this file first. For normal device tasks, always load `references/bootstrap-install.md` and `references/exploration.md` before acting. Use bootstrap to confirm or establish deterministic setup. Use exploration for UI inspection, interaction, and verification once the app session is open.
+Router only. Private setup before using this skill:
 
-## Default operating rules
+```bash
+agent-device --version
+```
 
-- Start conservative. Prefer read-only inspection before mutating the UI.
-- Start deterministic. If the app name, package, device, or session is uncertain, load bootstrap and discover them before interacting.
-- Use plain `snapshot` when the task is to verify what text or structure is currently visible on screen.
-- Use `snapshot -i` only when you need interactive refs such as `@e3` for a requested action or targeted query. On iOS and Android, default snapshot output uses the same visible-first model: off-screen interactive content is exposed as discovery hints, not tappable refs.
-- Prefer `diff snapshot` after a nearby mutation when you only need to know what changed.
-- Avoid speculative mutations. You may take the smallest reversible UI action needed to unblock inspection or complete the requested task, such as dismissing a popup, closing an alert, or clearing an unintended surface.
-- In React Native dev or debug builds, check early for visible warning or error overlays, tooltips, and toasts that can steal focus or intercept taps. If they are not part of the requested behavior, dismiss them and continue. If you saw them, report them in the final summary.
-- In Metro-backed React Native dev loops, use `agent-device metro reload` for a JS app reload before falling back to `open <app> --relaunch`. It mirrors pressing `r` in the Metro terminal and preserves the native app process.
-- Do not browse the web or use external sources unless the user explicitly asks.
-- Re-snapshot after meaningful UI changes instead of reusing stale refs.
-- Treat refs in default snapshot output as actionable-now, not durable identities. If a target appears only in an off-screen summary, use `scroll <direction>` and re-snapshot until the target is visible.
-- Prefer `@ref` or selector targeting over raw coordinates.
-- Ensure the correct target is pinned and an app session is open before interacting.
-- Keep the loop short: `open` -> inspect/act -> verify if needed -> `close`.
+Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
 
-## Default flow
+Before your first agent-device command or plan, read the version-matched CLI guide:
 
-1. Load [references/bootstrap-install.md](references/bootstrap-install.md) and [references/exploration.md](references/exploration.md) before acting on a normal device task.
-2. Use bootstrap first to confirm or establish the correct target, app install, and open app session.
-3. Once the app session is open and stable, use exploration for inspection, interaction, and verification.
-4. Start with plain `snapshot` if the goal is to read or verify what is visible.
-5. Escalate to `snapshot -i` only if you need refs for interactive exploration or a requested action.
-6. Use `get`, `is`, or `find` before mutating the UI when a read-only command can answer the question.
-7. End by capturing proof if needed, then `close`.
+```bash
+agent-device help workflow
+```
 
-## QA modes
+Escalate only when relevant:
 
-- Open-ended bug hunt with reporting: use [../dogfood/SKILL.md](../dogfood/SKILL.md).
-- Pass/fail QA from acceptance criteria: stay in this skill, start with [references/bootstrap-install.md](references/bootstrap-install.md), then use the QA loop in [references/exploration.md](references/exploration.md).
+```bash
+agent-device help debugging
+agent-device help react-devtools
+agent-device help remote
+agent-device help macos
+agent-device help dogfood
+```
 
-## Required references
+Default loop: `open -> snapshot/-i -> get/is/find or press/fill/scroll/wait -> verify -> close`.
 
-- For every normal device task, after reading this file, load [references/bootstrap-install.md](references/bootstrap-install.md) first, then [references/exploration.md](references/exploration.md), before acting.
-- Use bootstrap to confirm or establish deterministic setup, especially in sandbox or cloud environments.
-- Use exploration once the app session is open and stable.
-- Load additional references only when their scope is needed.
-
-## Decision rules
-
-- Use plain `snapshot` when you need to verify whether text is visible.
-- Use `snapshot -i` mainly for interactive exploration and choosing refs.
-- Use `diff snapshot` for compact post-action verification; use `snapshot --diff` when that alias is easier to discover from snapshot help.
-- Use `get`, `is`, or `find` when they can answer the question without changing UI state.
-- Use `fill` to replace text.
-- Use `type` to append text.
-- Do not write `type @eN "text"`. Use `fill @eN "text"` to target a field directly, or `press @eN` then `type "text"` when the field already has focus and you want append semantics.
-- If the on-screen keyboard blocks the next step, prefer `keyboard dismiss` over navigation. On iOS, keep an app session open first; `keyboard status|get` remains Android-only.
-- When a task asks to "go back", use plain `back` for predictable app-owned navigation and reserve `back --system` for platform back gestures or button semantics.
-- Use `type --delay-ms` or `fill --delay-ms` for debounced search fields that drop characters when typed too quickly.
-- If there is no simulator, no app install, or no open app session yet, switch to `bootstrap-install.md` instead of improvising setup steps.
-- Use the smallest unblock action first when transient UI blocks inspection, but do not navigate, search, or enter new text just to make the UI reveal data unless the user asked for that interaction.
-- In React Native dev or debug apps, treat visible warning or error overlays as transient blockers unless the user is explicitly asking you to diagnose them. Dismiss them when safe, then continue the requested flow.
-- For React Native code changes where the app is already connected to Metro, prefer `agent-device metro reload`, then wait and re-snapshot. Use `open <app> --relaunch` only when Metro reload does not reconnect or native startup state must reset.
-- Do not use external lookups to compensate for missing on-screen data unless the user asked for them.
-- If the needed information is not exposed on screen, say that plainly instead of compensating with extra navigation, text entry, or web search.
-- Prefer `@ref` or selector targeting over raw coordinates.
-
-## Additional references
-
-- Need logs, network, alerts, permissions, or failure triage: [references/debugging.md](references/debugging.md)
-- Need screenshots, diff, recording, replay maintenance, or perf data: [references/verification.md](references/verification.md)
-- Need desktop surfaces, menu bar behavior, or macOS-specific interaction rules: [references/macos-desktop.md](references/macos-desktop.md)
-- Need remote HTTP transport, `connect --remote-config`, or tenant leases on a remote macOS host: [references/remote-tenancy.md](references/remote-tenancy.md)
-  This includes remote React Native runs where `agent-device` now prepares Metro locally and manages the local Metro companion tunnel automatically.
-- Need the React Native component tree, props, state, hooks, or render profiling: use `agent-device react-devtools ...` and the [react-devtools skill](../react-devtools/SKILL.md).
+Use this skill only to route into version-matched CLI help. Let `help workflow` provide exact command shapes, platform limits, and current workflow guidance.

package/skills/dogfood/SKILL.md

@@ -1,184 +1,25 @@
 ---
 name: dogfood
-description: 'Systematically explore and test a mobile app on iOS/Android with agent-device to find bugs, UX issues, and other problems. Use when asked to "dogfood", "QA", "exploratory test", "find issues", "bug hunt", or "test this app" on mobile. Produces a structured report with reproducible evidence: screenshots, optional repro videos, and detailed steps for every issue.'
+description: Systematically explore and test a mobile app on iOS/Android with agent-device to find bugs, UX issues, and other problems. Use when asked to dogfood, QA, exploratory test, find issues, bug hunt, or test this app on mobile.
 allowed-tools: Bash(agent-device:*), Bash(npx agent-device:*)
 ---
 
-# Dogfood (agent-device)
+# Dogfood
 
-Systematically explore a mobile app, find issues, and produce a report with full reproduction evidence for every finding.
-
-## Setup
-
-Only the **Target app** is required. Everything else has sensible defaults.
-
-| Parameter            | Default                                                     | Example override                             |
-| -------------------- | ----------------------------------------------------------- | -------------------------------------------- |
-| **Target app**       | _(required)_                                                | `Settings`, `com.example.app`, deep link URL |
-| **Platform**         | Infer from user context; otherwise ask (`ios` or `android`) | `--platform ios`                             |
-| **Session name**     | Slugified app/platform (for example `settings-ios`)         | `--session my-session`                       |
-| **Output directory** | `./dogfood-output/`                                         | `Output directory: /tmp/mobile-qa`           |
-| **Scope**            | Full app                                                    | `Focus on onboarding and profile`            |
-| **Authentication**   | None                                                        | `Sign in to user@example.com`                |
-
-If the user gives enough context to start, begin immediately with defaults. Ask follow-up only when a required detail is missing (for example platform or credentials).
-
-Prefer direct `agent-device` binary when available.
-
-## Workflow
-
-```
-1. Initialize    Set up session, output dirs, report file
-2. Launch/Auth   Open app and sign in if needed
-3. Orient        Capture initial snapshot and map navigation
-4. Explore       Systematically test flows and states
-5. Document      Record reproducible evidence per issue
-6. Wrap up       Reconcile summary, close session
-```
-
-### 1. Initialize
-
-```bash
-mkdir -p {OUTPUT_DIR}/screenshots {OUTPUT_DIR}/videos
-cp {SKILL_DIR}/templates/dogfood-report-template.md {OUTPUT_DIR}/report.md
-```
-
-### 2. Launch/Auth
-
-Start a named session and launch target app:
-
-```bash
-agent-device --session {SESSION} open {TARGET_APP} --platform {PLATFORM}
-agent-device --session {SESSION} snapshot -i
-```
-
-If login is required:
+Router for exploratory QA. Private setup before using this skill:
 
 ```bash
-agent-device --session {SESSION} snapshot -i
-agent-device --session {SESSION} fill @e1 "{EMAIL}"
-agent-device --session {SESSION} fill @e2 "{PASSWORD}"
-agent-device --session {SESSION} press @e3
-agent-device --session {SESSION} wait 1000
-agent-device --session {SESSION} snapshot -i
+agent-device --version
 ```
 
-For OTP/email codes: ask the user, wait for input, then continue.
-
-### 3. Orient
+Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
 
-Capture initial evidence and navigation anchors:
+Read current CLI guidance:
 
 ```bash
-agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/initial.png
-agent-device --session {SESSION} snapshot -i
+agent-device help dogfood
 ```
 
-Map top-level navigation, tabs, and key workflows before deep testing.
-
-### 4. Explore
-
-Read [references/issue-taxonomy.md](references/issue-taxonomy.md) for severity/category calibration.
-
-Strategy:
-
-- Move through each major app area (tabs, drawers, settings pages).
-- Test core journeys end-to-end (create, edit, delete, submit, recover).
-- Validate edge states (empty/error/loading/offline/permissions denied).
-- Use `diff snapshot -i` after UI transitions to avoid stale refs.
-- Periodically capture `logs path` and inspect the app log when behavior looks suspicious.
-
-Useful commands per screen:
-
-```bash
-agent-device --session {SESSION} snapshot -i
-agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/{screen-name}.png
-agent-device --session {SESSION} appstate
-agent-device --session {SESSION} logs path
-```
-
-### 5. Document Issues (Repro-First)
-
-Explore and document in one pass. When you find an issue, stop and fully capture evidence before continuing.
-
-#### Interactive/behavioral issues
-
-Use video + step screenshots:
-
-1. Start recording:
-
-```bash
-agent-device --session {SESSION} record start {OUTPUT_DIR}/videos/issue-{NNN}-repro.mp4
-```
-
-2. Reproduce with visible pacing. Capture each step:
-
-```bash
-agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-1.png
-sleep 1
-# perform action
-sleep 1
-agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-step-2.png
-```
-
-3. Capture final broken state:
-
-```bash
-sleep 2
-agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}-result.png
-```
-
-4. Stop recording:
-
-```bash
-agent-device --session {SESSION} record stop
-```
-
-5. Append issue immediately to report with numbered steps and screenshot references.
-
-#### Static/on-load issues
-
-Single screenshot is sufficient; no video required:
-
-```bash
-agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/issue-{NNN}.png
-```
-
-Set **Repro Video** to `N/A` in the report.
-
-### 6. Wrap Up
-
-Target 5-10 well-evidenced issues, then finish:
-
-1. Reconcile summary severity counts in `report.md`.
-2. Close session:
-
-```bash
-agent-device --session {SESSION} close
-```
-
-3. Report total issues, severity breakdown, and highest-risk findings.
-
-## Guidance
-
-- Repro quality matters more than issue count.
-- Use refs (`@eN`) for fast exploration, selectors for deterministic replay assertions when needed.
-- Re-snapshot after any mutation (navigation, modal, list update, form submit).
-- Use `fill` for clear-then-type semantics; use `type` for incremental typing behavior checks.
-- Keep logs optional and targeted: enable/read app logs only when useful for diagnosis.
-- If the issue appears rooted in React Native internals rather than device/app runtime behavior, use `agent-device react-devtools ...` and the `skills/react-devtools` workflow for component-tree or render-profiling inspection.
-- Never read source code of the app under test; findings must come from observed runtime behavior.
-- Write each issue immediately to avoid losing evidence.
-- Never delete screenshots/videos/report artifacts during a session.
-
-## References
-
-| Reference                                                    | When to Read                                    |
-| ------------------------------------------------------------ | ----------------------------------------------- |
-| [references/issue-taxonomy.md](references/issue-taxonomy.md) | Start of session; severity/categories/checklist |
-
-## Templates
+Loop: open named session -> snapshot -i + screenshot -> explore flows -> capture evidence per issue -> close.
 
-| Template                                                                     | Purpose                                       |
-| ---------------------------------------------------------------------------- | --------------------------------------------- |
-| [templates/dogfood-report-template.md](templates/dogfood-report-template.md) | Copy into output directory as the report file |
+Target app is required; infer platform or ask. Findings must come from runtime behavior, not source reads. Let `help dogfood` provide exact report shape, evidence commands, and current workflow guidance.

package/skills/react-devtools/SKILL.md

@@ -1,55 +1,39 @@
 ---
 name: react-devtools
-description: Inspect and profile React Native component trees from agent-device. Use when debugging React Native props, state, hooks, render causes, slow components, excessive re-renders, or questions like why a component re-rendered.
+description: Inspect and profile React Native component trees from agent-device. Use for React Native performance, profiling, props, state, hooks, render causes, slow components, excessive rerenders, or questions like why a component rerendered.
 ---
 
 # react-devtools
 
-Use this skill when the task needs React Native internals that are not visible in the accessibility tree: component hierarchy, props, state, hooks, render causes, or profiling data.
+Router for React Native internals. Private setup before using this skill:
 
-Run commands through `agent-device react-devtools`. The command dynamically runs pinned `agent-react-devtools@0.4.0` and passes arguments through 1:1.
+```bash
+agent-device --version
+```
 
-The first run may download the pinned package from npm. `agent-device` global flags work before or after `react-devtools`; use `--` before downstream flags only when they intentionally share an `agent-device` global flag name.
+Require `agent-device >= 0.14.0`; older CLIs lack these help topics. If older, run `npm install -g agent-device@latest`, recheck, then continue. If you cannot upgrade, stop and tell the user. Do not include version/upgrade commands in final plans.
 
-## Default flow
+Read current CLI guidance:
 
-1. Use `agent-device` to open the React Native app and verify the visible state when needed.
-2. Check `agent-device react-devtools status`.
-3. If no app is connected, start or wait for the devtools daemon, then reload or relaunch the app.
-4. Inspect with `get tree`, `find`, and `get component`.
-5. Profile only around the interaction being investigated.
-6. Verify the fix with the same command sequence and interaction.
+```bash
+agent-device help react-devtools
+```
 
-For cross-platform validation with explicit `--device`, `--udid`, or `--serial` selectors, prefer an isolated `--state-dir` over separate named sessions. Named sessions enable bound-session locks during setup. Restart `agent-device react-devtools` between iOS and Android runs so `status`, `get tree`, and profiling clearly refer to the currently launched app.
+Use `agent-device react-devtools ...` for component tree, props, state, hooks, render ownership, performance profiling, slow components, or rerenders. It dynamically runs pinned `agent-react-devtools@0.4.0`. Use normal `agent-device` commands for visible UI, refs, screenshots, logs, network, or device-level perf.
 
-## Main commands
+Core loop:
 
 ```bash
 agent-device react-devtools status
 agent-device react-devtools wait --connected
 agent-device react-devtools get tree --depth 3
-agent-device react-devtools find <ComponentName>
-agent-device react-devtools get component @c5
 agent-device react-devtools profile start
+# perform the interaction with normal agent-device commands
 agent-device react-devtools profile stop
 agent-device react-devtools profile slow --limit 5
 agent-device react-devtools profile rerenders --limit 5
 ```
 
-## Decision rules
-
-- Need current UI text, refs, screenshots, logs, network, or device metrics: use the `agent-device` skill.
-- Need props, state, hooks, component ownership, render causes, or React profiler data: use this skill.
-- Start component-tree reads with `get tree --depth 3` or `find <name>` to keep output bounded.
-- Labels like `@c5` reset when the app reloads or components remount. After reload, run `wait --connected` and inspect again.
-- Profiling only captures renders between `profile start` and `profile stop`.
-- On Android, set `adb reverse tcp:8097 tcp:8097` for React DevTools. If Metro is local, also set `adb reverse tcp:8081 tcp:8081`.
-- For Android sessions connected through `agent-device connect --remote-config`, run `agent-device react-devtools ...` normally. The CLI registers a bridge companion tunnel to the local DevTools daemon on `127.0.0.1:8097` and unregisters it when the command exits.
-- Remote Android React DevTools assumes the React Native-bundled DevTools behavior in React Native 0.83+. Do not assume older browser/Chromium DevTools workflows exist in remote sandboxes. For Expo apps, verify the SDK's bundled React Native version and runtime behavior first; no Expo SDK version is separately verified by this skill.
-
-## References
+Rules:
 
-| File                                    | When to read                                  |
-| --------------------------------------- | --------------------------------------------- |
-| [commands.md](references/commands.md)   | Command reference and common inspection flows |
-| [profiling.md](references/profiling.md) | Render profiling workflow and interpretation  |
+Keep reads bounded with `--depth`/`find`, treat `@c` refs as reload-local, profile only the investigated interaction, and run the same command in remote Android sessions; the CLI manages the needed local service tunnel.