@swmansion/argent 0.5.1

package/skills/argent-react-native-profiler/references/diagnostic-tools.md

@@ -0,0 +1,94 @@
+# Diagnostic Tools
+
+These tools can be called independently without starting a profiling session.
+
+## Live render stats
+
+```json
+{ "port": 8081, "device_id": "<UDID>", "top_n": 20 }
+```
+
+Call `react-profiler-renders`. Returns render counts and durations per component — useful for spotting hot components before a full profile.
+
+## Component hierarchy
+
+```json
+{ "port": 8081, "device_id": "<UDID>", "max_depth": 10, "filter": "MyComponent" }
+```
+
+Call `react-profiler-fiber-tree`. Inspect `useMemoCache` presence to confirm React Compiler is active for a given component. If `useMemoCache` is absent, the compiler bailed out for that component — memoization hints are safe to propose.
+
+## Console logs
+
+```json
+{ "port": 8081, "device_id": "<UDID>" }
+```
+
+Call `debugger-log-registry`. Returns a summary with entry counts by level, message clusters, and the log file path. Use `Grep`/`Read` on the log file to filter by level or search for specific messages.
+
+---
+
+# Post-Analysis Query Tools
+
+These require a completed profiling session (`react-profiler-stop` + `react-profiler-analyze`).
+
+## CPU query (replaces react-profiler-cpu-summary)
+
+```json
+{ "port": 8081, "device_id": "<UDID>", "mode": "top_functions", "top_n": 15 }
+```
+
+Call `profiler-cpu-query`. Modes:
+
+- `top_functions` — global CPU hotspots. Add `time_window_ms: { start, end }` to filter.
+- `time_window` — CPU breakdown for a specific time range (e.g. during a slow commit).
+- `call_tree` — callers and callees of a specific `function_name`.
+- `component_cpu` — aggregate CPU during all commits of a `component_name`.
+
+## Commit query
+
+```json
+{ "port": 8081, "device_id": "<UDID>", "mode": "by_component", "component_name": "AppNavigator" }
+```
+
+Call `profiler-commit-query`. Modes:
+
+- `by_component` — all commits where a component rendered.
+- `by_time_range` — commits in a `time_range_ms` window.
+- `by_index` — full detail of a single `commit_index`.
+- `cascade_tree` — parent-child re-render cascade for a commit.
+
+## iOS Instruments query
+
+```json
+{ "device_id": "<UDID>", "mode": "hang_stacks", "hang_index": 0 }
+```
+
+Call `profiler-stack-query` after `ios-profiler-analyze`. Modes:
+
+- `hang_stacks` — full CPU context during a specific hang.
+- `function_callers` — who calls a specific native `function_name`.
+- `thread_breakdown` — CPU time split by thread, optionally filtered.
+- `leak_stacks` — memory leak details, optionally filtered by `object_type`.
+
+## Combined report
+
+```json
+{ "port": 8081, "device_id": "<UDID>" }
+```
+
+Call `profiler-combined-report` when both React Profiler and iOS Instruments ran in parallel. Automatically correlates iOS hangs with React commits using wall-clock time alignment.
+
+## Session reload
+
+```json
+{ "mode": "list" }
+```
+
+Call `profiler-load`. Modes:
+
+- `list` — show all saved profiling sessions (React + iOS) in `/tmp/argent-profiler-cwd/`.
+- `load_react` — reload a React profiler session by `session_id` + `device_id`. Populates the `port:device_id`-keyed in-memory cache for `profiler-cpu-query` and `profiler-commit-query` (which must be called with the same `device_id` afterward).
+- `load_instruments` — re-parse iOS Instruments XML by `session_id` and `device_id`. Populates session for `profiler-stack-query`.
+
+Use this to revisit an earlier profiling session without re-profiling. Each `react-profiler-analyze` run saves raw data with a unique timestamp.

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

