agent-device 0.10.2 → 0.11.0

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

@@ -1,7 +1,16 @@
 import XCTest
 
 extension RunnerTests {
+  private static let collapsedTabCandidateTypes: Set<XCUIElement.ElementType> = [
+    .button,
+    .link,
+    .menuItem,
+    .other,
+    .staticText
+  ]
+
   private struct SnapshotTraversalContext {
+    let queryRoot: XCUIElement
     let rootSnapshot: XCUIElementSnapshot
     let viewport: CGRect
     let flatSnapshots: [XCUIElementSnapshot]
@@ -68,12 +77,34 @@ extension RunnerTests {
       return DataPayload(nodes: [], truncated: false)
     }
 
+    var cachedDescendantElements: [XCUIElement]?
+    func collapsedTabDescendants() -> [XCUIElement] {
+      if let cachedDescendantElements {
+        return cachedDescendantElements
+      }
+      let fetched = safeSnapshotElementsQuery {
+        context.queryRoot.descendants(matching: .any).allElementsBoundByIndex
+      }
+      cachedDescendantElements = fetched
+      return fetched
+    }
+
     var nodes: [SnapshotNode] = []
     var truncated = false
     let rootEvaluation = evaluateSnapshot(context.rootSnapshot, in: context)
     nodes.append(
       makeSnapshotNode(snapshot: context.rootSnapshot, evaluation: rootEvaluation, depth: 0, index: 0)
     )
+    if context.maxDepth > 0 {
+      let didTruncateFallback = appendCollapsedTabFallbackNodes(
+        to: &nodes,
+        containerSnapshot: context.rootSnapshot,
+        resolveElements: collapsedTabDescendants,
+        depth: 1,
+        nodeLimit: fastSnapshotLimit
+      )
+      truncated = truncated || didTruncateFallback
+    }
 
     var seen = Set<String>()
     var stack: [(XCUIElementSnapshot, Int, Int)] = context.rootSnapshot.children.map { ($0, 1, 1) }
@@ -119,6 +150,16 @@ extension RunnerTests {
           index: nodes.count
         )
       )
+      if visibleDepth < context.maxDepth {
+        let didTruncateFallback = appendCollapsedTabFallbackNodes(
+          to: &nodes,
+          containerSnapshot: snapshot,
+          resolveElements: collapsedTabDescendants,
+          depth: visibleDepth + 1,
+          nodeLimit: fastSnapshotLimit
+        )
+        truncated = truncated || didTruncateFallback
+      }
 
     }
 
