agent-device 0.6.2 → 0.7.0

package/ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj/project.pbxproj

@@ -258,7 +258,7 @@
 				MTL_ENABLE_DEBUG_INFO = INCLUDE_SOURCE;
 				MTL_FAST_MATH = YES;
 				ONLY_ACTIVE_ARCH = YES;
-				SDKROOT = iphoneos;
+				SDKROOT = auto;
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "DEBUG $(inherited)";
 				SWIFT_OPTIMIZATION_LEVEL = "-Onone";
 			};
@@ -315,7 +315,7 @@
 				LOCALIZATION_PREFERS_STRING_CATALOGS = YES;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				MTL_FAST_MATH = YES;
-				SDKROOT = iphoneos;
+				SDKROOT = auto;
 				SWIFT_COMPILATION_MODE = wholemodule;
 				VALIDATE_PRODUCT = YES;
 			};
@@ -350,7 +350,9 @@
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
 				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = "1,2";
+				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator appletvos appletvsimulator";
+				TARGETED_DEVICE_FAMILY = "1,2,3";
+				TVOS_DEPLOYMENT_TARGET = 15.6;
 			};
 			name = Debug;
 		};
@@ -383,7 +385,9 @@
 				SWIFT_EMIT_LOC_STRINGS = YES;
 				SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
 				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = "1,2";
+				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator appletvos appletvsimulator";
+				TARGETED_DEVICE_FAMILY = "1,2,3";
+				TVOS_DEPLOYMENT_TARGET = 15.6;
 			};
 			name = Release;
 		};
@@ -404,7 +408,9 @@
 				SWIFT_OBJC_BRIDGING_HEADER = "AgentDeviceRunnerUITests/AgentDeviceRunnerUITests-Bridging-Header.h";
 				SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
 				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = "1,2";
+				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator appletvos appletvsimulator";
+				TARGETED_DEVICE_FAMILY = "1,2,3";
+				TVOS_DEPLOYMENT_TARGET = 15.6;
 				TEST_TARGET_NAME = AgentDeviceRunner;
 			};
 			name = Debug;
@@ -426,7 +432,9 @@
 				SWIFT_OBJC_BRIDGING_HEADER = "AgentDeviceRunnerUITests/AgentDeviceRunnerUITests-Bridging-Header.h";
 				SWIFT_UPCOMING_FEATURE_MEMBER_IMPORT_VISIBILITY = YES;
 				SWIFT_VERSION = 5.0;
-				TARGETED_DEVICE_FAMILY = "1,2";
+				SUPPORTED_PLATFORMS = "iphoneos iphonesimulator appletvos appletvsimulator";
+				TARGETED_DEVICE_FAMILY = "1,2,3";
+				TVOS_DEPLOYMENT_TARGET = 15.6;
 				TEST_TARGET_NAME = AgentDeviceRunner;
 			};
 			name = Release;

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