@@ -0,0 +1,272 @@
+---
+name: argent-simulator-interact
+description: Interact with an iOS simulator using argent MCP tools. Use when tapping UI elements, perfroming gestures, scrolling, typing text, pressing hardware buttons, launching apps, opening URLs, taking screenshots.
+---
+
+## 1. Before You Start
+
+If you delegate simulator tasks to sub-agents, make sure they have MCP permissions.
+
+Use `list-simulators` to find available simulators. **Pick the first result** if specific not specified by user — booted iPhones are listed first. If none are booted, use `boot-simulator` first.
+
+**Load tool schemas before first use.** Gesture tools (`gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`) may be deferred — their parameter schemas are not loaded until fetched. Always use ToolSearch to load the schemas of all gesture tools you plan to use **before** calling any of them. If you skip this step, parameters may be coerced to strings instead of numbers, causing validation errors.
+
+## 2. Best Practices
+
+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. Consider whether you need multiple swipes, if yes - use `run-sequence`.
+4. **Tap a text field before typing** — try `paste` first, fall back to `keyboard`.
+5. **Coordinates are normalized** — always 0.0–1.0, not pixels.
+6. **For native iOS 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.
+
+## 3. Opening Apps
+
+**Never navigate to an app by tapping home-screen icons.** Use `launch-app` or `open-url` — they are instant and reliable.
+
+### launch-app — by bundle ID
+
+```json
+{ "udid": "<UDID>", "bundleId": "com.apple.MobileSMS" }
+```
+
+Common IDs: `com.apple.MobileSMS` (Messages), `com.apple.mobilesafari` (Safari), `com.apple.Preferences` (Settings), `com.apple.Maps`, `com.apple.Photos`, `com.apple.mobilemail`, `com.apple.mobilenotes`, `com.apple.MobileAddressBook` (Contacts)
+
+### open-url — by URL scheme
+
+```json
+{ "udid": "<UDID>", "url": "messages://" }
+```
+
+Common schemes: `messages://`, `settings://`, `maps://?q=<query>`, `tel://<number>`, `mailto:<address>`, `https://...` (Safari)
+
+## 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                             |
+| 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`          | Form fields — uses clipboard                              |
+| Type text        | `keyboard`       | Fallback when paste fails; supports Enter, Escape, arrows |
+| Rotate device    | `rotate`         | Orientation changes                                       |
+
+## 5. Finding Tap Targets
+
+IMPORTANT. When moved to a different screen after an action or do not know the coordinates of component, **always** perform proper discovery first.
+
+| App type                          | Discovery tool            | What it returns                                                                                                                                                                          |
+| --------------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Target app discovery              | `describe`                | Accessibility element tree for the current simulator screen with normalized frame coordinates. Works on any app, system dialogs, and Home screen — no app restart or `bundleId` required |
+| React Native                      | `debugger-component-tree` | React component tree with names, text, testID, and (tap: x,y)                                                                                                                            |
+| App-scoped native                 | `native-describe-screen`  | Low-level app-scoped accessibility elements with normalized and raw coordinates; requires `bundleId`                                                                                     |
+| Permission / system modal overlay | `describe`                | `describe` detects system dialogs automatically and returns dialog buttons with tap coordinates. Fall back to `screenshot` only if `describe` does not expose the controls               |
+| Final visual fallback             | `screenshot`              | Use only when discovery tools cannot inspect the current UI reliably. Do not derive routine in-app navigation targets from screenshots                                                   |
+
+Point follow-up native diagnostics after you already have a candidate point:
+
+- `native-user-interactable-view-at-point`: deepest native view that would receive touch at a known raw iOS point; requires `bundleId`
+- `native-view-at-point`: deepest visible native view at a known raw iOS point; requires `bundleId`
+
+### If `describe` Fails
+
+Read the exact error and choose the action that matches it:
+
+- Error mentions `ax-service` not available or daemon startup failure:
+  the ax-service daemon could not start. Check that the simulator is booted. Use `screenshot` as a temporary fallback, or use `native-describe-screen` with an explicit `bundleId` if the app has native devtools injected.
+- `describe` returns an empty element list:
+  the screen may be blank, loading, or showing content without accessibility labels. Use `screenshot` to see what is visible, then retry after the content has loaded.
+- `describe` succeeds but is not detailed enough for a React Native app:
+  use `debugger-component-tree` next.
+- You need app-scoped inspection with full UIKit properties (`accessibilityIdentifier`, `viewClassName`):
+  use `native-describe-screen` with an explicit `bundleId`. This requires native devtools (dylib) injection — call `restart-app` first if needed.
+- You already have a candidate point and want to confirm what would actually receive touch:
+  use `native-user-interactable-view-at-point`. Use `native-view-at-point` when you want the visually deepest view instead of the hit-test target.
+
+## 6. Tool Usage
+
+### gesture-tap — Single tap at a point
+
+```json
+{ "udid": "<UDID>", "x": 0.5, "y": 0.5 }
+```
+
+Coordinates: `0.0` = left/top, `1.0` = right/bottom.
+
+Before tapping near the bottom of the screen in React Native apps, check that "Open Debugger to View Warnings" banners are not visible — tapping them breaks the debugger connection. Close them with the X icon if present.
+
+### gesture-swipe — Straight-line gesture
+
+```json
+{ "udid": "<UDID>", "fromX": 0.5, "fromY": 0.7, "toX": 0.5, "toY": 0.3 }
+```
+
+Swipe **up** (`fromY > toY`) = scroll content **down**. Default duration: 300ms. Optional: `"durationMs": 500` for slower swipe.
+
+### gesture-pinch — Two-finger pinch
+
+```json
+{ "udid": "<UDID>", "centerX": 0.5, "centerY": 0.5, "startDistance": 0.2, "endDistance": 0.6 }
+```
+
+All values are normalized 0.0–1.0 (fractions of screen, not pixels) — same as all other gesture tools. `startDistance: 0.2` means fingers start 20% of the screen apart; `endDistance: 0.6` means they end 60% apart. `startDistance < endDistance` = pinch out (zoom in). `startDistance > endDistance` = pinch in (zoom out). Defaults: `angle: 0` (horizontal), `durationMs: 300`. Optional: `"angle": 90` for vertical axis, `"durationMs": 500` for slower pinch.
+
+### gesture-rotate — Two-finger rotation
+
+```json
+{
+  "udid": "<UDID>",
+  "centerX": 0.5,
+  "centerY": 0.5,
+  "radius": 0.15,
+  "startAngle": 0,
+  "endAngle": 90
+}
+```
+
+All positions and radius are normalized 0.0–1.0 (fractions of screen, not pixels). `radius: 0.15` means each finger is 15% of the screen away from center. `endAngle > startAngle` = clockwise. Default duration: 300ms. Optional: `"durationMs": 500` for slower rotation.
+
+### gesture-custom — Custom touch sequence
+
+For long-press, drag-and-drop, and other complex sequences, see `references/gesture-examples.md`. Set `"interpolate": 10` to auto-generate smooth intermediate Move events between keyframes.
+
+### button — Hardware button press
+
+```json
+{ "udid": "<UDID>", "button": "home" }
+```
+
+Values: `home`, `back`, `power`, `volumeUp`, `volumeDown`, `appSwitch`, `actionButton`
+
+### paste — Type text into focused field
+
+```json
+{ "udid": "<UDID>", "text": "Hello, world!" }
+```
+
+Tap the field first, then paste. Fall back to `keyboard` if it doesn't work.
+
+### keyboard — Type text or press special keys
+
+```json
+{ "udid": "<UDID>", "text": "search query", "key": "enter" }
+```
+
+Special keys: `enter`, `escape`, `backspace`, `tab`, `space`, `arrow-up`, `arrow-down`, `arrow-left`, `arrow-right`, `f1`–`f12`. Optional: `"delayMs": 100` between keystrokes (default 50ms).
+
+### rotate — Change orientation
+
+```json
+{ "udid": "<UDID>", "orientation": "LandscapeLeft" }
+```
+
+Values: `Portrait`, `LandscapeLeft`, `LandscapeRight`, `PortraitUpsideDown`
+
+---
+
+## 7. Screenshots
+
+Use the explicit `screenshot` tool only when:
+
+- You need the initial screen state before any action.
+- The auto-attached screenshot shows a transitional or loading frame.
+- You require extra context.
+- You want to check state after a delay (e.g. waiting for a network response).
+- A permission dialog, system alert, or native modal overlay is visible and `describe` did not expose reliable targets.
+
+When using `screenshot` for permission or native modal navigation:
+
+- Do not switch to screenshot-driven navigation just because a modal is visible. On regular app screens and in-app modals, keep using `describe`.
+- Prefer obvious, centered alert buttons such as `Allow`, `OK`, `Don't Allow`, `Not Now`, or `Continue`.
+- Tap one control at a time and inspect the returned auto-screenshot before doing anything else.
+- After the modal is dismissed, return to normal discovery with `describe`, `native-describe-screen`, or `debugger-component-tree`.
+
+Optional rotation parameter: `{ "udid": "<UDID>", "rotation": "LandscapeLeft" }` — rotates the capture without changing simulator orientation.
+
+Screenshots are downscaled by default (30% of original resolution) to reduce context size. `scale` accepts values from 0.01 to 1.0. If UI elements are hard to read or you need to inspect fine detail, pass `scale: 1.0` to get full resolution: `{ "udid": "<UDID>", "scale": 1.0 }`.
+
+### Troubleshooting
+
+| Problem              | Solution                                                      |
+| -------------------- | ------------------------------------------------------------- |
+| Screenshot times out | Restart the simulator-server via `stop-simulator-server` tool |
+| No booted simulator  | Run `boot-simulator` first.                                   |
+
+---
+
+## 8. Action Sequencing with `run-sequence`
+
+Use `run-sequence` to batch multiple interaction steps into **a single tool call**. Only one screenshot is returned — after all steps complete. Use cases:
+scrolling multiple times, typing and submitting automatically, known sequence of multiple taps, rotating device back and forth.
+
+Do **not** use `run-sequence` when any step depends on observing the result of a previous step
+
+### Use cases
+
+Use the sequencing when:
+
+- Knowing that some action needs multiple steps without necessarily immediate insight of screenshot
+- "scroll to bottom", "scroll to top", "scroll to do X" -> sequence scroll 3-5 times
+- form interactions, "clear and retype field" -> you may use triple-tap to select all, type new value
+- "submit form" → fill all fields in sequence, tap submit
+- "go back to X" → defined tap sequence for the navigation
+
+### Allowed tools inside `run-sequence`
+
+`gesture-tap`, `gesture-swipe`, `gesture-custom`, `gesture-pinch`, `gesture-rotate`, `button`, `keyboard`, `rotate`
+
+The `udid` is shared — do **not** include it in each step's `args`. Optional `delayMs` per step (default 100ms).
+
+### Examples
+
+Scroll down three times:
+
+```json
+{
+  "udid": "<UDID>",
+  "steps": [
+    { "tool": "gesture-swipe", "args": { "fromX": 0.5, "fromY": 0.7, "toX": 0.5, "toY": 0.3 } },
+    { "tool": "gesture-swipe", "args": { "fromX": 0.5, "fromY": 0.7, "toX": 0.5, "toY": 0.3 } },
+    { "tool": "gesture-swipe", "args": { "fromX": 0.5, "fromY": 0.7, "toX": 0.5, "toY": 0.3 } }
+  ]
+}
+```
+
+Type into a focused field and submit:
+
+```json
+{
+  "udid": "<UDID>",
+  "steps": [
+    { "tool": "keyboard", "args": { "text": "hello world" } },
+    { "tool": "keyboard", "args": { "key": "enter" } }
+  ]
+}
+```
+
+Tap a known button, then scroll down:
+
+```json
+{
+  "udid": "<UDID>",
+  "steps": [
+    { "tool": "gesture-tap", "args": { "x": 0.5, "y": 0.15 } },
+    {
+      "tool": "gesture-swipe",
+      "args": { "fromX": 0.5, "fromY": 0.7, "toX": 0.5, "toY": 0.3 },
+      "delayMs": 300
+    }
+  ]
+}
+```
+
+Stops on the first error and returns partial results.

