agent-device 0.13.3 → 0.14.1

package/skills/agent-device/references/verification.md

@@ -1,134 +0,0 @@
-# Verification
-
-## When to open this file
-
-Open this file when the task needs evidence, regression checks, replay maintenance, or session performance measurements after the main interaction flow is already working.
-
-## Main commands to reach for first
-
-- `screenshot`
-- `diff snapshot`
-- `diff screenshot`
-- `record`
-- `replay -u`
-- `perf`
-
-## Most common mistake to avoid
-
-Do not use verification tools as the first exploration step. First get the app into the correct state with the normal interaction flow, then capture proof or maintain replay assets.
-
-## Canonical loop
-
-```bash
-agent-device open Settings --platform ios
-# after using exploration to reach the state you want to verify
-agent-device snapshot
-agent-device screenshot /tmp/settings-proof.png --overlay-refs
-agent-device close
-```
-
-## Structural verification with diff snapshot
-
-Use `diff snapshot` when you need a compact view of how the UI changed between nearby states.
-
-```bash
-agent-device snapshot -i
-agent-device press @e5
-agent-device diff snapshot -i
-```
-
-- Initialize the baseline at a stable point.
-- Perform the mutation.
-- Run `diff snapshot` to confirm the expected structural change.
-- Re-run full `snapshot` only when you need fresh refs.
-
-## Screenshot artifacts
-
-Use `screenshot` when the proof needs a rendered image instead of a structural tree.
-
-- Add `--max-size 1024` when a full-resolution screenshot is too large for an agent, model, or chat attachment.
-- Add `--overlay-refs` when you want the saved PNG to show fresh `@eN` refs burned into the screenshot.
-- Combine them as `screenshot /tmp/proof.png --max-size 1024 --overlay-refs` when you need a smaller visual proof that still includes tappable refs.
-- Avoid very small `--max-size` values when text, icons, or labels need to remain readable.
-
-## Visual regression with diff screenshot
-
-Use `diff screenshot` when comparing the current rendered screen against a saved visual baseline.
-
-```bash
-agent-device diff screenshot --baseline ./baseline.png --out /tmp/diff.png
-agent-device diff screenshot --baseline ./baseline.png ./current.png --out /tmp/diff.png
-agent-device diff screenshot --baseline ./baseline.png --out /tmp/diff.png --overlay-refs
-```
-
-- Text output includes ranked changed regions with screen-space rectangles, shape, size, density, average color, and luminance. JSON also includes normalized bounds.
-- The diff PNG uses a light grayscale current-screen context with changed pixels tinted red and changed regions outlined.
-- When a current image path is provided, `diff screenshot` compares the two saved files instead of capturing from the live device or requiring an active session.
-- Install `tesseract` when you want `diff screenshot` to add best-effort OCR text deltas, movement clusters, and bbox size-change hints. OCR improves the text/JSON descriptions only; it does not change the pixel comparison or the diff PNG.
-- When OCR is available, `diff screenshot` also reports best-effort non-text visual deltas by masking OCR text boxes out of the pixel diff and clustering the remaining residuals. Treat these as hints for icons, controls, and separators, not semantic icon recognition.
-- Add `--overlay-refs` to `diff screenshot` when you also want a separate current-screen overlay guide for a live capture. The raw screenshot is still used for pixel comparison; the overlay guide is only context for non-text controls, icons, and tappable regions. When overlay refs intersect changed regions, the output lists the best current-screen ref matches under the affected region. Saved-image comparisons do not have live accessibility refs, so omit `--overlay-refs` when passing a current image path.
-
-## Session recording
-
-Use `record` for debugging, documentation, or shareable verification artifacts.
-
-```bash
-agent-device record start ./recordings/ios.mov
-agent-device open App
-agent-device snapshot -i
-agent-device press @e3
-agent-device close
-agent-device record stop
-```
-
-- `record` supports iOS simulators, iOS devices, and Android.
-- On iOS, recording is a wrapper around `simctl` for simulators and the corresponding device capture path for physical devices.
-- On Android, recording is a wrapper around `adb`.
-- Recording writes a video artifact and a gesture-telemetry sidecar JSON.
-- Use `record start <path> --quality 5` when a smaller video is easier to inspect or share. The scale is 5-10, where 10 is native resolution; omit it to preserve native/current resolution.
-- On macOS hosts, touch overlay burn-in is available for supported recordings.
-- On non-macOS hosts, recording still succeeds but the video stays raw and `record stop` can return an `overlayWarning`.
-- If the agent already knows the interaction sequence and wants a more lifelike, uninterrupted recording, drive the flow with `batch` while recording instead of replanning between each step.
-
-Example:
-
-```bash
-agent-device record start ./recordings/smoke.mov
-agent-device batch --session sim --platform ios --steps-file /tmp/smoke-steps.json --json
-agent-device record stop
-```
-
-- Use this only after exploration has stabilized the flow.
-- Keep the batch short and add `wait` or `is exists` guards after mutating steps so the recorded flow still tracks realistic UI timing.
-
-## Replay maintenance
-
-Use replay updates when selectors drift but the recorded scenario is still correct.
-
-```bash
-agent-device replay -u ./session.ad
-agent-device test ./smoke --platform android
-```
-
-- Prefer selector-based actions in recorded `.ad` replays.
-- Use `test` when you already have multiple `.ad` flows and need a quick regression pass after updating or recording them.
-- Keep the skill-level rule simple: use `replay -u` to maintain one script, use `test` to verify a folder or matcher of scripts.
-- Treat `test` as a human and CI-facing suite runner that an agent can invoke for verification, not as the main source of product documentation.
-- Failed runs keep suite artifacts under `.agent-device/test-artifacts` by default, which is usually enough for debugging without extra agent-side processing.
-- Use update mode for maintenance, not as a substitute for fixing a broken interaction strategy.
-
-## Performance checks
-
-Use `perf --json` or `metrics --json` when you need session performance data for the active session.
-
-```bash
-agent-device open Settings --platform ios
-agent-device perf --json
-```
-
-- `startup` is command round-trip timing around `open`.
-- It is not true first-frame or first-interactive telemetry.
-- Android app sessions also expose `memory` (`dumpsys meminfo`) and `cpu` (`dumpsys cpuinfo`) snapshots when the session has an app package context.
-- Apple app sessions on macOS, iOS simulators, and physical iOS devices also expose `memory` and `cpu` process snapshots when the session has an app bundle ID.
-- On physical iOS devices, sampling uses a short `xcrun xctrace` Activity Monitor capture, so keep the device unlocked, connected, and the app active in the foreground while sampling.
-- `fps` is still unavailable in this release.

