@swmansion/argent 0.32.1-next.0 → 0.32.1-next.2

package/skills/argent-settings-permissions/SKILL.md

@@ -3,129 +3,27 @@ name: argent-settings-permissions
 description: Grant, deny, or reset an app's runtime permissions (camera, microphone, photos, contacts, notifications, calendar, location, location-always, media-library, motion, reminders) on an iOS simulator or Android device using the argent `settings-permissions` tool - without navigating the system Settings UI. Use when the permission cannot be changed through the app itself - and only then, pre-authorize before the app asks, deny up front, re-enable a permission the user already denied, or reset so the prompt reappears. If the app can flip it - via an in-app toggle or the system permission dialog the app triggers - interact with the app instead.
 ---
 
-## What this tool is for
-
-`settings-permissions` edits the platform's permission store directly - the iOS simulator's TCC database, or Android's package-manager permission flags. It replaces the manual **Settings → Privacy** dance during test setup: pre-authorize a service so the app never has to ask, deny it up front to test the refusal path, or reset it so the first-run dialog appears again on the next launch.
-
-It is a **test-setup / out-of-band** tool, not a general permissions toggle. The default way to change a permission is still through the app - this tool is the exception for the cases the app can't reach.
+`settings-permissions` edits the platform's permission store directly (the iOS simulator's TCC database, Android's runtime permissions over adb). It is a **test-setup / out-of-band** tool, not a general permissions toggle: the default way to change a permission is still through the app. The tool's description covers the supported permissions per platform, the parameters, the result (`applied` / `skipped`) and the per-platform requirements.
 
 ## When to use it - and when NOT to
 
-Decide with this order. The first matching row wins.
+The first matching row wins.
 
-| Situation                                                                                                        | Do this                                                                                       | Why                                                                                                                                                                     |
-| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| The app has an **in-app control** for the permission (a toggle in its own settings screen)                       | **Tap it in the app** (`describe` → `gesture-tap`) - do NOT use this tool                     | It's real user behavior and exercises the flow you're testing. See `argent-device-interact`.                                                                            |
-| The app is **about to ask** (or just asked) and the system **permission dialog is on screen**                    | **Tap the dialog** (`Allow` / `Don't Allow` / `Allow While Using App`) - do NOT use this tool | The app-triggered prompt is the natural path; answering it is what a user does. `describe` exposes the dialog buttons; fall back to `screenshot` only if it doesn't.    |
-| You need the permission **already granted/denied before the app runs**, so no dialog interrupts the flow         | **Use this tool** (`grant` / `deny`) before `launch-app`                                      | The app can't pre-set its own permission; a real user would do it in Settings. This is the core use case. (`deny` suppresses the prompt on **iOS only** - see Gotchas.) |
-| The user **already denied** it and you need it **on** again                                                      | **Use this tool** (`grant`)                                                                   | iOS never re-shows a dialog once denied - the only in-device path is the Settings app. This tool is the shortcut.                                                       |
-| You need the **first-run dialog to appear again** (test the prompt itself, or reset dirty state)                 | **Use this tool** (`reset`)                                                                   | Returns the permission to "not yet asked" so the app prompts on next use.                                                                                               |
-| The permission is **not one this tool supports** on the target platform (see the support table)                  | **Do NOT use this tool**                                                                      | It will return an "unsupported" error. Use the app dialog if the app triggers one, or navigate the real Settings app.                                                   |
-| The setting isn't one of the **11 runtime permissions** below (e.g. Wi-Fi, cellular data, dark mode, VPN, Focus) | **Do NOT use this tool**                                                                      | Out of scope - drive the Settings app or the app's own UI instead.                                                                                                      |
+| Situation                                                                                                                             | Do this                                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| The app has an **in-app control** for the permission (a toggle in its own settings screen)                                            | **Tap it in the app** (`describe` → `gesture-tap`); it exercises the flow you're testing               |
+| The app asked and the **system permission dialog is on screen**                                                                       | **Tap the dialog** (`Allow` / `Don't Allow` / `Allow While Using App`); `describe` exposes its buttons |
+| The permission must be **granted/denied before the app runs**, so no dialog interrupts the flow                                       | **Use this tool** (`grant` / `deny`) before `launch-app`                                               |
+| The user **already denied** it and you need it **on** again                                                                           | **Use this tool** (`grant`): iOS never re-shows a dialog once denied                                   |
+| You need the **first-run dialog to appear again**                                                                                     | **Use this tool** (`reset`)                                                                            |
+| The permission is unsupported on the target platform, or it isn't one of the 11 runtime permissions (Wi-Fi, dark mode, VPN, Focus, …) | **Do NOT use this tool**: answer the app's dialog, or drive the Settings app or the app's own UI       |
 
 **Rule of thumb:** if a human tester could flip it _inside the app_, do that. Reach for `settings-permissions` only for a change a human would otherwise make in the **system Settings app**.
 