@@ -247,6 +288,7 @@ extension RunnerTests {
 
     let (flatSnapshots, snapshotRanges) = flattenedSnapshots(rootSnapshot)
     return SnapshotTraversalContext(
+      queryRoot: queryRoot,
       rootSnapshot: rootSnapshot,
       viewport: viewport,
       flatSnapshots: flatSnapshots,
@@ -376,4 +418,183 @@ extension RunnerTests {
     if rect.isNull || rect.isEmpty { return false }
     return rect.intersects(viewport)
   }
+
+  private func appendCollapsedTabFallbackNodes(
+    to nodes: inout [SnapshotNode],
+    containerSnapshot: XCUIElementSnapshot,
+    resolveElements: () -> [XCUIElement],
+    depth: Int,
+    nodeLimit: Int
+  ) -> Bool {
+    let fallbackNodes = collapsedTabFallbackNodes(
+      for: containerSnapshot,
+      resolveElements: resolveElements,
+      startingIndex: nodes.count,
+      depth: depth
+    )
+    if fallbackNodes.isEmpty { return false }
+    let remaining = max(0, nodeLimit - nodes.count)
+    if remaining == 0 { return true }
+    nodes.append(contentsOf: fallbackNodes.prefix(remaining))
+    return fallbackNodes.count > remaining
+  }
+
+  private func collapsedTabFallbackNodes(
+    for containerSnapshot: XCUIElementSnapshot,
+    resolveElements: () -> [XCUIElement],
+    startingIndex: Int,
+    depth: Int
+  ) -> [SnapshotNode] {
+    if !containerSnapshot.children.isEmpty { return [] }
+    guard shouldExpandCollapsedTabContainer(containerSnapshot) else { return [] }
+    let containerFrame = containerSnapshot.frame
+    if containerFrame.isNull || containerFrame.isEmpty { return [] }
+
+    // Collapsed tab containers should be rare, so a full descendant scan is acceptable once per
+    // snapshot as a fallback for XCTest omitting the tab children from the snapshot tree.
+    let elements = resolveElements()
+    let candidates = elements.compactMap { element in
+      collapsedTabCandidateNode(
+        element: element,
+        containerSnapshot: containerSnapshot,
+        containerFrame: containerFrame
+      )
+    }
+    .sorted { left, right in
+      if left.rect.x != right.rect.x {
+        return left.rect.x < right.rect.x
+      }
+      return left.rect.y < right.rect.y
+    }
+
+    if candidates.count < 2 { return [] }
+    let rowMidpoints = candidates.map { $0.rect.y + ($0.rect.height / 2) }
+    let rowSpread = (rowMidpoints.max() ?? 0) - (rowMidpoints.min() ?? 0)
+    // Allow modest vertical jitter and short two-row wraps while still rejecting unrelated controls.
+    if rowSpread > max(24.0, Double(containerFrame.height) * 0.6) { return [] }
+
+    var seen = Set<String>()
+    let uniqueCandidates = candidates.filter { node in
+      let key = "\(node.type)-\(node.label ?? "")-\(node.identifier ?? "")-\(node.value ?? "")-\(node.rect.x)-\(node.rect.y)-\(node.rect.width)-\(node.rect.height)"
+      if seen.contains(key) { return false }
+      seen.insert(key)
+      return true
+    }
+    if uniqueCandidates.count < 2 { return [] }
+
+    return uniqueCandidates.enumerated().map { offset, node in
+      SnapshotNode(
+        index: startingIndex + offset,
+        type: node.type,
+        label: node.label,
+        identifier: node.identifier,
+        value: node.value,
+        rect: node.rect,
+        enabled: node.enabled,
+        hittable: node.hittable,
+        depth: depth
+      )
+    }
+  }
+
+  private func collapsedTabCandidateNode(
+    element: XCUIElement,
+    containerSnapshot: XCUIElementSnapshot,
+    containerFrame: CGRect
+  ) -> SnapshotNode? {
+    var node: SnapshotNode?
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      if !element.exists { return }
+      let elementType = element.elementType
+      if !Self.collapsedTabCandidateTypes.contains(elementType) { return }
+      let frame = element.frame
+      if frame.isNull || frame.isEmpty { return }
+      if frame.equalTo(containerFrame) { return }
+      let area = max(CGFloat(1), frame.width * frame.height)
+      let containerArea = max(CGFloat(1), containerFrame.width * containerFrame.height)
+      if area >= containerArea * 0.9 { return }
+      let center = CGPoint(x: frame.midX, y: frame.midY)
+      if !containerFrame.contains(center) { return }
+
+      let label = element.label.trimmingCharacters(in: .whitespacesAndNewlines)
+      let identifier = element.identifier.trimmingCharacters(in: .whitespacesAndNewlines)
+      let valueText = snapshotValueText(element)
+      let hasContent = !label.isEmpty || !identifier.isEmpty || valueText != nil
+      if !hasContent { return }
+      if sameSemanticElement(
+        containerSnapshot: containerSnapshot,
+        elementType: elementType,
+        label: label,
+        identifier: identifier
+      ) {
+        return
+      }
+
+      node = SnapshotNode(
+        index: 0,
+        type: elementTypeName(elementType),
+        label: label.isEmpty ? nil : label,
+        identifier: identifier.isEmpty ? nil : identifier,
+        value: valueText,
+        rect: snapshotRect(from: frame),
+        enabled: element.isEnabled,
+        hittable: element.isHittable,
+        depth: 0
+      )
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_SNAPSHOT_TAB_FALLBACK_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      return nil
+    }
+    return node
+  }
+
+  private func shouldExpandCollapsedTabContainer(_ snapshot: XCUIElementSnapshot) -> Bool {
+    let frame = snapshot.frame
+    if frame.isNull || frame.isEmpty { return false }
+    if frame.width < max(CGFloat(160), frame.height * 1.75) { return false }
+    switch snapshot.elementType {
+    case .tabBar, .segmentedControl, .slider:
+      return true
+    default:
+      return false
+    }
+  }
+
+  private func snapshotValueText(_ element: XCUIElement) -> String? {
+    let text = String(describing: element.value ?? "")
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    return text.isEmpty ? nil : text
+  }
+
+  private func sameSemanticElement(
+    containerSnapshot: XCUIElementSnapshot,
+    elementType: XCUIElement.ElementType,
+    label: String,
+    identifier: String
+  ) -> Bool {
+    if containerSnapshot.elementType != elementType { return false }
+    let containerLabel = containerSnapshot.label.trimmingCharacters(in: .whitespacesAndNewlines)
+    let containerIdentifier = containerSnapshot.identifier
+      .trimmingCharacters(in: .whitespacesAndNewlines)
+    return containerLabel == label && containerIdentifier == identifier
+  }
+
+  private func safeSnapshotElementsQuery(_ fetch: () -> [XCUIElement]) -> [XCUIElement] {
+    var elements: [XCUIElement] = []
+    let exceptionMessage = RunnerObjCExceptionCatcher.catchException({
+      elements = fetch()
+    })
+    if let exceptionMessage {
+      NSLog(
+        "AGENT_DEVICE_RUNNER_SNAPSHOT_QUERY_IGNORED_EXCEPTION=%@",
+        exceptionMessage
+      )
+      return []
+    }
+    return elements
+  }
 }