package/skills/dogfood/references/issue-taxonomy.md

@@ -1,83 +0,0 @@
-# Issue Taxonomy (Mobile)
-
-Reference for categorizing issues found during mobile dogfooding.
-
-## Severity Levels
-
-| Severity     | Definition                                                                |
-| ------------ | ------------------------------------------------------------------------- |
-| **critical** | Blocks a core workflow, causes data loss, or crashes/freeze loops the app |
-| **high**     | Major feature broken or unusable, no practical workaround                 |
-| **medium**   | Feature works with notable friction or partial failure; workaround exists |
-| **low**      | Minor cosmetic or polish issue                                            |
-
-## Categories
-
-### Visual / UI
-
-- Layout broken, clipped, overlapped, or unreadable text
-- Safe-area/notch overlap issues
-- Incorrect dark/light appearance rendering
-- Missing assets/icons
-- Animation glitches or flicker
-
-### Functional
-
-- Buttons/controls do nothing or trigger wrong action
-- Flows fail (create/edit/delete/submit)
-- Navigation dead-ends or wrong destination
-- State loss after background/foreground transitions
-- Deep link opens wrong screen or fails
-
-### UX
-
-- Confusing hierarchy or navigation labels
-- Missing loading/progress feedback
-- Unclear error handling or no recovery affordance
-- Excessive steps for common tasks
-- Inconsistent behavior between similar screens
-
-### Content
-
-- Typos, incorrect copy, placeholder text
-- Wrong labels/help text
-- Truncated text with no affordance
-- Inconsistent terminology across screens
-
-### Performance
-
-- Slow startup or route transitions
-- Input lag or gesture jank
-- Scroll hitches/frame drops
-- Notable battery/thermal symptoms during basic usage
-
-### Diagnostics / Logs
-
-- Native crashes or repeated fatal exceptions
-- Repeated warnings correlated with broken behavior
-- Unhandled runtime errors visible during repro
-
-### Permissions / Platform
-
-- Permission prompt flow broken or loops forever
-- Denied permissions not handled gracefully
-- Platform-specific regressions (iOS-only or Android-only)
-- Background/foreground lifecycle regressions
-
-### Accessibility
-
-- Missing labels or incorrect accessibility names
-- Focus order/navigation issues for assistive tech
-- Low contrast or unreadable text scaling
-- Touch targets too small for reliable interaction
-
-## Exploration Checklist
-
-1. Visual scan: capture screenshot; verify layout/safe areas/text/icon rendering.
-2. Interactions: press controls, open menus/modals, validate expected response.
-3. Forms/input: test valid/invalid/empty/boundary input.
-4. Navigation: traverse all top-level sections and return paths.
-5. App states: loading/empty/error/offline/permission-denied/background-resume.
-6. Logs/diagnostics: inspect app logs when behavior is suspicious.
-7. Platform parity: verify critical flows on each requested platform.
-8. Accessibility basics: labels, touch target sizes, readability/contrast.