package/skills/argent-simulator-interact/references/gesture-examples.md

@@ -0,0 +1,114 @@
+# Gesture Examples
+
+Detailed sequences and parameters for the gesture tool family. All coordinates, distances, and radii are **normalized 0.0–1.0** (fractions of screen width/height, not pixels) — same coordinate space across all gesture tools.
+
+## gesture-pinch — Two-finger pinch
+
+Pinch out (zoom in):
+
+```json
+{ "udid": "<UDID>", "centerX": 0.5, "centerY": 0.5, "startDistance": 0.2, "endDistance": 0.6 }
+```
+
+Pinch in (zoom out):
+
+```json
+{ "udid": "<UDID>", "centerX": 0.5, "centerY": 0.5, "startDistance": 0.6, "endDistance": 0.2 }
+```
+
+Vertical pinch (angle = 90):
+
+```json
+{
+  "udid": "<UDID>",
+  "centerX": 0.5,
+  "centerY": 0.5,
+  "startDistance": 0.2,
+  "endDistance": 0.6,
+  "angle": 90
+}
+```
+
+## gesture-rotate — Two-finger rotation
+
+Clockwise 90 degrees:
+
+```json
+{
+  "udid": "<UDID>",
+  "centerX": 0.5,
+  "centerY": 0.5,
+  "radius": 0.15,
+  "startAngle": 0,
+  "endAngle": 90
+}
+```
+
+Counter-clockwise 45 degrees:
+
+```json
+{
+  "udid": "<UDID>",
+  "centerX": 0.5,
+  "centerY": 0.5,
+  "radius": 0.15,
+  "startAngle": 0,
+  "endAngle": -45
+}
+```
+
+## gesture-custom — Custom touch sequences
+
+### Long Press (800ms hold)
+
+```json
+{
+  "udid": "<UDID>",
+  "events": [
+    { "type": "Down", "x": 0.5, "y": 0.5 },
+    { "type": "Up", "x": 0.5, "y": 0.5, "delayMs": 800 }
+  ]
+}
+```
+
+### Pinch Out (zoom in) — manual events
+
+```json
+{
+  "udid": "<UDID>",
+  "events": [
+    { "type": "Down", "x": 0.4, "y": 0.5, "x2": 0.6, "y2": 0.5 },
+    { "type": "Move", "x": 0.2, "y": 0.5, "x2": 0.8, "y2": 0.5 },
+    { "type": "Up", "x": 0.2, "y": 0.5, "x2": 0.8, "y2": 0.5 }
+  ]
+}
+```
+
+### Pinch Out with interpolation — smooth version
+
+```json
+{
+  "udid": "<UDID>",
+  "events": [
+    { "type": "Down", "x": 0.4, "y": 0.5, "x2": 0.6, "y2": 0.5 },
+    { "type": "Up", "x": 0.2, "y": 0.5, "x2": 0.8, "y2": 0.5 }
+  ],
+  "interpolate": 15
+}
+```
+
+### Drag and Drop
+
+```json
+{
+  "udid": "<UDID>",
+  "events": [
+    { "type": "Down", "x": 0.3, "y": 0.4 },
+    { "type": "Move", "x": 0.3, "y": 0.4, "delayMs": 500 },
+    { "type": "Move", "x": 0.7, "y": 0.6 },
+    { "type": "Up", "x": 0.7, "y": 0.6 }
+  ]
+}
+```
+
+Add a `delayMs` on the first `Move` to simulate a hold before dragging — this is required for some drag-and-drop implementations that only activate after a sustained press.