package/ios-runner/README.md

@@ -1,16 +1,25 @@
 # agent-device iOS Runner
 
-This folder is reserved for the lightweight XCUITest runner used to provide element-level automation on iOS.
+This folder contains the lightweight XCUITest runner used to provide element-level automation for Apple-family targets.
 
 ## Intent
+
 - Provide a minimal XCTest target that exposes UI automation over a small HTTP server.
 - Allow local builds via `xcodebuild` and caching for faster subsequent runs.
 - Support simulator prebuilds where compatible.
 
 ## Status
-Planned for the automation layer. See `docs/ios-automation.md` and `docs/ios-runner-protocol.md`.
+
+Current internal runner for iOS, tvOS, and macOS desktop automation.
+
+Protocol and maintenance references:
+
+- Protocol overview: [`RUNNER_PROTOCOL.md`](RUNNER_PROTOCOL.md)
+- TypeScript client: [`../src/platforms/ios/runner-client.ts`](../src/platforms/ios/runner-client.ts)
+- Swift wire models: [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
 
 ## UITest Runner File Map
+
 `AgentDeviceRunnerUITests/RunnerTests` is split into focused files to reduce context size for contributors and LLM agents.
 
 - `RunnerTests.swift`: shared state/constants, `setUp()`, and `testCommand()` entry flow.
@@ -23,3 +32,9 @@ Planned for the automation layer. See `docs/ios-automation.md` and `docs/ios-run
 - `RunnerTests+Snapshot.swift`: fast/raw snapshot builders and include/filter helpers.
 - `RunnerTests+SystemModal.swift`: SpringBoard/system modal detection and modal snapshot shaping.
 - `RunnerTests+ScreenRecorder.swift`: nested `ScreenRecorder` implementation.
+
+## Protocol Notes
+
+- The daemon posts JSON commands to `POST /command` on the runner's local HTTP listener.
+- The runner responds with a JSON envelope shaped as `{ ok, data?, error? }`.
+- The protocol is internal to `agent-device`; when adding or renaming commands, update both wire models and the protocol tests/docs in the same change.

package/ios-runner/RUNNER_PROTOCOL.md

@@ -0,0 +1,73 @@
+# iOS Runner Protocol
+
+The Apple runner speaks a small internal HTTP+JSON protocol between the TypeScript daemon and the XCUITest host. This protocol is a maintainer document, not part of the public user docs, but it should stay explicit so the TypeScript and Swift sides do not drift.
+
+## Transport
+
+- Endpoint: `POST /command`
+- Content type: `application/json`
+- Request body: one JSON command object
+- Response body: one JSON envelope
+
+The daemon probes `http://127.0.0.1:<port>/command` for simulator and desktop flows, and can use a tunneled device address for physical iOS/tvOS devices before falling back to localhost.
+
+## Request Shape
+
+Every request includes a `command` field. Additional fields depend on the command family.
+
+Examples:
+
+```json
+{ "command": "tap", "x": 120, "y": 240 }
+```
+
+```json
+{
+  "command": "snapshot",
+  "interactiveOnly": true,
+  "compact": true,
+  "depth": 2,
+  "scope": "app",
+  "raw": false
+}
+```
+
+```json
+{ "command": "recordStart", "outPath": "/tmp/demo.mp4", "fps": 30 }
+```
+
+The current command names are defined in:
+
+- [`../src/platforms/ios/runner-client.ts`](../src/platforms/ios/runner-client.ts)
+- [`AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift`](AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Models.swift)
+
+## Response Shape
+
+Successful and failed responses use the same top-level envelope:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "message": "ok"
+  }
+}
+```
+
+```json
+{
+  "ok": false,
+  "error": {
+    "code": "UNSUPPORTED_OPERATION",
+    "message": "Unable to dismiss the iOS keyboard without a native dismiss gesture or control"
+  }
+}
+```
+
+`data` is command-specific. Common fields include snapshot nodes, text lookup results, gesture timing, visibility metadata, and screenshot or recording output details.
+
+## Maintenance Rules
+
+- Treat the TypeScript and Swift wire models as a single contract.
+- When adding, removing, or renaming a command, update the protocol fixtures/tests in the same change.
+- Keep this file focused on the actual wire shape rather than implementation details of command execution.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",
@@ -31,13 +31,16 @@
     "build:all": "pnpm build:node && pnpm build:xcuitest",
     "ad": "node bin/agent-device.mjs",
     "format": "prettier --write src test skills",
-    "prepublishOnly": "pnpm build:all",
     "prepack": "pnpm build:all",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "node --test",
-    "test:unit": "node --test src/__tests__/*.test.ts src/core/__tests__/*.test.ts src/daemon/__tests__/*.test.ts src/daemon/handlers/__tests__/*.test.ts src/platforms/**/__tests__/*.test.ts src/utils/**/__tests__/*.test.ts",
+    "test": "vitest run",
+    "test:unit": "vitest run",
     "test:smoke": "node --test test/integration/smoke-*.test.ts",
-    "test:integration": "node --test test/integration/*.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",
+    "test:replay:ios-device": "node --experimental-strip-types src/bin.ts test test/integration/replays/ios/device",
+    "test:replay:android": "node --experimental-strip-types src/bin.ts test test/integration/replays/android",
+    "test:replay:macos": "node --experimental-strip-types src/bin.ts test test/integration/replays/macos"
   },
   "files": [
     "bin",
@@ -73,10 +76,12 @@
     "pngjs": "^7.0.0"
   },
   "devDependencies": {
+    "@microsoft/api-extractor": "^7.52.10",
     "@rslib/core": "0.19.4",
     "@types/node": "^22.0.0",
     "@types/pngjs": "^6.0.5",
     "prettier": "^3.3.3",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
   }
 }

package/skills/agent-device/SKILL.md

@@ -5,35 +5,61 @@ description: Automates interactions for Apple-platform apps (iOS, tvOS, macOS) a
 
 # agent-device
 
-Use this skill as a router.
+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.
+
+## Default operating rules
+
+- Start conservative. Prefer read-only inspection before mutating the UI.
+- 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.
+- 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.
+- 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.
+- 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`.
+
+## Default flow
+
+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`.
 
 ## QA modes
 
 - 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).
 
-## Mental model
+## Required references
 
-- First choose the correct target and open the app or session you want to work on.
-- Then inspect the current UI with `snapshot -i` and pick targets from the actual UI state.
-- Act with `press`, `fill`, `get`, `is`, `wait`, or `find`.
-- Re-snapshot after meaningful UI changes instead of reusing stale refs.
-- End by capturing proof if needed, then `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 `get`, `is`, or `find` when they can answer the question without changing UI state.
 - Use `fill` to replace text.
 - Use `type` to append text.