package/skills/dogfood/templates/dogfood-report-template.md

@@ -1,52 +0,0 @@
-# Dogfood Report: {APP_NAME}
-
-| Field          | Value          |
-| -------------- | -------------- |
-| **Date**       | {DATE}         |
-| **Platform**   | {PLATFORM}     |
-| **Target App** | {TARGET_APP}   |
-| **Session**    | {SESSION_NAME} |
-| **Scope**      | {SCOPE}        |
-
-## Summary
-
-| Severity  | Count |
-| --------- | ----- |
-| Critical  | 0     |
-| High      | 0     |
-| Medium    | 0     |
-| Low       | 0     |
-| **Total** | **0** |
-
-## Issues
-
-<!-- Copy this block for each issue found. Interactive issues need video + step screenshots. Static issues can be screenshot-only (Repro Video = N/A). -->
-
-### ISSUE-001: {Short title}
-
-| Field              | Value                                                                                        |
-| ------------------ | -------------------------------------------------------------------------------------------- |
-| **Severity**       | critical / high / medium / low                                                               |
-| **Category**       | visual / functional / ux / content / performance / diagnostics / permissions / accessibility |
-| **Screen / Route** | {screen where issue was found}                                                               |
-| **Repro Video**    | {path to video, or N/A for static issues}                                                    |
-
-**Description**
-
-{What is wrong, what was expected, and what actually happened.}
-
-**Repro Steps**
-
-1. Open {screen/entry point}
-   ![Step 1](screenshots/issue-001-step-1.png)
-
-2. {Action}
-   ![Step 2](screenshots/issue-001-step-2.png)
-
-3. {Action}
-   ![Step 3](screenshots/issue-001-step-3.png)
-
-4. **Observe:** {broken behavior}
-   ![Result](screenshots/issue-001-result.png)
-
----

package/skills/react-devtools/references/commands.md