-## Supported permissions & platform coverage
-
-| `permission`      | iOS simulator (TCC service)                                                                                                                            | Android (`android.permission.*`)                                                                          |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `camera`          | `camera` - only if the target simulator's **runtime** models it (varies by simruntime, not by the installed Xcode; simulators have no camera hardware) | `CAMERA`                                                                                                  |
-| `microphone`      | `microphone`                                                                                                                                           | `RECORD_AUDIO`                                                                                            |
-| `photos`          | `photos` + `photos-add` (add-only access is a separate TCC service; `photos-add` is best-effort - check `applied` to see whether both changed)         | `READ_MEDIA_IMAGES` + `READ_MEDIA_VIDEO` + `READ_MEDIA_VISUAL_USER_SELECTED` + `READ_EXTERNAL_STORAGE`    |
-| `contacts`        | `contacts`                                                                                                                                             | `READ_CONTACTS` + `WRITE_CONTACTS`                                                                        |
-| `notifications`   | **unsupported** - no iOS equivalent; answer the app's dialog instead                                                                                   | `POST_NOTIFICATIONS`                                                                                      |
-| `calendar`        | `calendar`                                                                                                                                             | `READ_CALENDAR` + `WRITE_CALENDAR`                                                                        |
-| `location`        | `location`                                                                                                                                             | `ACCESS_FINE_LOCATION` + `ACCESS_COARSE_LOCATION`                                                         |
-| `location-always` | `location-always`                                                                                                                                      | `ACCESS_BACKGROUND_LOCATION` (a **grant** also adds fine + coarse - background alone can't read location) |
-| `media-library`   | `media-library`                                                                                                                                        | `READ_MEDIA_AUDIO` + `READ_EXTERNAL_STORAGE`                                                              |
-| `motion`          | `motion`                                                                                                                                               | `ACTIVITY_RECOGNITION`                                                                                    |
-| `reminders`       | `reminders`                                                                                                                                            | **unsupported** - no Android runtime permission                                                           |
-
-One abstract permission can map to several concrete Android permissions; which ones actually exist depends on the app's manifest and the device's API level (e.g. `READ_MEDIA_*` on API 33+ vs `READ_EXTERNAL_STORAGE` below it).
-
-## Actions
-
-- **`grant`** - pre-authorize the permission. Requires `bundleId`.
-- **`deny`** - refuse it. Requires `bundleId`. Use to test the app's "permission denied" path.
-- **`reset`** - return to the not-yet-asked state so the dialog reappears on next use. Always per-app (`bundleId` required):
-  - iOS: removes that app's TCC row. A device-wide reset (no bundleId) is **not** offered - on recent iOS runtimes it reports success but leaves existing per-app grants untouched, so it would report a change that never happened.
-  - Android: revokes the grant, then best-effort clears the user-set/user-fixed flags (flag-clearing first appears in Android 13 / API 33; the revoke is what counts toward success). Below API 33 (i.e. API 23-32, everywhere a user-fixed state can exist) flag-clearing is unavailable, so a `reset` there revokes the grant but cannot clear a "don't ask again" (user-fixed) state - the dialog may stay suppressed on those older devices.
-
-## Parameters
-
-```json
-{
-  "udid": "<UDID-or-serial>",
-  "action": "grant",
-  "permission": "camera",
-  "bundleId": "com.example.app"
-}
-```
-
-- `udid` - target from `list-devices` (iOS simulator UDID, or Android serial). See `argent-ios-simulator-setup` / `argent-android-emulator-setup` to get one.
-- `action` - `grant` | `deny` | `reset`.
-- `permission` - one of the 11 names above.
-- `bundleId` - iOS bundle id or Android package name. **Required for every action**.
-
-## Platform behavior
-
-**iOS simulator only.** Edits the simulator's TCC store - always per-app (`bundleId` required). There is no host-side TCC switch on a physical iPhone, so this tool does not apply to real iOS devices. The simulator must be **booted** first (`boot-device`) - otherwise the tool fails with a "current state: Shutdown" error and surfaces the boot hint.
-
-**Android emulator and physical device.** Changes the app's `android.permission.*` runtime permissions over adb (and, for `reset`, best-effort clears the user-set/user-fixed flags - the revoke is what decides success; flag-clearing needs Android 13 / API 33+). Requirements:
-
-- The app must be **installed** - the tool probes for the package first and errors clearly if it is missing (a transport/timeout failure surfaces adb's real cause, not a false "not installed").
-- The app must **declare** the permission in its manifest. The package manager rejects any mapped permission the manifest doesn't request; those come back in the result's `skipped` list. The action succeeds if **at least one** mapped permission sticks, and errors only if **all** of them were rejected.
-
 ## Gotchas
 
-- **Changing a permission can terminate a running app** (system behavior on both platforms). Prefer setting permissions **before** `launch-app`; if you change one while the app is running, `restart-app` afterward.
-- **Reset is per-app on both platforms** - pass `bundleId`; there is no reliable device-wide reset.
-- **A partial Android result is normal.** `applied` lists what actually changed; `skipped` lists mapped permissions the package manager rejected (usually not in the manifest, or gated by API level). Both together tell you what happened.
-- **A pre-launch `deny` suppresses the prompt on iOS only.** On iOS a TCC denial answers the app's request, so no dialog appears. On Android a `deny` clears the grant but sets no "user-fixed" flag, so the app's next request still shows the system dialog - a pre-launch `deny` there tests the revoked _state_, not a suppressed prompt.
-- **`camera` on iOS** may be rejected by a simulator **runtime** that doesn't model the service (it varies by simruntime, not by the installed Xcode - a runtime can accept `camera` even when the platform's own service list omits it). A rejection surfaces as a generic CoreSimulator error, so a `camera` failure (unless it's the shutdown-simulator case, which gets the boot hint instead) is reported with a hint about the runtime's supported services.
-- **`grant location` needs the app installed first (iOS).** Location authorization isn't stored in TCC and isn't applied to a bundle id until the app exists, so a pre-install `grant location` / `grant location-always` records nothing. On a **local** simulator the tool checks install state and errors clearly instead of reporting a false success; on a **remote** simulator it cannot probe install state, so a pre-install grant there reports success while recording nothing - make sure the app is installed before granting location remotely. (TCC-backed services like `camera`/`photos` _can_ be granted before install; they persist and apply on install.)
-
-## Result
-
-Returns `{ action, permission, bundleId, applied, skipped? }`:
-
-- `applied` - the platform-level services/permissions actually changed (the TCC service(s) on iOS; the `android.permission.*` names on Android).
-- `skipped` - Android only, present when some mapped permissions were rejected but others succeeded.
-
-The call **fails** when nothing could be applied - read the error; it names the reason: an unsupported permission for the platform (`notifications` on iOS, `reminders` on Android), the app not installed (including a pre-install `grant location` on iOS), a shutdown simulator (iOS), or every mapped permission being rejected (usually a missing manifest entry). A non-shutdown `camera` failure additionally hints about the simulator runtime's supported services (a shutdown-simulator failure gets the boot hint instead).
-
-## Examples
-
-Pre-grant the camera before launching, so the app never prompts:
-
-```json
-{ "udid": "<UDID>", "action": "grant", "permission": "camera", "bundleId": "com.example.app" }
-```
-
-Test the denied path - refuse location, then launch and observe the fallback:
-
-```json
-{ "udid": "<serial>", "action": "deny", "permission": "location", "bundleId": "com.example.app" }
-```
-
-Reset notifications on Android so the first-run prompt appears again next launch:
-
-```json
-{
-  "udid": "<serial>",
-  "action": "reset",
-  "permission": "notifications",
-  "bundleId": "com.example.app"
-}
-```
-
-Grant always-on location on Android (fans out to background + foreground automatically):
-
-```json
-{
-  "udid": "<serial>",
-  "action": "grant",
-  "permission": "location-always",
-  "bundleId": "com.example.app"
-}
-```
+- **iOS simulator only on Apple platforms.** A physical iPhone has no host-side TCC switch, so the tool does not apply there.
+- **A pre-launch `deny` suppresses the prompt on iOS only.** On iOS a TCC denial answers the app's request, so no dialog appears. On Android a `deny` clears the grant but sets no "user-fixed" flag, so the app's next request still shows the system dialog: a pre-launch `deny` there tests the revoked _state_, not a suppressed prompt.
+- **Android `reset` below API 33 can't clear "don't ask again".** It revokes the grant, but clearing the user-fixed flag needs Android 13 / API 33+, so the dialog may stay suppressed on older devices.
+- **Set permissions before `launch-app`.** A change can terminate a running app; if you change one while it runs, `restart-app` afterwards.
+- **Android `location-always`**: a `grant` also adds fine and coarse location, since background alone can't read location.

package/skills/argent-test-ui-flow/SKILL.md

@@ -3,59 +3,30 @@ name: argent-test-ui-flow
 description: Autonomously test an app UI (iOS or Android) by running interact-screenshot-verify loops using argent MCP tools. Use when testing UI flows, verifying login works, testing navigation, running UI test scenarios, manual QA steps, visible UI changes, or visual behavior.
 ---
 
-## Platform-agnostic
+## Before testing
 
-Physical iPhone (`kind: "device"`): read `argent-ios-device-interact` first. `launch-app` before anything; `describe` fails while the app is backgrounded.
-
-The interaction tool names are identical on iOS and Android (`gesture-tap`, `gesture-swipe`, `describe`, `screenshot`, `launch-app`, etc.) and the tool-server auto-dispatches based on the `udid` you pass (UUID-shape → iOS, adb serial → Android).
-
-**Before testing, resolve which device to test on.** Call `list-devices` and follow `<device_selection_rule>`: prefer a running device on any platform;
-
-Once a platform is chosen, the per-platform setup skill takes over:
+Resolve the device first: call `list-devices`, use the platform the user named or else prefer a device that is already running, and don't pick a cabled phone without explicit intent. Setup: `argent-ios-simulator-setup` / `argent-android-emulator-setup`. The interaction tool names are identical on iOS and Android.
 
-| Platform | Setup skill                     | Find devices with                                           |
-| -------- | ------------------------------- | ----------------------------------------------------------- |
-| iOS      | `argent-ios-simulator-setup`    | `list-devices` → `boot-device` with `udid` if none booted   |
-| Android  | `argent-android-emulator-setup` | `list-devices` → `boot-device` with `avdName` if none ready |
+Physical iPhone (`kind: "device"`): read `argent-ios-device-interact` first. `launch-app` before anything; `describe` fails while the app is backgrounded.
 
 ## 1. Workflow
 
-All interactions go through argent MCP tools. Ensure the simulator/emulator is ready before starting.
-
-For implementation tasks that modify visible UI, this workflow can also serve as a visual acceptance path.
+For implementation tasks that modify visible UI, this workflow also serves as a visual acceptance path.
 
-1. **Baseline screenshot**: Call `screenshot` to see the current UI state. For visual regression comparison or UI change verification, capture the baseline at `scale: 1.0` with `includeImageInContext: false` and keep the returned `path` before editing whenever feasible.
-2. **Find target**: Before tapping, use a discovery tool to get element coordinates:
-   - **React Native apps**: use `debugger-component-tree`: it returns component names with (tap: x,y) coordinates. This is the preferred tool for RN apps on either platform. To use it, resolve the `argent-react-native-app-workflow` skill for setup; on Android you must also run `adb -s <serial> reverse tcp:8081 tcp:8081` so Metro is reachable from the device, prefixed as the `list-devices` `hint` shows when it names an adb server.
-   - **Standard app screens and in-app modals**: use `describe`. On iOS this returns the AX tree (falls back to native-devtools when AX is empty); on Android it returns the uiautomator tree in the same DescribeNode shape.
-   - **Permission prompts / system modal overlays**: try `describe` first. Fall back to `screenshot` only if the overlay is not exposed reliably. When the app raises its own permission dialog, answer it here; that's the real flow under test. To take a prompt _out_ of the flow (pre-grant/deny before launch, re-enable a permission the user already denied, or reset it so the dialog reappears), use the `argent-settings-permissions` skill during setup instead of interacting with the dialog.
-   - **Fallback**: use `screenshot` to estimate where the desired component is, then verify immediately after the action.
-3. **Interact**: Perform the action (`gesture-tap`, `gesture-swipe`, `keyboard`, `button`, ...): you receive a screenshot automatically.
-4. **Verify**: Check the returned screenshot for expected results. If it shows a loading/transitional state, prefer blocking until it settles with `await-ui-element` (expected element `visible`, or a spinner `hidden`) over a guessed delay, but only with a selector you can trust (`text`/`identifier`/`role`) that the screen is known to have or that you saw in a prior `describe`; a guessed one just times out. Otherwise use a short fixed wait. Pick evidence by what's being asserted:
-   - **Visual** (layout, spacing, color, typography, image/icon rendering, clipping, overflow, text rendering): prefer `screenshot-diff` against the baseline captured in step 1: it surfaces pixel-visible changes the auto-screenshot might miss. Fall back to visual inspection of the auto-screenshot only when a stable baseline isn't available.
+1. **Baseline screenshot**: call `screenshot` to see the current UI state. For visual regression comparison or UI change verification, capture the baseline at `scale: 1.0` with `includeImageInContext: false` and keep the returned `path` before editing whenever feasible.
+2. **Find target**: get element coordinates from a discovery tool before tapping:
+   - **App screens (React Native included), in-app modals and system dialogs**: `describe`. Fall back to `screenshot` only if an overlay is not exposed reliably. When the app raises its own permission dialog, answer it here; that's the real flow under test. To take a prompt _out_ of the flow, use `argent-settings-permissions` during setup.
+   - **Fallback**: use `screenshot` to estimate where the component is, then verify immediately after the action.
+3. **Interact**: perform the action (`gesture-tap`, `gesture-swipe`, `keyboard`, `button`, ...); you receive a screenshot automatically.
+4. **Verify**: check the returned screenshot. If it shows a loading/transitional state, block with `await-ui-element` (expected element `visible`, or a spinner `hidden`) rather than a guessed delay (its result carries the new screenshot and element tree), but only with a selector you can trust (`text`/`identifier`/`role`) that the screen is known to have or that you saw in a prior `describe`; a guessed one just times out. Otherwise use a short fixed wait. Pick evidence by what's being asserted:
+   - **Visual** (layout, spacing, color, typography, image/icon rendering, clipping, overflow, text rendering): prefer `screenshot-diff` against the step 1 baseline: it surfaces pixel-visible changes the auto-screenshot might miss. Fall back to inspecting the auto-screenshot only when a stable baseline isn't available.
    - **Structural** (navigation state, element existence, accessibility labels/values, selection, hierarchy, route): verify with `describe`, `debugger-component-tree`, or `native-describe-screen`.
-   - **Runtime / log / network** (console errors, API calls, persistence, timing): verify with `view-network-logs`, `debugger-log-registry`, `debugger-evaluate`, or targeted tests. Note `debugger-log-registry` returns `{ status: "not_connected", reason, guidance }` with no log file when the debugger is unreachable; that is not evidence about the app; follow its `guidance` to reconnect, then re-verify.
+   - **Runtime / log / network** (console errors, API calls, persistence, timing): verify with `view-network-logs`, `debugger-log-registry`, `debugger-evaluate`, or targeted tests. A `not_connected` result from the debugger tools is not evidence about the app: follow its `guidance`, then re-verify.
    - **Mixed**: collect evidence for each relevant class.
    - Report the combined verdict: expected behavior, observed behavior, evidence used, and any blocker for requested visual diffing.
 5. **Repeat** for each step in the flow.
 
-## 2. Template
-
-```
-Goal: Test [feature name]
-
-Steps:
-1. Classify expected result: visual / structural / runtime-log-network / mixed → choose evidence
-2. [Navigate / tap / type to reach stable comparable starting point] → verify auto-screenshot
-3. screenshot { scale: 1.0, includeImageInContext: false } → save baseline path when visual or mixed evidence needs diffing
-4. [Perform the action to test] → verify auto-screenshot
-5. Use screenshot-diff when requested or when comparable images add useful visual evidence
-6. Report: pass / fail with combined visual, structural, runtime/log/network evidence as applicable
-```
-
-## 3. Examples
-
-### Login flow
+## 2. Example: login flow
 
 ```
 1. screenshot → see login screen
@@ -67,57 +38,16 @@ Steps:
 7. screenshot → verify home screen appeared
 ```
 
-> **Credentials:** never type plaintext credentials; use a `{{secret:<NAME>}}` placeholder in `keyboard`, resolved server-side so the value never enters agent context. It comes from the `ARGENT_SECRET_<NAME>` environment variable or an argent secrets file (`.argent/secrets.env` in the project, `~/.argent/secrets.env`, or an `ARGENT_SECRET_`-prefixed key in the project's `.env` / `.env.local`); over a link with `forward-secrets` on, the client's own sources come first. If the name is not defined, the failure lists the available names and every path it checked; ask the user to add it to one of those files (which applies immediately) instead of pasting the secret into the conversation. Never invent credentials or echo secret values into reports or saved files.
-
-### Scroll and navigation
-
-```
-1. screenshot → see list at top
-2. gesture-swipe { fromY: 0.7, toY: 0.3 } → scroll down
-3. gesture-tap item at visible position → verify auto-screenshot
-4. screenshot → verify detail view opened
-5. button { button: "back" }
-6. screenshot → verify returned to list
-```
-
-### Visual behavior check
-
-```
-1. Classify expected result as visual or mixed.
-2. Navigate to the stable starting state.
-3. screenshot { scale: 1.0, includeImageInContext: false } → save baseline path.
-4. describe / debugger-component-tree → find the control and use its returned tap coordinates.
-5. gesture-tap → perform the visual behavior under test.
-6. screenshot-diff { baselinePath, captureCurrent: true, udid, outputDir } → inspect visible change or stability.
-7. describe / debugger-component-tree → verify selected state, label, route, or attributes if relevant.
-8. Report combined verdict from expected behavior, visual inspection, diff summary, and structural evidence.
-```
-
-### Wait for a loading spinner
-
-```
-1. gesture-tap { x: 0.5, y: 0.7 } → trigger an action that fetches data
-2. screenshot → loading spinner is showing
-3. await-ui-element { condition: hidden, selector: { text: "Loading" } } → block until the fetch finishes and the spinner disappears; its result carries the screenshot and element tree, so verify the fetched content rendered from it
-```
-
----
-
-## 4. Recovery Pattern
+> **Credentials:** never type plaintext credentials; use a `{{secret:<NAME>}}` placeholder (`keyboard`'s `text` parameter lists where it is read from and what to do when a name is missing). Never invent credentials or echo secret values into reports or saved files.
 
-- If a screen is mid-transition or loading: block until it settles with `await-ui-element` (wait for the target element to be `visible`, or the spinner/placeholder to be `hidden`) instead of a blind fixed delay, then re-check. Fall back to a fixed wait + `screenshot` only when no element reliably marks the transition.
-- If tap misses target: re-run discovery tool (`describe` / `debugger-component-tree`), retry once with new coordinates.
-- If a permission dialog or modal is visible: re-run `describe` first. Stay in screenshot-driven navigation only when the overlay is not exposed reliably, then switch back to `describe` / `debugger-component-tree` as soon as it is dismissed.
-- If tap fails twice at same coordinates: stop, re-discover, report if element not found.
-- If a **saved e2e test** fails during `e2e-execute` replay (as opposed to live test steps above): follow `argent-create-e2e`'s [Diagnose a replay failure](../argent-create-e2e/references/reliability-and-recovery.md#diagnose-a-replay-failure): classify the failure, inspect the actual screen, repair the smallest justified unit, then replay the full e2e test.
+## 3. Recovery Pattern
 
-## Tips
+- Screen mid-transition or loading: wait with `await-ui-element` as in step 4, then re-check. Fall back to a fixed wait + `screenshot` only when no element reliably marks the transition. Don't poll with repeated screenshots.
+- Tap misses the target: re-run `describe` and retry once with new coordinates. If it fails twice, stop and report that the element was not found.
+- Permission dialog or modal visible: re-run `describe` first. Stay in screenshot-driven navigation only while the overlay is not exposed reliably: tap one visible button at a time, verify with the returned screenshot, and switch back to `describe` as soon as it is dismissed.
+- A **saved e2e test** fails during `e2e-execute` replay (as opposed to the live steps above): follow `argent-create-e2e`'s [Diagnose a replay failure](../argent-create-e2e/references/reliability-and-recovery.md#diagnose-a-replay-failure): classify the failure, inspect the actual screen, repair the smallest justified unit, then replay the full e2e test.
 
-- **Wait on the UI, don't poll.** When a step needs the screen to change first, gate it with `await-ui-element` (block until an element is `visible`/`hidden` or contains `text`) rather than repeated `screenshot` calls with fixed sleeps. See the `await-ui-element` section of `argent-device-interact`.
-- **Use `gesture-custom` for long-press** context menus (800ms hold).
-- **Report clearly**: state what you expected, what you saw, and the verdict.
-- **Permission modals**: try `describe` first. Use `screenshot` only as fallback, tap one visible button at a time, and verify with the returned screenshot before continuing.
-- **Record for replay**: If a tested flow is likely to be repeated, use the `argent-create-e2e` skill to record it as a `.yaml` script. This lets you replay the entire sequence later with a single `e2e-execute` call instead of re-running each step manually.
+**Record for replay**: if a tested flow is likely to be repeated, use the `argent-create-e2e` skill to record it as a `.yaml` test, so it can be replayed later with a single `e2e-execute` call.
 
 ## Related Skills
 

package/skills/argent-tv-interact/SKILL.md

@@ -10,6 +10,8 @@ description: Control and inspect TV apps via argent, Apple TV (tvOS), Android TV
 - A TV is **focus-driven, not touch-driven.** Drive every interaction with `describe` + `tv-remote` + `keyboard`; never use `gesture-*` / coordinate taps; they don't apply on any TV platform.
 - **Always `describe` before navigating** to find the live cursor and your target; never guess focus from a screenshot. The cursor is the focused element; on **Vega** the toolkit often leaves `focused` false and marks the highlighted item `[selected]`, so treat `[selected]` as the cursor when nothing reports `[focused]`.
 - Pass the `udid` from `list-devices`: an Apple TV simulator UDID or an Android TV / Vega `serial`. Dispatch is automatic from the id; the same tools drive all three.
+- **E2E tests: Vega only.** Apple TV and Android TV have no e2e support (a `tap:` can pass without doing anything): report that limitation.
+- **Fire TV (Vega)** (`platform: "vega"` in `list-devices`): read `references/vega.md` before driving it. It covers booting and stopping the VVD, Fast Refresh, and debugging the JS runtime.
 
 ## The navigation loop
 
@@ -19,52 +21,25 @@ description: Control and inspect TV apps via argent, Apple TV (tvOS), Android TV
 
 ## Tools
 
-- `describe {udid}`: focus view: the focused / `[selected]` element + focusable elements with labels and normalized frames. Call before and after navigating. Empty tree → see the per-platform notes.
-- `tv-remote {udid, button}`: D-pad / remote. `button` is one key **or a whole path** (run in one call). Keys: `up`/`down`/`left`/`right`, `select`, `back`, `menu`, `home`, `playPause`, plus media keys `rewind`/`fastForward`/`next`/`previous`/`volumeUp`/`volumeDown`/`mute`. Single: `{button:"down"}`; repeat: `{button:"down", repeat:3}`; path: `{button:["up","right","select"]}`.
-- `keyboard {udid, text}`: type into the focused field (focus it with `tv-remote` first). One call carries `text` or `key`, never both; to type and then press a key, send two `keyboard` steps in one `run-sequence`. Named `key` presses (e.g. `{key:"enter"}`) work on Vega; on Apple TV / Android TV move focus with `tv-remote` instead.
-- `launch-app` / `restart-app` / `reinstall-app {udid, bundleId}`: `bundleId` from the app manifest. Vega `reinstall-app` takes `appPath` = a `.vpkg`.
-- `screenshot {udid, scale?}`: Apple TV via `xcrun simctl io` (downscaled); Android TV / Vega host-side via `adb` / `screencap`.
+`describe`, `tv-remote` and `keyboard` descriptions cover the TV behaviour (focus view, remote keys and paths, text-only typing). Beyond them:
+
+- `launch-app` / `restart-app` / `reinstall-app` take the `bundleId` from the app manifest.
 
 ## Per-platform
 
 ### Apple TV (tvOS simulator)
 
-- Boot like any iOS sim (`boot-device`); the AX + HID daemons auto-start on the first `describe` / `tv-remote` (first call may take a few seconds). Give the RN bundle a few seconds to render before the first `describe`.
-- Media-transport / volume keys are **rejected**: the sim's HID stack ignores them (they work on Android TV / Vega).
+- Boot like any iOS sim (`boot-device`); the AX + HID daemons auto-start on the first `describe` / `tv-remote` (first call may take a few seconds).
 - Dev build: `open-url {udid, url:"<scheme>://expo-development-client/?url=http%3A%2F%2F<HOST_IP>%3A8081"}` (`<HOST_IP>` = your Mac's LAN IP, shown on the launcher).
 
 ### Android TV (leanback emulator)
 
 - Boot the leanback AVD like any emulator; see `argent-android-emulator-setup`.
-- **`describe` may report zero focusables on a screen with visible tiles**: many `react-native-tvos` screens use RN's own focus engine, invisible to the OS accessibility tree. `describe` auto-falls-back to the full UI tree (and says so in the hint); `tv-remote` still moves focus, so drive blind + `screenshot` to confirm.
-- Dev build: `adb -s <serial> reverse tcp:8081 tcp:8081`, deep-link `<pkg>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081`, dismiss the first dev-menu with `adb shell input keyevent KEYCODE_DPAD_CENTER` (not Back: Back exits the app). If `list-devices` returns a `hint` about the adb server, prefix these `adb` commands as the hint shows.
-
-### Fire TV (Vega / VVD)
-
-- `list-devices` shows a `serial` (use as `udid`) and a `vvdImage`. `boot-device {vvdImage}` (e.g. `"tv"`) starts the single SDK-managed VVD; skip if one already runs.
-- **Stop the VVD** with `vega virtual-device stop` in your shell. The CLI only tracks VVDs it started in the foreground, so it may report "not running" for one started via `boot-device`; to restart that one use `boot-device {vvdImage, force:true}` (stops then re-boots).
-- Empty `describe` tree → `restart-app` (the automation toolkit attaches at launch), then retry. Input ignored → enable developer mode in the VVD: `vsm developer-mode enable`.
-- Editing `node_modules` has no effect on a Release build; only Debug `.vpkg` builds load patchable JS.
-- Profiling / crashes → `amazon-devices-buildertools-mcp` server (`analyze_perfetto_traces`, `get_app_hot_functions`, `symbolicate_acr`); docs via its `search_documentation` tool.
-
-## Common gotchas
-
-- **Empty focus right after `launch-app` / `restart-app`** is the splash / loading window; `describe` retries internally; wait ~2-3s and retry on a cold start.
-- Passing a phone/tablet (`runtimeKind: "mobile"`) udid to `tv-remote` fails with a clear "tvOS-only" / "Android-TV-only" error; pick a TV target from `list-devices`.
+- Dev build: `open-url` `<scheme>://expo-development-client/?url=http%3A%2F%2F10.0.2.2%3A8081` (`<scheme>`: the app's URL scheme, or its package name if it sets none), then dismiss the first dev menu with `tv-remote` `select` (not `back`: it exits the app).
 
 ## Fast Refresh (dev builds)
 
-Needs a Debug build + Metro running. argent only _connects_ to Metro; start Metro and port-forward yourself (any platform). Metro is fixed on **:8081**.
+Needs a Debug build + Metro running. argent only _connects_ to Metro: start Metro yourself, and forward the port where the app needs it (Android: `argent-metro-debugger` §1; Vega: `references/vega.md`).
 
 - **Apple TV / Android TV:** use the dev-build deep-links above; `npm start` for Metro.
-- **Vega:** build/install a Debug `.vpkg` (`vega device install-app -p <path>`), `npm start`, `vega device start-port-forwarding --port 8081 --forward false`, then `vega device launch-app -a <appId>`. Confirm `http://localhost:8081/json/list` shows a `Hermes React Native` target; `.tsx` edits then hot-reload.
-
-## Debugging the JS runtime (Vega)
-
-Once that same Debug build + Metro setup is in place, the JS-runtime tools work on a Vega VVD: `debugger-connect`, `debugger-status`, `debugger-evaluate`, `debugger-log-registry` (console logs), `view-network-logs`, and `view-network-request-details`. Verify with `debugger-status`: it returns a status result rather than an error when not connected: `status: "connected"` means the setup works; `status: "not_connected"` carries a `reason` and `guidance` (e.g. `metro_not_running` → Metro itself is not up). Vega-specific: on `no_app_connected`, check `vega device start-port-forwarding` **before** relaunching the app: a down device→host forward is the usual cause, and the generic guidance can't know about it. See the `argent-metro-debugger` skill.
-
-Vega's React Native forks RN 0.72 and serves the legacy Hermes inspector, so three things differ from iOS / Android:
-
-- `debugger-component-tree`, `debugger-inspect-element`, `debugger-reload-metro` and the `react-profiler-*` / `profiler-*` tools are **not supported**. Component-tree and inspect-element are hard-blocked: they need `Runtime.addBinding`, which this Hermes acknowledges but never installs. The rest are simply unverified on the legacy inspector. Use `describe` for on-screen structure; with both component tools gated off, component `file:line` tracing has no path on Vega.
-- `debugger-status` reports `isNewDebugger: false`.
-- `projectRoot` is empty (RN 0.72's Metro sends no project-root header), so lookups that resolve paths against the project root return no location.
+- **Vega:** see `references/vega.md`.

package/skills/argent-tv-interact/references/vega.md

@@ -0,0 +1,23 @@
+# Fire TV (Vega / VVD)
+
+Everything in the related SKILL.md still applies; this page covers what is Vega-only.
+
+## Device
+
+- Use the `serial` from `list-devices` as `udid`; start a stopped VVD with `boot-device {vvdImage}`.
+- **Stop the VVD** with `vega virtual-device stop` in your shell. The CLI only tracks VVDs it started in the foreground, so it may report "not running" for one started via `boot-device`; to restart that one use `boot-device {vvdImage, force:true}` (stops then re-boots).
+- Input ignored → enable developer mode in the VVD: `vsm developer-mode enable`.
+- Editing `node_modules` has no effect on a Release build; only Debug `.vpkg` builds load patchable JS.
+- Profiling / crashes → `amazon-devices-buildertools-mcp` server (`analyze_perfetto_traces`, `get_app_hot_functions`, `symbolicate_acr`); docs via its `search_documentation` tool.
+- `keyboard` named `key` presses (e.g. `{key:"enter"}`) work on Vega, unlike Apple TV / Android TV.
+- `reinstall-app` takes a `.vpkg` as `appPath`.
+
+## Fast Refresh
+
+Build and install a Debug `.vpkg` (`vega device install-app -p <path>`), `npm start`, `vega device start-port-forwarding --port 8081 --forward false`, then `vega device launch-app -a <appId>`. Confirm `http://localhost:8081/json/list` shows a `Hermes React Native` target; `.tsx` edits then hot-reload.
+
+## Debugging the JS runtime
+
+Once that same Debug build + Metro setup is in place, the JS-runtime tools work on a Vega VVD: `debugger-connect`, `debugger-status`, `debugger-evaluate`, `debugger-log-registry` (console logs), `view-network-logs`, and `view-network-request-details`. Verify with `debugger-status`. Vega-specific: on `no_app_connected`, check `vega device start-port-forwarding` **before** relaunching the app: a down device→host forward is the usual cause, and the generic guidance can't know about it. See the `argent-metro-debugger` skill.
+
+Vega's React Native forks RN 0.72 and serves the legacy Hermes inspector, so `debugger-component-tree`, `debugger-inspect-element`, `debugger-reload-metro` and the `react-profiler-*` / `profiler-*` tools are **not supported**. Component-tree and inspect-element are hard-blocked: they need `Runtime.addBinding`, which this Hermes acknowledges but never installs. The rest are simply unverified on the legacy inspector. Use `describe` for on-screen structure; with both component tools gated off, component `file:line` tracing has no path on Vega. `isNewDebugger: false` and an empty `projectRoot` are expected there.

package/agents/argent-environment-inspector.md

@@ -1,107 +0,0 @@
----
-name: argent-environment-inspector
-description: >
-  Inspects a mobile app project's environment and returns structured JSON covering
-  project type, platform support, build and startup commands, bundler config, env
-  resolution, key packages, QA/feedback-loop tooling, and Argent-specific workflow
-  commands. Works on any project: determines whether it is React Native, Expo,
-  Flutter, native iOS/Android, or another stack, and provides environment context
-  regardless. Has deeper React Native introspection via gather-workspace-data but
-  also reports useful information for non-RN projects.
-  Use proactively at session start when required to gather the environment information.
-  If subagent delegation is not available, run the steps in the main thread instead.
-  The main agent is responsible for persisting the result to project memory.
----
-
-You are the **environment-inspector** subagent. Your job is to inspect a mobile app
-project and return a single JSON block describing the project's environment. You do
-not write files; the main agent handles persistence.
-
-**Your first task is to determine what kind of project this is.**. The project could be, for example:
-
-- React Native (bare CLI or Expo)
-- Flutter / Dart
-- Native iOS (Swift / Objective-C with Xcode)
-- Native Android (Kotlin / Java with Gradle)
-- A web app, a monorepo containing multiple apps, or something else entirely
-
-Provide useful environment context regardless of the project type. You have
-deep introspection tools at your disposal - `gather-workspace-data`, which provides heuristical
-context about the workspace structure. If any of the information is not retrieved from the tool,
-but required by the main agent, fill it in by manual inspection of the project.
-
-## Execution steps
-
-1. **Call `gather-workspace-data`** with the project's workspace path.
-   This is always your first action. It returns a structured snapshot of
-   `package.json`, metro/babel config text, `app.json`, `eas.json`, `tsconfig`,
-   platform directories, lockfile type, `.env` key names, CLI tool versions,
-   `scripts/` listing, husky hooks, CI config, Makefile targets, and config
-   file existence.
-
-2. **Determine the project type.** From the snapshot, classify the project:
-   - `react-native` in `package.json` dependencies → React Native project
-   - `expo` in dependencies or `app.json` with `expo` key → Expo project
-   - `pubspec.yaml` present → Flutter project
-   - `ios/*.xcodeproj` or `ios/*.xcworkspace` without `react-native` → native iOS
-   - `android/build.gradle` or `android/build.gradle.kts` without `react-native` → native Android
-   - None of the above → classify based on what you find (web app, library, etc.)
-
-3. **Explore beyond the snapshot.** Use Read, Glob, Grep, and Bash to fill
-   gaps the snapshot does not cover:
-   - Non-obvious `scripts/` directory contents and what each script does.
-   - CI workflow files (`.github/workflows/*.yml`) to understand what "passing" means.
-   - Custom Makefile or Fastfile targets.
-   - `package.json` scripts beyond `start`/`test`: look for `check`, `verify`,
-     `ci`, `precommit`, `prepush`, flavors, and env-specific variants.
-   - `.husky/` hook contents to understand pre-commit/pre-push validation.
-   - `lint-staged` config to understand what runs on commit.
-   - Monorepo indicators: `workspaces` in root `package.json`, `turbo.json`,
-     `nx.json`, `lerna.json`.
-   - README or CONTRIBUTING docs that describe build/run/test workflows.
-   - Storybook config (`.storybook/`), Detox config (`.detoxrc.js`), Maestro
-     flows (`.maestro/`).
-   - For Flutter: `pubspec.yaml`, `analysis_options.yaml`, `lib/` structure.
-   - For native iOS: Xcode project/workspace, schemes, `Podfile`, `Package.swift`.
-   - For native Android: `build.gradle` / `build.gradle.kts`, `settings.gradle` / `settings.gradle.kts`, flavor configs.
-
-4. **Populate every field** in the output schema below. Use `null` for
-   genuinely unknown values or fields that do not apply to this project type.
-   Prefer concrete commands over generic ones (e.g. `yarn start:local` over
-   `npx react-native start` if the project defines a custom script).
-
-5. **Return the JSON block**: no prose, no markdown fences, no
-   explanation. The main agent parses your entire response as JSON.
-
-## Output schema
-
-Return a JSON object with these top-level fields:
-
-| Field                                 | Type         | Description                                                                                   |
-| ------------------------------------- | ------------ | --------------------------------------------------------------------------------------------- |
-| `project_type`                        | string       | `react-native`, `expo`, `flutter`, `native-ios`, `native-android`, `web`, `monorepo`, `other` |
-| `project_type_details`                | string       | Short human-readable stack summary                                                            |
-| `is_react_native`                     | bool         | `react-native` in deps                                                                        |
-| `is_ios` / `is_android`               | bool         | Platform directories exist                                                                    |
-| `is_expo` / `is_web` / `is_flutter`   | bool         | Framework detection flags                                                                     |
-| `is_native_ios` / `is_native_android` | bool         | Native without cross-platform framework                                                       |
-| `startup_commands`                    | array        | `[{ command, context }]`: concrete dev server start commands                                  |
-| `build_commands`                      | array        | `[{ command, platform, context }]`: build commands per platform                               |
-| `argent_workflow`                     | object       | `{ start_dev_server, build_ios, build_android, notes }`: exact commands for Argent            |
-| `ios_has_podfile`                     | bool         | True when `ios/Podfile` exists                                                                |
-| `android_has_gradle`                  | bool         | True when `android/gradlew` exists                                                            |
-| `configs`                             | object       | Paths to metro, babel, app, tsconfig, pubspec, xcode, gradle configs (`null` if absent)       |
-| `metro_port`                          | number\|null | From config or default 8081; `null` for non-RN                                                |
-| `env_resolution`                      | object       | `{ env_files, strategy, notes }`                                                              |
-| `key_packages`                        | object       | Major dependencies with versions                                                              |
-| `package_json`                        | object       | `{ name, version, scripts_summary }`                                                          |
-| `bundler`                             | string\|null | `metro`, `webpack`, etc.                                                                      |
-| `terminal_tools`                      | object       | `{ package_manager, pod_available, expo_cli, eas_cli }`                                       |
-| `cloud_build`                         | object       | `{ eas, eas_profiles }` or other CI/CD                                                        |
-| `quality_control`                     | object       | Linting, formatting, type checking, unit tests, e2e tests, feedback loop tools                |
-| `additional_notes`                    | string       | Anything relevant not covered above                                                           |
-| `needs_user_input`                    | bool         | True if critical info is missing                                                              |
-| `missing_information`                 | array        | List of things you couldn't determine                                                         |
-| `inspected_at`                        | string       | ISO 8601 timestamp                                                                            |
-
-For the `quality_control` field structure, see `references/quality-control-checklist.md`.

package/agents/references/quality-control-checklist.md

@@ -1,45 +0,0 @@
-## Quality control checklist
-
-The `quality_control` field in the output JSON must follow this structure:
-
-```json
-{
-  "linting": { "eslint": bool, "eslint_config": "path", "run_command": "cmd", "fix_command": "cmd" },
-  "formatting": { "prettier": bool, "prettier_config": "path", "run_command": "cmd" },
-  "type_checking": { "typescript": bool, "strict_mode": bool, "run_command": "cmd" },
-  "unit_tests": { "jest": bool, "jest_config": "path", "run_command": "cmd", "watch_command": "cmd", "coverage_command": "cmd" },
-  "e2e_tests": { "detox": bool, "maestro": bool, "xctest": bool, "flutter_integration_test": bool },
-  "feedback_loop_tools": { "metro_hot_reload": bool, "flutter_hot_reload": bool, "react_devtools": bool, "flipper": bool, "storybook": bool, "notes": "string" }
-}
-```
-
-Look for these beyond the obvious lint/test configs, regardless of project type:
-
-**Immediate feedback tools (agent can trigger during a task):**
-
-- `tsc --noEmit`: instant type error feedback after edits (TypeScript projects)
-- `eslint --fix` / `swiftlint` / `ktlint`: auto-fixable lint errors
-- `jest --testPathPattern <file>`: single test file (JS/TS projects)
-- `dart analyze`: static analysis (Flutter projects)
-- `flutter test <file>`: single test file (Flutter projects)
-- `yarn test --watch` / `flutter test --watch`: reactive test runner
-- Metro hot reload (via `debugger-reload-metro` Argent tool, RN only)
-- Flutter hot reload / hot restart
-
-**Slower validation tools (agent runs at end of a task):**
-
-- Full test suite run (`jest`, `flutter test`, `xcodebuild test`, `gradle test`)
-- E2E: Detox, Maestro, XCUITest, Espresso, Flutter integration tests
-- `eas build --local` / `flutter build` / `xcodebuild` for native validation
-
-**Indicators to check (all project types):**
-
-- `scripts/` directory at project root: often contains custom validation scripts
-- `Makefile` / `Fastfile` targets: look for `lint`, `test`, `typecheck`, `check`, `validate`
-- `package.json` scripts named `check`, `verify`, `ci`, `precommit`, `prepush`
-- `.husky/` directory: which hooks run and what they execute
-- `lint-staged` config: what runs on commit
-- CI config files: the CI steps are ground truth for what "passing" means
-- `Podfile` / `Package.swift`: iOS dependency management
-- `build.gradle` / `build.gradle.kts` / `settings.gradle` / `settings.gradle.kts`: Android build config and flavor definitions (Groovy or Kotlin DSL)
-- `pubspec.yaml` / `analysis_options.yaml`: Flutter project config and lint rules