+- 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.
+- 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.
-- Keep the default loop short: `open` -> explore/act -> optional debug or verify -> `close`.
 
-## Choose a reference
+## Additional references
 
-- Pick target device, install, open, or manage sessions: [references/bootstrap-install.md](references/bootstrap-install.md)
-- Need to discover UI, pick refs, wait, query, or interact: [references/exploration.md](references/exploration.md)
 - 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 to connect to a remote `agent-device` daemon over HTTP or use tenant leases: [references/remote-tenancy.md](references/remote-tenancy.md)
+- Need remote HTTP transport, `--remote-config` launches, or tenant leases on a remote macOS host: [references/remote-tenancy.md](references/remote-tenancy.md)

package/skills/agent-device/references/bootstrap-install.md

@@ -2,37 +2,79 @@
 
 ## When to open this file
 
-Open this file when you still need to choose the right target, start the right session, install or relaunch the app, or pin automation to one device before interacting.
+Open this file when you still need to choose the right target, start the right session, install or relaunch the app, or pin automation to one device before interacting. This is the deterministic setup layer for sandbox, cloud, or other environments where install paths, device state, or app readiness may be uncertain.
 
-## Main commands to reach for first
+## Open-first path
 
 - `devices`
+- `apps`
 - `ensure-simulator`
 - `open`
-- `install` or `reinstall`
-- `close`
 - `session list`
 
+## Install path
+
+- `install` or `reinstall`
+
 ## Most common mistake to avoid
 
 Do not start acting before you have pinned the correct target and opened an `app` session. In mixed-device environments, always pass `--device`, `--udid`, or `--serial`.
 