package/skills/argent-simulator-setup/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: argent-simulator-setup
+description: Set up and connect to an iOS simulator using argent MCP tools. Use when starting a new session, booting a simulator, getting a simulator UDID, or before any simulator interaction task.
+---
+
+## 1. Setup Steps
+
+If you delegate simulator tasks to sub-agents, make sure they have MCP permissions.
+
+1. **Find a booted simulator**
+   Use `list-simulators`. Pick the first result — booted iPhones are listed first.
+   If none are booted, use `boot-simulator` with the desired UDID.
+
+2. **Verify connection**
+   All interaction tools (`gesture-tap`, `gesture-swipe`, `gesture-custom`, etc.) auto-start the server if not already running.
+
+## 2. Notes
+
+- UDIDs look like: `A1B2C3D4-E5F6-7890-ABCD-EF1234567890`

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

@@ -0,0 +1,84 @@
+---
+name: argent-test-ui-flow
+description: Autonomously test an iOS app UI by running interact-screenshot-verify loops using argent simulator tools. Use when testing a UI flow, verifying login works, testing navigation, or running an end-to-end UI test scenario.
+---
+
+## 1. Workflow
+
+All interactions go through argent MCP tools. Ensure the simulator is booted before starting.
+
+1. **Baseline screenshot**: Call `screenshot` to see the current UI state.
+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. To use it, resolve the `argent-react-native-app-workflow` skill for setup.
+   - **Standard iOS app screens and in-app modals**: use `describe` — it returns the accessibility element tree with normalized frame coordinates.
+   - **Permission prompts / system modal overlays**: still 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`, `paste`, etc.) — you receive a screenshot automatically.
+4. **Verify**: Check the returned screenshot for expected results. If it shows a loading/transitional state, retake with `screenshot`.
+5. **Repeat** for each step in the flow.
+
+## 2. Template
+
+```
+Goal: Test [feature name]
+
+Steps:
+1. screenshot → see current state (baseline)
+2. [Navigate / tap / type to reach starting point] → verify auto-screenshot
+3. [Perform the action to test] → verify auto-screenshot
+4. Report: pass / fail with details
+```
+
+## 3. Examples
+
+### Login flow
+
+```
+1. screenshot → see login screen
+2. gesture-tap { x: 0.5, y: 0.4 }  → tap email field
+3. paste { text: "user@example.com" }
+4. gesture-tap { x: 0.5, y: 0.55 } → tap password field
+5. paste { text: "password123" }
+6. gesture-tap { x: 0.5, y: 0.7 }  → tap Login button
+7. screenshot → verify home screen appeared
+```
+
+### 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
+```
+
+---
+
+## 4. Recovery Pattern
+
+- If screenshot shows loading/transition: wait 500ms, retake with `screenshot`.
+- 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 flow** fails during `flow-execute` replay (as opposed to live test steps above): follow `argent-create-flow` skill §10 for structured diagnosis and correction.
+
+## Tips
+
+- **Use `paste` for text entry** — faster and more reliable than key-by-key `keyboard`.
+- **Use `gesture-custom` for long-press** context menus (800ms hold).
+- **Report clearly**: state what you expected, what you saw, and the verdict.
+- **Coordinate estimation**: center = 0.5, 0.5; top-third ~ 0.2; bottom-third ~ 0.8.
+- **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-flow` skill to record it as a `.yaml` script. This lets you replay the entire sequence later with a single `flow-execute` call instead of re-running each step manually.
+
+## Related Skills
+
+| Skill                              | When to use                                      |
+| ---------------------------------- | ------------------------------------------------ |
+| `argent-simulator-interact`        | Detailed tool usage for tapping, swiping, typing |
+| `argent-simulator-setup`           | Booting and connecting a simulator               |
+| `argent-react-native-app-workflow` | Starting the app, Metro, build issues            |
+| `argent-metro-debugger`            | Breakpoints, console logs, JS evaluation         |
+| `argent-create-flow`               | Record a test sequence as a replayable flow      |