@@ -40,6 +40,7 @@ final class RunnerTests: XCTestCase {
   private let postSnapshotInteractionDelay: TimeInterval = 0.2
   private let firstInteractionAfterActivateDelay: TimeInterval = 0.25
   private let scrollInteractionIdleTimeoutDefault: TimeInterval = 1.0
+  private let tvRemoteDoublePressDelayDefault: TimeInterval = 0.0
   private let minRecordingFps = 1
   private let maxRecordingFps = 120
   private var needsPostSnapshotInteractionDelay = false
@@ -783,6 +784,28 @@ final class RunnerTests: XCTestCase {
       }
       needsPostSnapshotInteractionDelay = true
       return Response(ok: true, data: snapshotFast(app: activeApp, options: options))
+    case .screenshot:
+      // If a target app bundle ID is provided, activate it first so the screenshot
+      // captures the target app rather than the AgentDeviceRunner itself.
+      if let bundleId = command.appBundleId, !bundleId.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+        let targetApp = XCUIApplication(bundleIdentifier: bundleId)
+        targetApp.activate()
+        // Brief wait for the app transition animation to complete
+        Thread.sleep(forTimeInterval: 0.5)
+      }
+      let screenshot = XCUIScreen.main.screenshot()
+      guard let pngData = screenshot.image.pngData() else {
+        return Response(ok: false, error: ErrorPayload(message: "Failed to encode screenshot as PNG"))
+      }
+      let fileName = "screenshot-\(Int(Date().timeIntervalSince1970 * 1000)).png"
+      let filePath = (NSTemporaryDirectory() as NSString).appendingPathComponent(fileName)
+      do {
+        try pngData.write(to: URL(fileURLWithPath: filePath))
+      } catch {
+        return Response(ok: false, error: ErrorPayload(message: "Failed to write screenshot: \(error.localizedDescription)"))
+      }
+      // Return path relative to app container root (tmp/ maps to NSTemporaryDirectory)
+      return Response(ok: true, data: DataPayload(message: "tmp/\(fileName)"))
     case .back:
       if tapNavigationBack(app: activeApp) {
         return Response(ok: true, data: DataPayload(message: "back"))
@@ -790,7 +813,7 @@ final class RunnerTests: XCTestCase {
       performBackGesture(app: activeApp)
       return Response(ok: true, data: DataPayload(message: "back"))
     case .home:
-      XCUIDevice.shared.press(.home)
+      pressHomeButton()
       return Response(ok: true, data: DataPayload(message: "home"))
     case .appSwitcher:
       performAppSwitcherGesture(app: activeApp)
@@ -934,7 +957,7 @@ final class RunnerTests: XCTestCase {
 
   private func isReadOnlyCommand(_ command: Command) -> Bool {
     switch command.command {
-    case .findText, .snapshot:
+    case .findText, .snapshot, .screenshot:
       return true
     case .alert:
       let action = (command.action ?? "get").lowercased()
@@ -961,7 +984,7 @@ final class RunnerTests: XCTestCase {
 
   private func isRunnerLifecycleCommand(_ command: CommandType) -> Bool {
     switch command {
-    case .shutdown, .recordStop:
+    case .shutdown, .recordStop, .screenshot:
       return true
     default:
       return false
@@ -990,10 +1013,13 @@ final class RunnerTests: XCTestCase {
       back.tap()
       return true
     }
-    return false
+    return pressTvRemoteMenuIfAvailable()
   }
 
   private func performBackGesture(app: XCUIApplication) {
+    if pressTvRemoteMenuIfAvailable() {
+      return
+    }
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.05, dy: 0.5))
     let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5))
@@ -1001,12 +1027,64 @@ final class RunnerTests: XCTestCase {
   }
 
   private func performAppSwitcherGesture(app: XCUIApplication) {
+    if performTvRemoteAppSwitcherIfAvailable() {
+      return
+    }
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.99))
     let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.7))
     start.press(forDuration: 0.6, thenDragTo: end)
   }
 
+  private func pressHomeButton() {
+    if pressTvRemoteHomeIfAvailable() {
+      return
+    }
+    XCUIDevice.shared.press(.home)
+  }
+
+  private func pressTvRemoteMenuIfAvailable() -> Bool {
+#if os(tvOS)
+    XCUIRemote.shared.press(.menu)
+    return true
+#else
+    return false
+#endif
+  }
+
+  private func pressTvRemoteHomeIfAvailable() -> Bool {
+#if os(tvOS)
+    XCUIRemote.shared.press(.home)
+    return true
+#else
+    return false
+#endif
+  }
+
+  private func performTvRemoteAppSwitcherIfAvailable() -> Bool {
+#if os(tvOS)
+    XCUIRemote.shared.press(.home)
+    sleepFor(resolveTvRemoteDoublePressDelay())
+    XCUIRemote.shared.press(.home)
+    return true
+#else
+    return false
+#endif
+  }
+
+  private func resolveTvRemoteDoublePressDelay() -> TimeInterval {
+    guard
+      let raw = ProcessInfo.processInfo.environment["AGENT_DEVICE_TV_REMOTE_DOUBLE_PRESS_DELAY_MS"],
+      !raw.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+    else {
+      return tvRemoteDoublePressDelayDefault
+    }
+    guard let parsedMs = Double(raw), parsedMs >= 0 else {
+      return tvRemoteDoublePressDelayDefault
+    }
+    return min(parsedMs, 1000) / 1000.0
+  }
+
   private func findElement(app: XCUIApplication, text: String) -> XCUIElement? {
     let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR identifier CONTAINS[c] %@ OR value CONTAINS[c] %@", text, text, text)
     let element = app.descendants(matching: .any).matching(predicate).firstMatch
@@ -1109,6 +1187,9 @@ final class RunnerTests: XCTestCase {
   }
 
   private func swipe(app: XCUIApplication, direction: SwipeDirection) {
+    if performTvRemoteSwipeIfAvailable(direction: direction) {
+      return
+    }
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
     let start = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.2))
     let end = target.coordinate(withNormalizedOffset: CGVector(dx: 0.5, dy: 0.8))