-## Canonical loop
+## Deterministic setup rule
+
+If there is no simulator, no app install, no open app session, or any uncertainty about where the app should come from, stay in this file and use deterministic setup commands or bootstrap scripts first. Do not improvise install paths or app-launch flows while exploring.
+
+After setup is confirmed or completed, move to `exploration.md` before doing UI inspection or interaction.
+
+## Open-first rule
+
+- If the user asks to test an app and does not provide an install artifact or explicit install instruction, try `open <app>` first.
+- If `open <app>` fails, run `agent-device apps` and retry with a discovered app name before considering install steps.
+- Do not install or reinstall on the first attempt unless the user explicitly asks for installation or provides a concrete artifact path or URL.
+- When installation is required from a known location, prefer a checked-in shell script or other deterministic bootstrap command over ad hoc path guessing.
+
+- If `open <app>` fails, or you are not sure which app name is available on the target, run `agent-device apps` first and choose from the discovered app list instead of guessing.
+- Use `apps --platform <platform>` together with `--device`, `--udid`, or `--serial` when target selection matters.
+- Once you have the correct app name, retry `open` with that exact discovered value.
+
+## Common starting points
+
+These are examples, not required exact sequences. Use the smallest setup flow that matches the task.
+
+### Boot a simulator and open an app
 
 ```bash
 agent-device ensure-simulator --platform ios --device "iPhone 17 Pro" --boot
 agent-device open MyApp --platform ios --device "iPhone 17 Pro" --relaunch
-agent-device snapshot -i
-agent-device close
 ```
 
+### Install an app artifact
+
+```bash
+agent-device install com.example.app ./build/app.apk --platform android --serial emulator-5554
+```
+
+```bash
+agent-device install com.example.app ./build/MyApp.app --platform ios --device "iPhone 17 Pro"
+```
+
+## Install guidance
+
+- Use `install <app> <path>` when the app may already be installed and you do not need a fresh-state reset.
+- Use `reinstall <app> <path>` when you explicitly need uninstall plus install as one deterministic step.
+- Keep install and open as separate phases. Do not turn them into one default command flow.
+- Supported binary formats:
+  - Android: `.apk` and `.aab`
+  - iOS: `.app` and `.ipa`
+- For iOS `.ipa` files, `<app>` is used as the bundle id or bundle name hint when the archive contains multiple app bundles.
+- After install or reinstall, later use `open <app>` with the exact discovered or known package/bundle identifier, not the artifact path.
+
 ## Choose the right starting point
 
 - iOS local QA: prefer simulators unless the task explicitly requires physical hardware.
 - iOS in mixed simulator and device environments: run `ensure-simulator` first, then keep using `--device` or `--udid`.
 - TV targets: use `--target tv` together with `--platform` when the task is for tvOS or Android TV rather than phone or tablet surfaces.
 - Android binary flow: use `install` or `reinstall` for `.apk` or `.aab`, then open by installed package name.
-- Android React Native plus Metro flow: `reinstall <app> <apk>` first, then `open <package> --remote-config <path> --relaunch`.
 - macOS desktop app flow: use `open <app> --platform macos`. Only load [macos-desktop.md](macos-desktop.md) if a desktop surface or macOS-specific behavior matters.
 
 TV example:
@@ -95,8 +137,6 @@ export AGENT_DEVICE_PLATFORM=ios
 export AGENT_DEVICE_SESSION_LOCK=strip
 
 agent-device open MyApp --relaunch
-agent-device snapshot -i
-agent-device close
 ```
 
 - `AGENT_DEVICE_SESSION` plus `AGENT_DEVICE_PLATFORM` provides the default binding.
@@ -111,10 +151,7 @@ Android emulator variant:
 export AGENT_DEVICE_SESSION=qa-android
 export AGENT_DEVICE_PLATFORM=android
 
-agent-device reinstall MyApp /path/to/app-debug.apk --serial emulator-5554
 agent-device --session-lock reject open com.example.myapp --relaunch
-agent-device snapshot -i
-agent-device close --shutdown
 ```
 
 ## Scoped discovery
@@ -151,11 +188,14 @@ agent-device replay -u ./session.ad --session auth
 - Once the correct target and session are pinned, move to [exploration.md](exploration.md).
 - If opening, startup, permissions, or logs become the blocker, switch to [debugging.md](debugging.md).
 
-## Install and open examples
+## Install examples
 
 ```bash
 agent-device reinstall MyApp /path/to/app-debug.apk --platform android --serial emulator-5554
-agent-device open com.example.myapp --remote-config ./agent-device.remote.json --relaunch
+```
+
+```bash
+agent-device install com.example.app ./build/MyApp.ipa --platform ios --device "iPhone 17 Pro"
 ```
 
 Do not use `open <apk|aab> --relaunch` on Android.