@@ -1,91 +0,0 @@
-# React DevTools Commands
-
-All commands are run through `agent-device react-devtools`.
-
-## Connection
-
-```bash
-agent-device react-devtools start
-agent-device react-devtools stop
-agent-device react-devtools status
-agent-device react-devtools wait --connected --timeout 30
-agent-device react-devtools wait --component <ComponentName> --timeout 30
-```
-
-- `status` shows the daemon port, connected apps, component count, profiling state, uptime, and last connection event.
-- Most commands auto-start the daemon, but `start` is useful before launching or reloading the app.
-- React Native development builds connect to the daemon on port 8097. For Android emulators or physical devices, use `adb reverse tcp:8097 tcp:8097` if the app cannot reach the host. If the app also uses local Metro, set `adb reverse tcp:8081 tcp:8081`.
-
-## Validation Notes
-
-- When validating the same app across iOS and Android with explicit `--device`, `--udid`, or `--serial` selectors, prefer an isolated `--state-dir` over separate named sessions. A named `--session` enables bound-session lock behavior, so setup commands with explicit target selectors can be rejected.
-- Restart the React DevTools daemon between platforms so `status`, `get tree`, and profiling output belong to the currently launched app.
-- Verify the app is visibly loaded with `snapshot` before collecting React internals. Use `react-devtools` for component state and profiling, not for proving the device/app surface is open.
-
-## Component Inspection
-
-```bash
-agent-device react-devtools get tree --depth 3
-agent-device react-devtools get component @c5
-agent-device react-devtools find Button
-agent-device react-devtools find Button --exact
-agent-device react-devtools count
-agent-device react-devtools errors
-```
-
-- `get tree` prints a component hierarchy with labels like `@c1`, `@c2`.
-- Use `--depth` on large apps. Start at `--depth 3` or `--depth 4`.
-- `get component` accepts a label or numeric React fiber id and shows props, state, and hooks.
-- `find` searches by display name. Use `--exact` when fuzzy results are noisy.
-- `errors` lists components with React-tracked warnings or errors.
-
-## Profiling
-
-```bash
-agent-device react-devtools profile start "interaction name"
-agent-device react-devtools profile stop
-agent-device react-devtools profile slow --limit 5
-agent-device react-devtools profile rerenders --limit 5
-agent-device react-devtools profile report @c5
-agent-device react-devtools profile timeline --limit 20
-agent-device react-devtools profile commit 3
-agent-device react-devtools profile export profile.json
-agent-device react-devtools profile diff before.json after.json --limit 10
-```
-
-- `profile slow` ranks components by average render duration.
-- `profile rerenders` ranks components by render count.
-- `profile report @cN` shows render causes and changed props/state/hooks for one component.
-- `profile timeline` lists commits. Use `--limit` and `--offset` for long sessions.
-- `profile export` writes React DevTools Profiler JSON that can be diffed later.
-
-## Common Flows
-
-Inspect a component:
-
-```bash
-agent-device react-devtools status
-agent-device react-devtools get tree --depth 3
-agent-device react-devtools find SearchScreen
-agent-device react-devtools get component @c12
-```
-
-Profile a slow interaction:
-
-```bash
-agent-device react-devtools profile start "slow search"
-# Trigger the interaction with agent-device or ask the user to perform it.
-agent-device react-devtools profile stop
-agent-device react-devtools profile slow --limit 5
-agent-device react-devtools profile rerenders --limit 5
-```
-
-Verify a render fix:
-
-```bash
-agent-device react-devtools profile start "after fix"
-# Repeat the same interaction.
-agent-device react-devtools profile stop
-agent-device react-devtools profile slow --limit 5
-agent-device react-devtools profile rerenders --limit 5
-```

package/skills/react-devtools/references/profiling.md

@@ -1,74 +0,0 @@
-# React Native Profiling
-
-Use this workflow when the user reports slow interactions, excessive re-renders, unstable props, or unclear render causes.
-
-## Baseline
-
-```bash
-agent-device react-devtools status
-agent-device react-devtools count
-agent-device react-devtools get tree --depth 3
-```
-
-If the app is not connected, run:
-
-```bash
-agent-device react-devtools start
-agent-device react-devtools wait --connected
-```
-
-Then reload or relaunch the React Native app if needed.
-
-## Capture One Interaction
-
-```bash
-agent-device react-devtools profile start "short label"
-# Trigger exactly the interaction being investigated.
-agent-device react-devtools profile stop
-```
-
-Keep the profiling window narrow. Extra navigation, warm-up work, or unrelated gestures make the report harder to interpret.
-
-## Identify Suspects
-
-```bash
-agent-device react-devtools profile slow --limit 5
-agent-device react-devtools profile rerenders --limit 5
-```
-
-- A component with high average render time is a slow-render suspect.
-- A component with high render count is a re-render suspect.
-- A component can be both.
-
-## Drill In
-
-```bash
-agent-device react-devtools profile report @c12
-agent-device react-devtools get component @c12
-```
-
-Use `profile report` to identify render causes and changed keys. Use `get component` to inspect current props, state, and hooks.
-
-Common interpretations:
-
-| Signal                                     | Meaning                             | Typical follow-up                              |
-| ------------------------------------------ | ----------------------------------- | ---------------------------------------------- |
-| `props-changed` with function props        | Parent may pass unstable callbacks  | Check whether the parent can use `useCallback` |
-| `props-changed` with object or array props | Parent may pass unstable references | Check whether the parent can use `useMemo`     |
-| `parent-rendered` with many child renders  | Child has no bailout                | Check whether `React.memo` is appropriate      |
-| `state-changed`                            | Component state caused the render   | Check whether the state update is necessary    |
-| `hooks-changed`                            | Hook value or dependency changed    | Inspect hook values and dependencies           |
-
-## Verify
-
-After making a change, repeat the same interaction:
-
-```bash
-agent-device react-devtools profile start "after fix"
-# Repeat the same interaction.
-agent-device react-devtools profile stop
-agent-device react-devtools profile slow --limit 5
-agent-device react-devtools profile rerenders --limit 5
-```
-
-Compare render counts, average durations, changed keys, and commit counts against the baseline.