@@ -1127,6 +1208,24 @@ final class RunnerTests: XCTestCase {
     }
   }
 
+  private func performTvRemoteSwipeIfAvailable(direction: SwipeDirection) -> Bool {
+#if os(tvOS)
+    switch direction {
+    case .up:
+      XCUIRemote.shared.press(.up)
+    case .down:
+      XCUIRemote.shared.press(.down)
+    case .left:
+      XCUIRemote.shared.press(.left)
+    case .right:
+      XCUIRemote.shared.press(.right)
+    }
+    return true
+#else
+    return false
+#endif
+  }
+
   private func pinch(app: XCUIApplication, scale: Double, x: Double?, y: Double?) {
     let target = app.windows.firstMatch.exists ? app.windows.firstMatch : app
 
@@ -1741,6 +1840,7 @@ enum CommandType: String, Codable {
   case swipe
   case findText
   case snapshot
+  case screenshot
   case back
   case home
   case appSwitcher

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-device",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Unified control plane for physical and virtual devices via an agent-driven CLI.",
   "license": "MIT",
   "author": "Callstack",
@@ -16,7 +16,9 @@
     "build": "rslib build",
     "clean:daemon": "rm -f ~/.agent-device/daemon.json && rm -f ~/.agent-device/daemon.lock",
     "build:node": "pnpm build && pnpm clean:daemon",
-    "build:xcuitest": "rm -rf ~/.agent-device/ios-runner/derived/device && xcodebuild build-for-testing -project ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj -scheme AgentDeviceRunner -destination \"generic/platform=iOS Simulator\" -derivedDataPath ~/.agent-device/ios-runner/derived",
+    "build:xcuitest": "pnpm build:xcuitest:ios",
+    "build:xcuitest:ios": "rm -rf ~/.agent-device/ios-runner/derived/device && xcodebuild build-for-testing -project ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj -scheme AgentDeviceRunner -destination \"generic/platform=iOS Simulator\" -derivedDataPath ~/.agent-device/ios-runner/derived",
+    "build:xcuitest:tvos": "rm -rf ~/.agent-device/ios-runner/derived/tvos && xcodebuild build-for-testing -project ios-runner/AgentDeviceRunner/AgentDeviceRunner.xcodeproj -scheme AgentDeviceRunner -destination \"generic/platform=tvOS Simulator\" -derivedDataPath ~/.agent-device/ios-runner/derived/tvos",
     "build:all": "pnpm build:node && pnpm build:xcuitest",
     "ad": "node bin/agent-device.mjs",
     "format": "prettier --write .",

package/skills/agent-device/SKILL.md

@@ -6,6 +6,7 @@ description: Automates interactions for iOS simulators/devices and Android emula
 # Mobile Automation with agent-device
 
 For exploration, use snapshot refs. For deterministic replay, use selectors.
+For structured exploratory QA bug hunts and reporting, use [../dogfood/SKILL.md](../dogfood/SKILL.md).
 
 ## Start Here (Read This First)
 
@@ -22,7 +23,7 @@ Use this skill as a router, not a full manual.
 
 - No target context yet: `devices` -> pick target -> `open`.
 - Normal UI task: `open` -> `snapshot -i` -> `press/fill` -> `diff snapshot -i` -> `close`
-- Debug/crash: `open <app>` -> `logs clear --restart` -> reproduce -> `logs path` -> targeted `grep`
+- Debug/crash: `open <app>` -> `logs clear --restart` -> reproduce -> `network dump` -> `logs path` -> targeted `grep`
 - Replay drift: `replay -u <path>` -> verify updated selectors
 
 ## Canonical Flows
@@ -43,6 +44,7 @@ agent-device close
 ```bash
 agent-device open MyApp --platform ios
 agent-device logs clear --restart
+agent-device network dump 25
 agent-device logs path
 ```
 
@@ -68,6 +70,14 @@ agent-device session list
 ```
 
 Use `boot` only as fallback when `open` cannot find/connect to a ready target.
+Use `--target mobile|tv` with `--platform` (required) to pick phone/tablet vs TV targets (AndroidTV/tvOS).
+
+TV quick reference:
+- AndroidTV: `open`/`apps` use TV launcher discovery automatically.
+- TV target selection works on emulators/simulators and connected physical devices (AndroidTV + AppleTV).
+- tvOS: runner-driven interactions and snapshots are supported (`snapshot`, `wait`, `press`, `fill`, `get`, `scroll`, `back`, `home`, `app-switcher`, `record` and related selector flows).
+- tvOS `back`/`home`/`app-switcher` map to Siri Remote actions (`menu`, `home`, double-home) in the runner.
+- tvOS follows iOS simulator-only command semantics for helpers like `pinch`, `settings`, and `push`.
 
 ### Snapshot and targeting
 
@@ -86,6 +96,11 @@ agent-device is visible 'id="anchor"'
 
 ```bash
 agent-device appstate
+agent-device clipboard read
+agent-device clipboard write "token"
+agent-device perf --json
+agent-device network dump [limit] [summary|headers|body|all]
+agent-device push <bundle|package> <payload.json|inline-json>
 agent-device get text @e1
 agent-device screenshot out.png
 agent-device settings permission grant notifications
@@ -100,6 +115,11 @@ agent-device trace stop ./trace.log
 agent-device batch --steps-file /tmp/batch-steps.json --json
 ```
 
+### Performance Check
+
+- Use `agent-device perf --json` (or `metrics --json`) after `open`.
+- For detailed metric semantics, caveats, and interpretation guidance, see [references/perf-metrics.md](references/perf-metrics.md).
+
 ## Guardrails (High Value Only)
 
 - Re-snapshot after UI mutations (navigation/modal/list changes).
@@ -107,7 +127,13 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - Use refs for discovery, selectors for replay/assertions.
 - Use `fill` for clear-then-type semantics; use `type` for focused append typing.
 - iOS `appstate` is session-scoped; Android `appstate` is live foreground state.
-- iOS settings helpers are simulator-only; use faceid `match|nonmatch|enroll|unenroll`.
+- Clipboard helpers: `clipboard read` / `clipboard write <text>` are supported on Android and iOS simulators; iOS physical devices are not supported yet.
+- `network dump` is best-effort and parses HTTP(s) entries from the session app log file.
+- iOS settings helpers are simulator-only; use `appearance light|dark|toggle` and faceid `match|nonmatch|enroll|unenroll`.
+- For AndroidTV/tvOS selection, always pair `--target` with `--platform` (`ios`, `android`, or `apple` alias); target-only selection is invalid.
+- `push` simulates notification delivery:
+  - iOS simulator uses APNs-style payload JSON.
+  - Android uses broadcast action + typed extras (string/boolean/number).
 - Permission settings are app-scoped and require an active session app:
   `settings permission <grant|deny|reset> <camera|microphone|photos|contacts|notifications> [full|limited]`
 - `full|limited` mode applies only to iOS `photos`; other targets reject mode.
@@ -138,3 +164,4 @@ agent-device batch --steps-file /tmp/batch-steps.json --json
 - [references/video-recording.md](references/video-recording.md)
 - [references/coordinate-system.md](references/coordinate-system.md)
 - [references/batching.md](references/batching.md)
+- [references/perf-metrics.md](references/perf-metrics.md)

package/skills/agent-device/references/logs-and-debug.md

@@ -1,6 +1,7 @@
 # Logs (Token-Efficient Debugging)
 
 Logging is off by default in normal flows. Enable it on demand for debugging windows. App output is written to a session-scoped file so agents can grep it instead of loading full logs into context.
+`network dump` parses recent HTTP(s) entries from this same session app log file.
 
 ## Data Handling
 
@@ -23,6 +24,7 @@ Logging is off by default in normal flows. Enable it on demand for debugging win
 ```bash
 agent-device open MyApp --platform ios      # or --platform android
 agent-device logs clear --restart    # Preferred: stop stream, clear logs, and start streaming again
+agent-device network dump 25         # Parse latest HTTP(s) requests (method/url/status) from app.log
 agent-device logs path               # Print path, e.g. ~/.agent-device/sessions/default/app.log
 agent-device logs doctor             # Check tool/runtime readiness for current session/device
 agent-device logs mark "before tap"  # Insert a timeline marker into app.log
@@ -41,10 +43,13 @@ Precondition: `logs clear --restart` requires an active app session (`open <app>
 - `logs clear --restart`: convenience reset for repro loops (stop stream, clear files, restart stream).
 - `logs doctor`: reports backend/tool checks and readiness notes for troubleshooting.
 - `logs mark`: writes a timestamped marker line to the session log.
+- `network dump [limit] [summary|headers|body|all]`: parses recent HTTP(s) lines from the session app log and returns request summaries.
+- `network log ...`: alias for `network dump`.
 
 ## Behavior and Limits
 
 - `logs start` appends to `app.log` and rotates to `app.log.1` when `app.log` exceeds 5 MB.
+- `network dump` scans the last 4000 app-log lines, returns up to 200 entries, and truncates payload/header fields at 2048 characters.
 - Android log streaming automatically rebinds to the app PID after process restarts.
 - iOS log capture relies on Unified Logging signals (for example `os_log`); plain stdout/stderr output may be limited depending on app/runtime.
 - Retention knobs:

package/skills/agent-device/references/perf-metrics.md

@@ -0,0 +1,53 @@
+# Performance Metrics (`perf` / `metrics`)
+
+Use this reference when you need to measure launch performance in agent workflows.
+
+## Quick flow
+
+```bash
+agent-device open Settings --platform ios
+agent-device perf --json
+```
+
+Alias:
+
+```bash
+agent-device metrics --json
+```
+
+## What is measured today
+
+- Session-scoped `startup` timing only.
+- Sampling method: `open-command-roundtrip`.
+- Unit: milliseconds (`ms`).
+- Source: elapsed wall-clock time around each session `open` command dispatch for the active app target.
+
+## Output fields to use
+
+- `metrics.startup.lastDurationMs`: most recent startup sample.
+- `metrics.startup.lastMeasuredAt`: ISO timestamp of most recent sample.
+- `metrics.startup.sampleCount`: number of retained samples.
+- `metrics.startup.samples[]`: recent startup history for the current session.
+- `sampling.startup.method`: current sampling method identifier.
+
+## Platform support (current)
+
+- iOS simulator: supported for startup sampling.
+- iOS physical device: supported for startup sampling.
+- Android emulator/device: supported for startup sampling.
+- `fps`, `memory`, and `cpu`: currently placeholders (`available: false`).
+
+## Interpretation guidance
+
+- Treat startup values as command round-trip timing, not true app first-frame or first-interactive telemetry.
+- Compare like-for-like runs:
+  - same device target
+  - same app build
+  - same workflow/session steps
+- Use multiple runs and compare trend/median, not one-off samples.
+
+## Common pitfalls
+
+- Running `perf` before any `open` in the session yields no startup sample yet.
+- Comparing values across different devices/runtimes introduces large noise.
+- Interpreting current `startup` as CPU/FPS/memory would be incorrect.

package/skills/dogfood/SKILL.md

@@ -0,0 +1,183 @@
+---
+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.
+allowed-tools: Bash(agent-device:*), Bash(npx agent-device:*)
+---
+
+# Dogfood (agent-device)
+
+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:
+
+```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
+```
+
+For OTP/email codes: ask the user, wait for input, then continue.
+
+### 3. Orient
+
+Capture initial evidence and navigation anchors:
+
+```bash
+agent-device --session {SESSION} screenshot {OUTPUT_DIR}/screenshots/initial.png
+agent-device --session {SESSION} snapshot -i
+```
+
+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.
+- 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
+
+| Template | Purpose |
+|----------|---------|
+| [templates/dogfood-report-template.md](templates/dogfood-report-template.md) | Copy into output directory as the report file |