@swmansion/argent 0.12.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",
   "repository": {

package/rules/argent.md

@@ -4,7 +4,7 @@ alwaysApply: true
 ---
 
 <description>
-If argent is installed and configured in this environment, its MCP tools are the preferred form of interaction with the application for iOS simulator, Android emulator, and Chromium (CDP) app control; otherwise see `<availability_check>` below before attempting any argent workflow. A "Chromium (CDP) app" is any Chromium runtime exposing a Chrome DevTools Protocol endpoint — an Electron app, or any Chromium-family browser (Chrome/Brave/Edge) launched with `--remote-debugging-port`; all are driven through the same tool surface and tagged `platform: "chromium"`.
+If argent is installed and configured in this environment, its MCP tools are the preferred form of interaction with the application for iOS simulator, Android emulator, Chromium (CDP) app, and Vega (Amazon Fire TV) device control; otherwise see `<availability_check>` below before attempting any argent workflow. A "Chromium (CDP) app" is any Chromium runtime exposing a Chrome DevTools Protocol endpoint — an Electron app, or any Chromium-family browser (Chrome/Brave/Edge) launched with `--remote-debugging-port`; all are driven through the same tool surface and tagged `platform: "chromium"`. A "Vega device" is a virtual device (VVD) or physical unit — driven by tv-remote (D-pad) and tagged `platform: "vega"`.
 Running MCP server and managing the Argent toolkit utilises `argent` command - if asked use `argent --help` for reference.
 To check current version of MCP server run `argent --version` command.
 
@@ -15,7 +15,7 @@ Use cases:
 - Any tapping, swiping, typing, screenshotting, or inspecting a running app
 - Any code change that affects visible mobile UI, layout, styling, copy, navigation, or screen composition
 - Any request to execute manual QA, UI QA, or visual behavior validation for a mobile app
-- Running, debugging, or testing a React Native app (iOS or Android)
+- Running, debugging, or testing a React Native app (iOS, Android or Vega)
 - Profiling performance or diagnosing re-renders in a React Native app (iOS or Android)
 - Running, debugging, or testing a Chromium (CDP) app — an Electron app (boot with `boot-device` + `electronAppPath`) or a Chromium browser exposing CDP (auto-discovered on port `9222` / `ARGENT_CHROMIUM_PORTS`); on Chromium scroll with `gesture-scroll` and drag with `gesture-drag` — `gesture-swipe` is touch-only
   </description>
@@ -80,7 +80,7 @@ Decision order:
 - When the session ends or the user says they are done: call `stop-all-simulator-servers`.
   If the user started Metro separately, ask whether to call `stop-metro` (specify the port if not 8081).
 - If tools provided by mcp-server are not sufficient and action can be done using `xcrun`, `adb`, or other commands, use the command. Examples: changing device options, performing a device action such as lock, shake, etc.
-- When waiting for an action, do not call `screenshot` repeatedly without a proper wait mechanism. For example, six consecutive `screenshot` calls with no adequate delay between them will cause context bloat.
+- When waiting for an action, do not call `screenshot` repeatedly without a proper wait mechanism. Use the `await-ui-element` tool to block until the UI settles (e.g. wait for an element to become `visible`/`hidden`, or to contain expected `text`) instead of polling.
   </general_rules>
 
 <react_native_detection>
@@ -98,7 +98,7 @@ Load the matching skill before starting work and executing tools from argent-mcp
 procedure and edge-case handling for each workflow.
 
 PLATFORM DETECTION
-If the user did not specify a platform, call `list-devices` first and pick the booted target — do not default to iOS.
+If the user did not specify a platform, call `list-devices` first and pick the booted target — do not default to iOS. Vega (Amazon Fire TV) devices appear as `platform:"vega"`, when present load `argent-vega`
 
 iOS SIMULATOR SETUP
 Skill: `argent-ios-simulator-setup`
@@ -108,6 +108,11 @@ ANDROID EMULATOR SETUP
 Skill: `argent-android-emulator-setup`
 When: Beginning a task that involves the Android emulator, no emulator running yet, need an adb serial, or about to install an APK.
 
+VEGA / AMAZON FIRE TV APP CONTROL
+Skill: `argent-vega`
+When: Any task involving a Vega / Amazon Fire TV device (a `platform:"vega"` / `kind:"vvd"` entry in `list-devices`, or the user mentions Vega / Fire TV / VVD). Covers list/launch/restart/reinstall apps, on-screen element discovery via `describe`, D-pad navigation with the `tv-remote` tool (Vega is remote-driven, not touch), typing, screenshots, Fast Refresh setup, and VVD lifecycle (start/stop via the `vega` CLI — argent has no Vega stop tool).
+Prompt keywords: vega, fire tv, vvd, virtual device, d-pad
+
 TAPPING, SWIPING, TYPING, GESTURES, SCREENSHOTS, SCROLLING
 Skill: `argent-device-interact`
 When: Performing touch interactions, typing, pressing hardware buttons, launching/restarting apps, opening URLs, rotating device, taking standalone screenshots, or verifying a visible UI code change.

package/skills/argent-create-flow/SKILL.md

@@ -58,6 +58,13 @@ command: "screenshot"
 args: "{\"udid\": \"<UDID>\"}"
 ```
 
+```
+command: "await-ui-element"
+args: "{\"udid\": \"<UDID>\", \"condition\": \"visible\", \"selector\": {\"text\": \"Continue\"}}"
+```
+
+Record an `await-ui-element` step to **gate** the next step on a screen transition — it blocks until the element is `visible`/`hidden` (or contains `text`), so the following step runs only once the screen has actually settled. If its condition is not met before the timeout, replay **stops at that step** (the steps after it assume the transition happened). Prefer this over a fixed `delayMs`. See the `await-ui-element` section of `argent-device-interact` for the full condition/selector reference.
+
 For tools with no arguments, omit `args` entirely.
 
 ## 5. Important Rules
@@ -99,7 +106,7 @@ flow-execute   { name: "open-settings", project_root: "/Users/dev/MyApp", prereq
 Flow files use YAML. The top-level is an object with `executionPrerequisite` (describes required state) and `steps` (array of actions):
 
 - `- echo: <message>` — a label
-- `- tool: <name>` with optional `args:` — a tool call. Add `delayMs: <ms>` to sleep that long before the step runs (use sparingly — only when the app needs a fixed wait between actions).
+- `- tool: <name>` with optional `args:` — a tool call. A tool step may also carry `delayMs: <ms>` to sleep that long before it runs. (`await-ui-element` is an ordinary tool step; see §4 and §10.5 for when to gate a transition with one.)
 
 Example `.yaml` file:
 
@@ -111,6 +118,13 @@ steps:
     args:
       udid: ABC
       bundleId: com.apple.Preferences
+  - echo: Wait for the Settings list to render
+  - tool: await-ui-element
+    args:
+      udid: ABC
+      condition: visible
+      selector:
+        text: General
   - echo: Tap General
   - tool: gesture-tap
     args:
@@ -207,6 +221,7 @@ After applying a correction, re-run `flow-execute` to verify.
 Apply these when recording new flows to reduce future breakage:
 
 - **Echo expected state, not just actions.** Write `"On Settings > General screen, about to tap About"` not `"Tap About"`. During diagnosis these tell you what the screen _should_ look like.
+- **Gate transitions with `await-ui-element`, not fixed delays.** After a tap that triggers a navigation, record an `await-ui-element` step that waits for the next screen's element to be `visible` (or a spinner to be `hidden`) before the following step. This removes the **Timing** failure mode in §10.2 (the element is in the tree but the tap fired before the screen settled) and is more reliable than `delayMs` or an extra `screenshot`. An unmet wait stops replay at that step, so a mistimed step can never run blind.
 - **Add screenshot steps after critical navigation.** Insert `screenshot` steps after screen transitions. These produce images in the flow result you can inspect during diagnosis.
 - **Write specific executionPrerequisites.** `"App on home tab, user logged in, simulator UDID is <X>"` — not `"App running"`. Verify with `screenshot` + `describe` before acknowledging.
 - **Prefer launch-app / open-url over navigation chains.** Deep links are more resilient to layout changes than tap sequences.

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

@@ -1,6 +1,6 @@
 ---
 name: argent-device-interact
-description: Interact with an iOS simulator, Android emulator, or Chromium (CDP) app using argent MCP tools. Use when tapping UI elements, performing gestures, scrolling/swiping, typing text, pressing hardware buttons, launching apps, opening URLs, taking screenshots, or checking visible app state after interactions.
+description: Interact with an iOS simulator, Android emulator, or Chromium (CDP) app using argent MCP tools. Use when tapping UI elements, performing gestures, scrolling/swiping, typing text, pressing hardware buttons, launching apps, opening URLs, taking screenshots, waiting for an element to appear or disappear, or checking visible app state after interactions.
 ---
 
 ## Unified tool surface
@@ -28,7 +28,7 @@ Use `list-devices` to get a target id. Results are tagged with `platform` (`ios`
 1. **Always refer to tapping_rule** from your argent.md rule before tapping.
 2. Before performing interactions, consider whether they can be **dispatched sequentially** - more on that in `run-sequence`.
 3. **Use `gesture-swipe` for lists/scrolling**, not `gesture-custom`, unless you need non-linear movement. On Chromium use `gesture-scroll` instead — `gesture-swipe` is touch-only. Consider whether you need multiple swipes, if yes - use `run-sequence`.
-4. **Tap a text field before typing** — on iOS try `paste` first then fall back to `keyboard`; on Android use `keyboard` directly (`paste` is iOS-only).
+4. **Tap a text field before typing**, then use `keyboard` to enter text.
 5. **Coordinates are normalized** — always 0.0–1.0, not pixels.
 6. **For app navigation, prefer `describe` first.** It works on any screen without app restart. Do not navigate from screenshots on regular in-app screens unless `describe` failed to expose a reliable target. Use `native-describe-screen` only when you need app-scoped UIKit properties.
 
@@ -54,25 +54,25 @@ Common schemes: `messages://`, `settings://`, `maps://?q=<query>`, `tel://<numbe
 
 ## 4. Choosing the Right Tool
 
-| Action            | Tool             | Notes                                                                  |
-| ----------------- | ---------------- | ---------------------------------------------------------------------- |
-| Multiple actions  | `run-sequence`   | Batch steps in one call (no intermediate screenshots)                  |
-| Open an app       | `launch-app`     | **Always — never tap home-screen icons**                               |
-| Restart an app    | `restart-app`    | Terminate and relaunch by bundle ID                                    |
-| Open URL/scheme   | `open-url`       | Web pages, deep links, URL schemes                                     |
-| Single tap        | `gesture-tap`    | Buttons, links, checkboxes                                             |
-| Scroll/swipe      | `gesture-swipe`  | Straight-line scroll or swipe                                          |
-| Scroll (Chromium) | `gesture-scroll` | Wheel-based; deltas are window fractions, positive deltaY = down       |
-| Drag (Chromium)   | `gesture-drag`   | Sliders, drag-and-drop, text selection                                 |
-| Long press        | `gesture-custom` | Context menus, drag start                                              |
-| Drag & drop       | `gesture-custom` | Complex drag interactions                                              |
-| Pinch/zoom        | `gesture-pinch`  | Two-finger pinch with auto-interpolation                               |
-| Rotation          | `gesture-rotate` | Two-finger rotation with auto-interpolation                            |
-| Custom gesture    | `gesture-custom` | Arbitrary touch sequences, optional interpolation                      |
-| Hardware key      | `button`         | Home, back, power, volume, appSwitch, actionButton                     |
-| Type text (fast)  | `paste`          | iOS only. Form fields — uses clipboard                                 |
-| Type text         | `keyboard`       | iOS+Android. Fallback when paste fails; supports Enter, Escape, arrows |
-| Rotate device     | `rotate`         | Orientation changes                                                    |
+| Action            | Tool               | Notes                                                            |
+| ----------------- | ------------------ | ---------------------------------------------------------------- |
+| Multiple actions  | `run-sequence`     | Batch steps in one call (no intermediate screenshots)            |
+| Open an app       | `launch-app`       | **Always — never tap home-screen icons**                         |
+| Restart an app    | `restart-app`      | Terminate and relaunch by bundle ID                              |
+| Open URL/scheme   | `open-url`         | Web pages, deep links, URL schemes                               |
+| Single tap        | `gesture-tap`      | Buttons, links, checkboxes                                       |
+| Scroll/swipe      | `gesture-swipe`    | Straight-line scroll or swipe                                    |
+| Scroll (Chromium) | `gesture-scroll`   | Wheel-based; deltas are window fractions, positive deltaY = down |
+| Drag (Chromium)   | `gesture-drag`     | Sliders, drag-and-drop, text selection                           |
+| Long press        | `gesture-custom`   | Context menus, drag start                                        |
+| Drag & drop       | `gesture-custom`   | Complex drag interactions                                        |
+| Pinch/zoom        | `gesture-pinch`    | Two-finger pinch with auto-interpolation                         |
+| Rotation          | `gesture-rotate`   | Two-finger rotation with auto-interpolation                      |
+| Custom gesture    | `gesture-custom`   | Arbitrary touch sequences, optional interpolation                |
+| Hardware key      | `button`           | Home, back, power, volume, appSwitch, actionButton               |
+| Type text         | `keyboard`         | iOS+Android. Supports Enter, Escape, arrows                      |
+| Rotate device     | `rotate`           | Orientation changes                                              |
+| Wait for UI       | `await-ui-element` | Block until an element is visible/hidden/exists/contains text    |
 
 ## 5. Finding Tap Targets
 
@@ -161,14 +161,6 @@ For long-press, drag-and-drop, and other complex sequences, see `references/gest
 
 Values: `home`, `back`, `power`, `volumeUp`, `volumeDown`, `appSwitch`, `actionButton`
 
-### paste — Type text into focused field (iOS only)
-
-```json
-{ "udid": "<UDID>", "text": "Hello, world!" }
-```
-
-Tap the field first, then paste. Fall back to `keyboard` if it doesn't work. On Android the call is rejected by the capability gate ("Tool 'paste' is not supported on android") — use `keyboard` directly.
-
 ### keyboard — Type text or press special keys
 
 ```json
@@ -185,6 +177,23 @@ Special keys: `enter`, `escape`, `backspace`, `tab`, `space`, `arrow-up`, `arrow
 
 Values: `Portrait`, `LandscapeLeft`, `LandscapeRight`, `PortraitUpsideDown`
 
+### await-ui-element — Block until a UI element reaches a state
+
+Instead of polling `screenshot`/`describe` in a loop, use `await-ui-element` to block server-side until an element reaches an expected state (or `timeoutMs`, default 5000ms, elapses). It polls the same accessibility/DOM tree as `describe`. (For a plain pause, use your own harness sleep — this tool deliberately has no bare-timer mode.)
+
+```json
+{ "udid": "<UDID>", "condition": "visible", "selector": { "text": "Continue" } }
+```
+
+- `condition`: `exists`, `visible`, `hidden`, or `text`.
+- `selector`: `{ text?, identifier?, role? }` — every provided field must match (case-insensitive substring). `text` matches the element's label or value; `identifier` matches its accessibility id / resource-id / testID; `role` matches its element role (e.g. `AXButton`, `button`, `TextView`, `StaticText`). The synthetic `ROOT` container `describe` prints is never matched, so a `role` like `AXGroup`/`html` won't trivially "match the screen".
+- Prefer a **specific** selector. A loose substring can match several elements, and the tool may then key off one you didn't mean: `text` reads the **first** match in **reading order** (top-to-bottom, left-to-right — the same order `describe` lists them, so it's the one you saw first), while `visible`/`exists` are satisfied by **any** match. Disambiguate with a longer or more exact string, an `identifier`, or a `role` (e.g. pin to a text role like `StaticText` to skip a same-named button). On a `text` timeout the `note` quotes the matched element's text, so you can see which one it landed on.
+- `text` condition also needs `expectedText` (substring the matched element must contain).
+- `hidden` treats a selector that matches **nothing** as already-hidden, so a typo'd selector returns an instant (false) success. Double-check the selector for `hidden` waits — the result `note` flags when the selector never matched any element. (On iOS, if the accessibility backend is down the tree comes back empty; the tool will **not** report `hidden` success off such a degraded read and the `note` surfaces the boot hint instead.)
+- Optional `timeoutMs` (default 5000) and `pollIntervalMs` (default 400).
+
+Returns `{ success, elapsed }`; on a timeout `success` is `false` and a `note` explains what was seen.
+
 ---
 
 ## 7. Screenshots
@@ -246,10 +255,12 @@ Use the sequencing when:
 
 ### Allowed tools inside `run-sequence`
 
-`gesture-tap`, `gesture-swipe`, `gesture-custom`, `gesture-pinch`, `gesture-rotate`, `button`, `keyboard`, `rotate`
+`gesture-tap`, `gesture-swipe`, `gesture-scroll`, `gesture-drag`, `gesture-custom`, `gesture-pinch`, `gesture-rotate`, `button`, `keyboard`, `rotate`, `await-ui-element`
 
 The `udid` is shared — do **not** include it in each step's `args`. Optional `delayMs` per step (default 100ms).
 
+Add an `await-ui-element` step to gate a later tap on a screen transition (e.g. tap → wait for the next screen's button → tap it). If its condition is **not** met before the timeout, the sequence stops at that step and the following steps do **not** run — so a mistimed tap can't fire against a screen that never settled.
+
 ### Examples
 
 Scroll down three times:
@@ -293,7 +304,25 @@ Tap a known button, then scroll down:
 }
 ```
 
-Stops on the first error and returns partial results.
+Tap, wait for the next screen, then act on it — the `await-ui-element` step **gates** the tap after it:
+
+```json
+{
+  "udid": "<UDID>",
+  "steps": [
+    { "tool": "gesture-tap", "args": { "x": 0.5, "y": 0.9 } },
+    {
+      "tool": "await-ui-element",
+      "args": { "condition": "visible", "selector": { "text": "Continue" } }
+    },
+    { "tool": "gesture-tap", "args": { "x": 0.5, "y": 0.5 } }
+  ]
+}
+```
+
+Prefer this over a fixed `delayMs` when a step depends on a screen transition: it adapts to real load time, and if the condition is not met before the timeout the sequence **stops there** so the next tap can't fire against a screen that never settled.
+
+Stops on the first error (or unmet `await-ui-element` condition) and returns partial results.
 
 ---
 

package/skills/argent-native-profiler/SKILL.md

@@ -87,7 +87,7 @@ To revisit a previous trace:
 Bottlenecks are categorized by severity:
 
 - **RED**: CPU functions taking >15% of total time, all UI hangs, and **attributed** memory leaks (those with a resolved responsible frame). These require immediate attention.
-- **YELLOW**: CPU functions taking 5-15% of total time, and **unattributed** memory leaks (`<Call stack limit reached>`, no library — see the memory-leaks caveat below). Worth investigating but may be acceptable.
+- **YELLOW**: CPU functions taking 3-15% of total time, and **unattributed** memory leaks (`<Call stack limit reached>`, no library — see the memory-leaks caveat below). Worth investigating but may be acceptable.
 
 Each bottleneck type indicates a different class of problem:
 

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

@@ -29,7 +29,7 @@ For implementation tasks that modify visible UI, this workflow can also serve as
    - **Permission prompts / system modal overlays**: try `describe` first. Fall back to `screenshot` only if the overlay is not exposed reliably.
    - **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, retake with normal downscaled `screenshot`. Pick evidence by what's being asserted:
+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.
    - **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.
@@ -58,9 +58,9 @@ Steps:
 ```
 1. screenshot → see login screen
 2. gesture-tap { x: 0.5, y: 0.4 }  → tap email field
-3. paste { text: "user@example.com" }
+3. keyboard { text: "user@example.com" }
 4. gesture-tap { x: 0.5, y: 0.55 } → tap password field
-5. paste { text: "password123" }
+5. keyboard { text: "password123" }
 6. gesture-tap { x: 0.5, y: 0.7 }  → tap Login button
 7. screenshot → verify home screen appeared
 ```
@@ -89,11 +89,20 @@ Steps:
 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
+4. describe / screenshot → verify the fetched content rendered
+```
+
 ---
 
 ## 4. Recovery Pattern
 
-- If screenshot shows loading/transition: wait 500ms, retake with `screenshot`.
+- 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.
@@ -101,7 +110,7 @@ Steps:
 
 ## Tips
 
-- **Use `paste` for text entry on iOS** — faster and more reliable than key-by-key `keyboard`. `paste` is iOS-only; on Android use `keyboard` instead.
+- **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.

package/skills/argent-vega/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: argent-vega
+description: Control and inspect Amazon Fire TV (Vega) apps via argent — launch/restart/reinstall apps, read the on-screen element tree, navigate with the D-pad remote, type, and screenshot. Use when the task mentions Vega, Fire TV, or VVD, or involves driving a Vega virtual device.
+---
+
+# Argent Vega (Amazon Fire TV)
+
+## Critical
+
+- Vega is a TV platform
+- **D-pad only.** Drive every interaction with `tv-remote`. Never use `gesture-*` / touch — they are unsupported on Vega.
+- **Always `describe` before navigating.** Find the live cursor from the tree — the `[focused]` element, or `[selected]` when nothing reports `[focused]` (the toolkit often marks the highlighted item `[selected]` while `focused` stays false). Never guess focus position from a screenshot.
+- All tools take the Vega `serial` (from `list-devices`) as `udid`.
+
+## The navigation loop
+
+Per screen, two calls:
+
+1. `describe` — find the cursor (`[focused]`, or `[selected]` if no `[focused]`) and your target.
+2. Compute the full D-pad path from focus → target (count rows/columns from the frames) and fire it as **one** `tv-remote {button:[...]}` ending in `select`.
+
+Then `describe` again to confirm. On a miss, run the loop again.
+
+## Tools
+
+### Device lifecycle
+
+- `list-devices` → Vega devices appear with a `serial` (use as `udid`) and a `vvdImage`. Start here to get both.
+- `boot-device {vvdImage}` — starts the single SDK-managed VVD (e.g. `vvdImage:"tv"`) and returns its `serial`. Skip if `list-devices` already shows a running device.
+- **Stopping the VVD** — run `vega virtual-device stop` in your shell.
+
+### App lifecycle
+
+- `launch-app {udid, bundleId}` — `bundleId` = interactive component app id from manifest.toml (e.g. `com.example.app.main`)
+- `restart-app {udid, bundleId}` — terminate + launch
+- `reinstall-app {udid, bundleId, appPath}` — uninstall + install; `appPath` = a `.vpkg`
+- `describe {udid}` → on-screen element tree. The discovery tool — call before navigating
+- `tv-remote {udid, button}` — D-pad; single key, path array, or `repeat`
+- `keyboard {udid, text}` or `{udid, key:"enter"}` — focus the field with the D-pad first
+- `screenshot {udid, scale?}` — captured host-side via `adb`
+
+### `describe`
+
+Nested element tree from the on-device automation toolkit — each line is a `button`/`text`/`image` with its label, `id` (test_id), `[clickable]`, and **`[focused]`/`[selected]`** + a normalized [0,1] frame. `[focused]` is the live D-pad cursor when present; in practice the toolkit usually leaves `focused` false and marks the highlighted item `[selected]`, so treat `[selected]` as the cursor whenever no element reports `[focused]`. Navigate on the tree alone. If the tree comes back empty → `restart-app` and retry.
+
+### `tv-remote`
+
+`button` is a single key **or a whole path**. Keys: `up`/`down`/`left`/`right`, `select`, `back`, `home`, `menu`, `playPause`, `rewind`, `fastForward`. Single: `{button:"down"}`. Repeat one key: `{button:"down", repeat:3}`. Whole path in one call: `{button:["up","right","right","select"]}` — strongly prefer this for any multi-step move.
+
+## Fast Refresh
+
+Needs a Debug build + Metro running. argent only connects to Metro — it does not start Metro or port-forward (any platform); do these in your shell.
+
+1. Build a **Debug** `.vpkg` and install it: `vega device install-app -p <path/to/debug.vpkg>`
+2. `npm start` (Metro on :8081; use `npm start`, not `npx react-native start`)
+3. `vega device start-port-forwarding --port 8081 --forward false` (reverse)
+4. `vega device launch-app -a <appId>`
+
+Metro must be up before launch; confirm `http://localhost:8081/json/list` lists a `Hermes React Native` target. Then `.tsx` edits hot-reload live.
+
+## Troubleshooting
+
+- **`describe` returns an empty tree** → `restart-app` (the automation toolkit attaches at launch), then retry.
+- **Keyboard / D-pad input is ignored** → enable developer mode inside the VVD: `vsm developer-mode enable`.
+- **Editing `node_modules` has no effect** → you are on a Release build. Release Vega apps load JavaScript and native code split and stored on device, so patching `node_modules` only works in Debug builds.
+
+## Platform notes
+
+- Metro connects only on port **8081** — fixed, cannot be changed.
+- Profiling / crashes → use the `amazon-devices-buildertools-mcp` server (`analyze_perfetto_traces`, `get_app_hot_functions`, `symbolicate_acr`).
+- Unsupported tools, with the Vega equivalent: `gesture-*` → use `tv-remote`; `open-url` → not wired; `debugger-*` → JS debugger not supported on Vega. These fail with `Tool '<id>' is not supported on vega vvd.` (or `... is not yet implemented on vega.`).
+
+## Knowledgebase
+
+- Search Vega docs with the `search_documentation` tool (`amazon-devices-buildertools-mcp` server).
+- Community Q&A at community.amazondeveloper.com.