@swmansion/argent 0.5.1

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@swmansion/argent",
+  "version": "0.5.1",
+  "description": "MCP server for iOS Simulator control",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/software-mansion/argent.git"
+  },
+  "type": "module",
+  "bin": {
+    "argent": "dist/cli.js",
+    "argent-simulator-server": "bin/simulator-server"
+  },
+  "scripts": {
+    "build": "npm run build:mcp && npm run build:tools-bundle && npm run sync-readme",
+    "build:mcp": "rm -rf dist tsconfig.tsbuildinfo && tsc",
+    "sync-readme": "node scripts/sync-readme.cjs",
+    "prepack": "node scripts/sync-readme.cjs",
+    "build:tools-bundle": "node scripts/bundle-tools.cjs",
+    "dev": "node --loader ts-node/esm src/cli.ts mcp",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "observe": "node scripts/observe.cjs",
+    "benchmark": "node scripts/benchmark.cjs",
+    "postinstall": "node scripts/postinstall.cjs"
+  },
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "dylibs/",
+    "skills/",
+    "agents/",
+    "rules/",
+    "scripts/postinstall.cjs"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "picocolors": "^1.1.1",
+    "smol-toml": "^1.6.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.27.3",
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.18"
+  }
+}

package/rules/argent.md

@@ -0,0 +1,121 @@
+---
+description: Argent iOS Simulator Agent — always-on guidance for methodology and tools for working with, interacting, testing and profiling mobile app work
+alwaysApply: true
+---
+
+<description>
+Argent MCP tools are available in this project for iOS simulator control. Argent MCP tools are the preferred form of interaction with the application.
+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.
+
+Use cases:
+
+- User mentions iOS simulator, device, or app interaction
+- The app user is working with is a mobile application which can be run in the simulator
+- Any tapping, swiping, typing, screenshotting, or inspecting a running app
+- Running, debugging, or testing a React Native app
+- Profiling performance or diagnosing re-renders in a React Native app
+  </description>
+
+<tapping_rule>
+<important>**Never** derive tap coordinates from a screenshot</important>
+Before **every** tap, you MUST call a discovery tool and extract coordinates from the result. This is not optional. Preferred tools are, in order:
+
+- `describe` - native app-level components and safely targetable foreground apps.
+- `native-describe-screen` - accessibility screen description via injected native devtools
+- `debugger-component-tree` - react-native specific components
+
+`native-user-interactable-view-at-point` / `native-view-at-point` are follow-up diagnostics once you already have a candidate point.
+
+Whenever something changed YOU MUST first call `describe`, or another appropriate discovery tool so you do not hallucinate element positions. Do not guess coordinates if you can use discovery tool. Do not tap if you have not called a discovery tool in the current step. Screenshots alone are never sufficient for coordinates.
+
+If a **tap fails twice** at the same coordinates, **stop retrying**. Re-run the discovery tool.
+
+If `describe` fails, **read the exact error before reacting**, follow the recovery guidance in `argent-simulator-interact` to choose the correct next action.
+
+Before starting to interact with the app, read the `argent-simulator-interact` skill first.
+</tapping_rule>
+
+<skill_reading_rule>
+<important>Always read relevant skills for guidance before executing argent-mcp tool - read skill_routing reference</important>
+</skill_reading_rule>
+
+<general_rules>
+
+- All simulator interactions go through argent MCP tools — never use `xcrun simctl`,
+  raw `curl` to simulator ports, or the simulator-server binary directly.
+- Before calling any gesture tool for the first time, use ToolSearch to load its schema.
+- Interaction tools (`gesture-tap`, `gesture-swipe`, `gesture-pinch`, `gesture-rotate`, `gesture-custom`, `launch-app`, etc.) return a screenshot automatically.
+  Call `screenshot` separately only for a baseline before any action or after a delay.
+- Always open apps with `launch-app` or `open-url` — never tap home screen icons.
+- Always use `run-sequence` when performing multiple sequential simulator actions where you don't need to observe the screen between steps. More in `simulator-interact` skill.
+- 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` or other commands, use the command. Examples: changing simulator options, performing simulator 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.
+  </general_rules>
+
+<react_native_detection>
+Project type is determined by the `argent-environment-inspector` subagent (see `subagents` section).
+When the subagent result is available, use its `is_react_native` field as the authoritative
+source — do not re-inspect files manually.
+
+If the subagent has not run yet and project type is unknown, run it first before proceeding. Always use subagents if available to run `gather-workspace-data` data tool, if possible do not run yourself.
+
+When `is_react_native` is true: load `argent-react-native-app-workflow` skill. Use `debugger-component-tree` for element discovery - if the responses are large or unhelpful, try `describe`.
+</react_native_detection>
+
+<skill_routing>
+Load the matching skill before starting work and executing tools from argent-mcp — skills contain the full step-by-step
+procedure and edge-case handling for each workflow.
+
+SIMULATOR SETUP
+Skill: `argent-simulator-setup`
+When: Beginning a task that involves the simulator, no simulator booted yet, need UDID or simulator-server.
+
+TAPPING, SWIPING, TYPING, GESTURES, SCREENSHOTS, SCROLLING
+Skill: `argent-simulator-interact`
+When: Performing touch interactions, typing, pressing hardware buttons, launching/restarting apps, opening URLs, rotating device, or taking standalone screenshots.
+
+RUNNING / BUILDING / DEBUGGING REACT NATIVE APP
+Skill: `argent-react-native-app-workflow`
+When: Project is react-native, starting Metro or running iOS app, build failures, pod issues, lost Metro connection, reading logs, reloading JS bundle, reinstalling app.
+
+JS EVALUATION, METRO CONNECTION, REACT NATIVE
+Skill: `argent-metro-debugger`
+When: evaluating expressions, inspecting React component tree at source level, finding element placement via `debugger-component-tree`.
+
+REACT APP & COMPONENT PROFILING
+Use skill: `argent-react-native-profiler`
+When: To measure performance of specific components, to find app-wide bottlenecks. Investigating re-renders or CPU hotspots, producing ranked performance reports.
+
+NATIVE iOS PROFILING
+Use skill: `argent-ios-profiler`
+When: Profiling native iOS performance (CPU hotspots, UI hangs, memory leaks via Instruments). Useful as a reference for iOS-specific investigation when running dual profiling via `argent-react-native-profiler`.
+
+PERFORMANCE OPTIMIZATION
+Use skill: `argent-react-native-optimization`
+When: App feels slow, user asks to optimize, reducing bundle size, improving startup time, fixing re-renders, optimizing lists/images/navigation, or any performance-related task. This is the entry-point skill for all performance work — it delegates to `argent-react-native-profiler` for measurement.
+
+END-TO-END UI TESTING
+Skill: `argent-test-ui-flow`
+When: Verifying complete user flows, running interact → screenshot → verify loops, testing features by using the app.
+
+RECORDING & REPLAYING FLOWS
+Use skill: `argent-create-flow`
+When: A multi-step interaction sequence needs to be repeated — re-profiling after a fix, A/B comparisons, regression checks, user says "again" / "run that flow", or you worked through a complex path worth saving. Also use proactively: if you are about to repeat steps you already performed, record first, then replay.
+Prompt keywords: flow, repeat, test X times
+</skill_routing>
+
+<subagents>
+ENVIRONMENT INSPECTION AT SESSION START
+Use subagent: `argent-environment-inspector`
+When:
+- Environment context of the project is not yet known
+- No "Project Environment" section exists in project memory / `MEMORY.md` or you lack information about basic setup workflows
+- Need to determine build commands, startup scripts, metro port, platform support, or QA tooling
+  If the subagent already ran this session (result in memory), use that context directly — do NOT re-run.
+Rules:
+  - Run the `argent-environment-inspector` subagent if possible. Never call `gather-workspace-data` yourself - do only if subagent is not available.
+  - The main agent is responsible for persisting the subagent's JSON result to project memory
+</subagents>

package/scripts/postinstall.cjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+// @ts-check
+"use strict";
+
+// Runs automatically after `npm install @swmansion/argent`.
+// Set ARGENT_SKIP_POSTINSTALL=1 to suppress the init message (used by `argent update`).
+
+const os = require("os");
+const fs = require("fs");
+const path = require("path");
+
+// Always kill any running tool-server so the new binary takes effect on next use.
+const stateFile = path.join(os.homedir(), ".argent", "tool-server.json");
+try {
+  const state = JSON.parse(fs.readFileSync(stateFile, "utf8"));
+  if (state && state.pid) {
+    try {
+      process.kill(state.pid, "SIGTERM");
+    } catch {}
+  }
+  fs.unlinkSync(stateFile);
+} catch {}
+
+if (process.env.ARGENT_SKIP_POSTINSTALL === "1") {
+  process.exit(0);
+}
+
+console.log(`
+@swmansion/argent installed.
+
+To set up your workspace (MCP server, skills, rules), run:
+
+  argent init
+`);

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

@@ -0,0 +1,213 @@
+---
+name: argent-create-flow
+description: Record a reusable flow (scripted sequence of MCP tool calls) that can be replayed later with a single command. Use when the user asks to create, record, or build a flow, or to script a sequence of simulator actions.
+---
+
+## 1. Overview
+
+A flow is a recorded sequence of MCP tool calls saved to a `.yaml` file in the `.argent/flows/` directory. Each step is **executed live** as you add it, so you verify it works before it becomes part of the flow. Replay a finished flow with `flow-execute`.
+
+## 2. Tools
+
+| Tool                     | Purpose                                                                    |
+| ------------------------ | -------------------------------------------------------------------------- |
+| `flow-start-recording`   | Start recording — takes a name and executionPrerequisite, creates the file |
+| `flow-add-step`          | Execute a tool call live and record it if it succeeds                      |
+| `flow-add-echo`          | Add a label/comment that prints during replay                              |
+| `flow-finish-recording`  | Stop recording and get a summary                                           |
+| `flow-read-prerequisite` | Read a flow's execution prerequisite without running it                    |
+| `flow-execute`           | Replay a saved flow by name                                                |
+
+## 3. Workflow
+
+### Recording
+
+1. **Start**: Call `flow-start-recording` with a descriptive name, the absolute `project_root`, and an `executionPrerequisite` describing the required app state before running the flow (e.g. "App on home screen after a fresh reload"). `project_root` is stored for the session — you do **not** need to pass it again to subsequent tools.
+2. **Build step-by-step**: For each action, call `flow-add-step` with the tool name and args. The tool runs immediately — check the result before moving on.
+3. **Add labels**: Use `flow-add-echo` between steps to describe what each section does.
+4. **Finish**: Call `flow-finish-recording` to stop recording. It returns the file path where the flow was saved and a summary of all steps. You can edit the `.yaml` file directly afterwards to remove, reorder, or tweak steps.
+
+Every tool during recording returns the current flow file contents so you can track what has been recorded.
+
+### Replaying
+
+Call `flow-execute` with the flow name. If the flow has an execution prerequisite:
+
+1. The tool returns a **notice** with the prerequisite text instead of running. It asks you to verify the prerequisite is met and call `flow-execute` again with `prerequisiteAcknowledged: true`.
+2. You can also call `flow-read-prerequisite` beforehand to inspect the prerequisite without triggering a run.
+3. Once you pass `prerequisiteAcknowledged: true`, the flow runs all steps in order and returns every tool call result (including screenshots) merged into a single response.
+
+If the flow has no prerequisite, it runs immediately without needing acknowledgment.
+
+## 4. flow-add-step Usage
+
+The `command` parameter is the MCP tool name. The `args` parameter is a **JSON string** (not an object):
+
+```
+command: "launch-app"
+args: "{\"udid\": \"<UDID>\", \"bundleId\": \"com.apple.Preferences\"}"
+```
+
+```
+command: "gesture-tap"
+args: "{\"udid\": \"<UDID>\", \"x\": 0.5, \"y\": 0.35}"
+```
+
+```
+command: "screenshot"
+args: "{\"udid\": \"<UDID>\"}"
+```
+
+For tools with no arguments, omit `args` entirely.
+
+## 5. Important Rules
+
+- **Every step runs live.** You will see the real tool result (including screenshots). Use this to verify the step worked before continuing.
+- **Only successful steps are recorded.** If a tool call fails, nothing is written to the flow file — fix the issue and try again.
+- **Pass `project_root` only to `flow-start-recording`.** It is stored for the session and automatically used by all subsequent flow tools. An error is returned if the path is not absolute.
+- **You do NOT need to pass a flow name** to `flow-add-step`, `flow-add-echo`, or `flow-finish-recording`. The active flow is tracked automatically after `flow-start-recording`.
+- **Start before adding.** Calling `flow-add-step`, `flow-add-echo`, or `flow-finish-recording` without an active recording returns an error: _"No active flow. Call flow-start-recording first."_
+- **One flow at a time.** If you call `flow-start-recording` while already recording, the active flow switches to the new one. The response tells you which flow was abandoned and which is now active. The old flow's file remains on disk.
+- **Mistakes can be edited out.** If a step was recorded by mistake, edit the `.yaml` file directly to remove or reorder entries.
+
+## 6. Example Session
+
+```
+flow-start-recording  { name: "open-settings", project_root: "/Users/dev/MyApp", executionPrerequisite: "Simulator booted with app installed" }
+flow-add-echo  { message: "Launch Settings app" }
+flow-add-step  { command: "launch-app", args: "{\"udid\": \"ABC\", \"bundleId\": \"com.apple.Preferences\"}" }
+flow-add-echo  { message: "Tap General" }
+flow-add-step  { command: "gesture-tap", args: "{\"udid\": \"ABC\", \"x\": 0.5, \"y\": 0.35}" }
+flow-add-echo  { message: "Tap About" }
+flow-add-step  { command: "gesture-tap", args: "{\"udid\": \"ABC\", \"x\": 0.5, \"y\": 0.17}" }
+flow-finish-recording  {}
+```
+
+## 7. Replay Example
+
+```
+flow-execute   { name: "open-settings", project_root: "/Users/dev/MyApp" }
+→ Returns: notice with executionPrerequisite: "Simulator booted with app installed"
+  "Verify the prerequisite is met and call flow-execute again with prerequisiteAcknowledged set to true."
+
+flow-execute   { name: "open-settings", project_root: "/Users/dev/MyApp", prerequisiteAcknowledged: true }
+→ Runs all steps, returns merged results with status and output for every step
+```
+
+## 8. Flow File Format
+
+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
+
+Example `.yaml` file:
+
+```yaml
+executionPrerequisite: Simulator booted with app installed
+steps:
+  - echo: Launch Settings app
+  - tool: launch-app
+    args:
+      udid: ABC
+      bundleId: com.apple.Preferences
+  - echo: Tap General
+  - tool: gesture-tap
+    args:
+      udid: ABC
+      x: 0.5
+      y: 0.35
+  - echo: Tap About
+  - tool: gesture-tap
+    args:
+      udid: ABC
+      x: 0.5
+      y: 0.17
+```
+
+## 9. When to Proactively Record a Flow
+
+You do not need the user to ask for a flow. Record one proactively when you recognize any of these patterns:
+
+- **About to re-profile**: You completed a profiling session and are about to apply a fix and re-profile. Record the interaction steps now so the re-profile replays them identically (see `argent-react-native-profiler` and `argent-ios-profiler` skills).
+- **Repeating steps**: You have already performed a multi-step interaction sequence once and the task requires doing it again (comparison, retry, re-test).
+- **Complex path discovered**: You worked through a non-trivial sequence of taps/swipes/navigation to reach a desired app state. Capture it before it is lost.
+- **User says "again" / "one more time"**: Any request to redo what you just did is a signal to record first, then replay.
+
+## 10. Flow Self-Improvement
+
+Flows break. UI layouts change, coordinates drift, screens get added or removed. When `flow-execute` returns a failure, follow this procedure to diagnose and fix the flow instead of silently re-recording or giving up.
+
+### 10.1 Classify the Result
+
+After every `flow-execute`, classify the outcome before proceeding:
+
+| Outcome                | Signal                                                                | Action             |
+| ---------------------- | --------------------------------------------------------------------- | ------------------ |
+| **Success**            | All steps completed, final screenshot shows expected state            | Continue with task |
+| **Hard error**         | A step has `ERROR` in the result — engine stopped there               | Enter §10.2        |
+| **Silent misfire**     | All steps completed but final screenshot shows wrong screen           | Enter §10.2        |
+| **Partial divergence** | Intermediate screenshot shows wrong state even though later steps ran | Enter §10.2        |
+
+For silent misfires and partial divergence, echo annotations (§10.5) are your reference for what each screen _should_ look like.
+
+### 10.2 Diagnose
+
+1. Note the failure step index and error message (if hard error).
+2. Call `screenshot` to see where the app actually is now.
+3. Call `describe` or `debugger-component-tree` to get the current element tree.
+4. Compare current state to what the failed step expected. Classify the root cause:
+
+| Root cause       | Symptoms                                                        |
+| ---------------- | --------------------------------------------------------------- |
+| Coordinate drift | Tap succeeded but hit wrong element; elements shifted positions |
+| Missing element  | Target element not present in element tree                      |
+| Wrong screen     | Screenshot shows entirely different page than expected          |
+| Timing           | Element exists in tree but tap missed; loading spinner visible  |
+| State mismatch   | First step fails — executionPrerequisite was not actually met   |
+
+5. State the diagnosis in one sentence before attempting any correction.
+
+### 10.3 Correct
+
+Choose the lightest strategy that fits:
+
+**Strategy 1 — Edit the YAML** (coordinate drift, parameter changes).
+Read `.argent/flows/<flow-name>.yaml`, update the broken step's `x`/`y`, `bundleId`, `text`, or other args. Re-run `flow-execute` to verify.
+
+**Strategy 2 — Manual recovery + continue** (timing/transient issues, one-off replay).
+Manually execute the failed step with corrected coordinates from §10.2 discovery, then manually execute remaining steps. Does not fix the YAML — use only when re-recording is not worth it.
+
+**Strategy 3 — Re-record from failure point** (structural changes, new intermediate screens).
+Navigate the app to the state just before the failure point. Call `flow-start-recording` with the same flow name (overwrites). Re-add the working prefix steps via `flow-add-step`, then continue recording new steps from the divergence point. Call `flow-finish-recording`.
+
+**Strategy 4 — Full re-record** (major changes, unclear diagnosis, or 3+ broken steps).
+Reset the app to prerequisite state (`restart-app` + `launch-app`). Record from scratch with the same flow name.
+
+**Decision heuristic:**
+
+- 1 step broken, parameter-only change → Strategy 1
+- 1 step broken, transient issue, not worth persisting → Strategy 2
+- 2–3 steps broken or flow structure partially changed → Strategy 3
+- 3+ steps broken, or unclear root cause → Strategy 4
+- Flow used for profiling comparison (must be identical) → Strategy 4
+
+### 10.4 Verify and Bound Retries
+
+After applying a correction, re-run `flow-execute` to verify.
+
+- If it succeeds → done. Report what changed (e.g. "Fixed step 4: updated tap coordinates from 0.5,0.35 to 0.5,0.42").
+- If it fails at a **different** step → return to §10.2 for a second attempt.
+- If this is already the second correction attempt → **stop**. Report the diagnosis to the user and recommend a full re-record or manual investigation.
+
+**Hard cap: 2 correction cycles.** Do not enter an unbounded fix loop.
+
+### 10.5 Making Flows Resilient
+
+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.
+- **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.
+- **Echo accessibility labels for coordinate taps.** When recording a tap, add an echo with the target's label or testID: `"Tapping 'Submit' button (testID: submit-btn) at 0.5, 0.82"`. During repair, use `describe` to find the element by label and update coordinates. Only use `screenshot` for permission or system overlays when `describe` cannot expose the target reliably.

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

@@ -0,0 +1,103 @@
+---
+name: argent-ios-profiler
+description: Native iOS profiling for CPU hotspots, UI hangs, and memory leaks via xctrace. Use when diagnosing native-level performance issues on iOS simulators or devices.
+---
+
+## 1. Tool Overview
+
+| Tool                   | Purpose                                                                                                                            |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `ios-profiler-start`   | Start xctrace recording on a booted simulator or device. Captures CPU, hangs, and leaks. Optional: `app_process`, `template_path`. |
+| `ios-profiler-stop`    | Stop xctrace, export trace data to XML files (timestamped, persist on disk).                                                       |
+| `ios-profiler-analyze` | Parse exported XML and return structured bottleneck payload (CPU hotspots, UI hangs, leaks).                                       |
+| `profiler-stack-query` | Drill into parsed data: hang stacks, function callers, thread breakdown, leak details.                                             |
+| `profiler-load`        | List and reload previous trace sessions from disk for re-investigation.                                                            |
+
+---
+
+## 2. Investigation Patterns
+
+After `ios-profiler-analyze` surfaces findings, use `profiler-stack-query` to drill into root causes:
+
+- **Hang detected** → `profiler-stack-query` mode=`hang_stacks` for full native call chains → mode=`function_callers` for the suspected function → read native source.
+- **CPU hotspot** → `profiler-stack-query` mode=`thread_breakdown` for per-thread distribution → mode=`function_callers` for the dominant function.
+- **Memory leak** → `profiler-stack-query` mode=`leak_stacks` filtered by `object_type` for responsible frames and libraries.
+
+After presenting findings, ask the user whether to investigate further, implement fixes, or stop. After applying fixes, always re-profile the same scenario and compare with `profiler-load`. Report honestly whether the target metric improved, regressed, or stayed flat. If the fix showed no net benefit or introduced regressions elsewhere, say so and reconsider.
+
+**Tip:** For reproducible before/after comparisons, record the interaction sequence as a flow using the `argent-create-flow` skill before the first profiling run. Replay with `flow-execute` on subsequent runs to eliminate interaction variance.
+
+> **Note:** The `argent-react-native-profiler` instructs to start iOS profiling automatically alongside React profiling. This skill's workflow and investigation patterns apply in both cases.
+
+---
+
+## 3. Workflow
+
+**Complete all steps in order — do not break mid-flow.**
+
+### Step 0: Ensure the target app is running
+
+The `ios-profiler-start` tool **auto-detects** the running app on the simulator.
+You do not need to derive `app_process` manually — just make sure the app is launched.
+
+1. If the app is already running on the simulator, skip to Step 1 (do not pass `app_process`).
+2. If the app is not running, use `launch-app` with the correct bundle ID first.
+3. Only pass `app_process` explicitly if the tool reports multiple running user apps and you need to disambiguate.
+
+> **Note**: If multiple build flavors are installed (dev, staging, prod), the tool will detect whichever one is currently running. If both are running, it will ask you to specify.
+
+### Step 1: Start recording
+
+Call `ios-profiler-start` with `device_id` (simulator UDID). The tool auto-detects the running app and saves the trace to `/tmp/argent-profiler-cwd/` with a timestamped filename.
+Let the user interact with the app or drive interaction via simulator tools (see `argent-simulator-interact` skill).
+
+### Step 2: Stop and export
+
+Call `ios-profiler-stop` with `device_id`. This sends SIGINT to xctrace, waits for trace packaging, and exports CPU, hangs, and leaks data to XML. Check `exportDiagnostics` in the response for any export warnings.
+
+### Step 3: Analyze
+
+Call `ios-profiler-analyze` with `device_id`. Returns a markdown report with bottlenecks categorized as CPU hotspots, UI hangs, or memory leaks, sorted by severity.
+
+### Step 4: Present findings and ask about next steps
+
+Present a concise summary of the key findings. Then follow the "After analysis" guideline — ask whether to investigate further with query tools, implement fixes, or stop.
+
+### Step 5: Drill-down investigation
+
+Use `profiler-stack-query` to investigate specific findings. See §3 Investigation Patterns for chaining guidance.
+
+### Step 6: Reload previous sessions
+
+To revisit a previous trace:
+
+1. Call `profiler-load` mode=`list` to see available sessions.
+2. Call `profiler-load` mode=`load_instruments` session_id=`<timestamp>` device_id=`<UDID>` to re-parse the XML files.
+3. Use `profiler-stack-query` to investigate the reloaded data.
+
+---
+
+## 4. Understanding Results
+
+Bottlenecks are categorized by severity:
+
+- **RED**: CPU functions taking >15% of total time, all UI hangs, all memory leaks. These require immediate attention.
+- **YELLOW**: CPU functions taking 5-15% of total time. Worth investigating but may be acceptable.
+
+Each bottleneck type indicates a different class of problem:
+
+- **CPU hotspots**: Native functions consuming excessive CPU time. Look for tight loops, expensive computations, or redundant work.
+- **UI hangs**: Main thread blocked long enough to cause visible jank or unresponsiveness. Often caused by synchronous I/O, heavy layout passes, or lock contention.
+- **Memory leaks**: Objects allocated but never freed. Common causes include retain cycles, unclosed resources, or forgotten observers.
+
+---
+
+## 5. Important Caveats
+
+- **Simulator vs device**: Simulator profiling reflects host Mac performance, not real device hardware. Use device profiling for accurate CPU timings and memory behavior.
+- **xctrace availability**: Requires Xcode command-line tools installed. Verify with `xcrun xctrace version`.
+- **Profiler overhead**: xctrace instrumentation adds CPU load. If `JSLexer`, `JSONEmitter`, or Hermes runtime internals dominate the JS thread in CPU hotspot results, those reflect profiler overhead — not app work. Discount those entries when evaluating findings.
+- **Run-to-run variance**: Small fluctuations in CPU percentages between runs are normal. Treat only consistent directional changes (across 2+ runs or >15% delta) as actionable signal.
+- **Live data variability**: If the app fetches live API data, different responses between runs change rendering workload independently of code changes. Note when data-dependent screens show variance.
+
+---

package/skills/argent-metro-debugger/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: argent-metro-debugger
+description: Debug a React Native app via Metro CDP using argent debugger tools. Use when connecting to Metro, inspecting React components, reading console logs, or evaluating JavaScript in the app runtime.
+---
+
+## 1. Prerequisites
+
+The debugger requires **Metro dev server running** (default `localhost:8081`) and **a React Native app connected to Metro** (at least one CDP target). Verify via `debugger-status`.
+
+## 2. Tool Overview
+
+All tools accept `port` (default 8081) AND `device_id` (the iOS Simulator UDID, a.k.a. `logicalDeviceId`). Always make sure you target the correct app on the correct device.
+
+One Metro port can serve multiple connected devices (e.g. two simulators on `localhost:8081`). `device_id` pins every debugger/network/profiler call to a specific device so sessions do not collide.
+
+### Connect & diagnostics
+
+| Tool               | Purpose                                                                                                                                                                                                                   |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debugger-connect` | Connect to Metro CDP. Returns port, projectRoot, deviceName, appName, `logicalDeviceId`, isNewDebugger, connected. The returned `logicalDeviceId` is the `device_id` for every subsequent debugger/network/profiler call. |
+| `debugger-status`  | Like connect + loadedScripts, enabledDomains, sourceMapReady. **Use to diagnose.**                                                                                                                                        |
+
+### Reload & recovery
+
+| Tool                    | Purpose                                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------------------- |
+| `debugger-reload-metro` | Reload all connected apps (like pressing "r" in Metro terminal). Needs a CDP target.     |
+| `restart-app`           | Terminate and relaunch the app by UDID and bundleId. Use when app lost Metro connection. |
+
+### Inspection & console
+
+| Tool                       | Purpose                                                                                                                                                                   |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `debugger-component-tree`  | Full React fiber tree (names, depth, bounding rects, tap coordinates).                                                                                                    |
+| `debugger-inspect-element` | Inspect at (x, y) using **logical pixel coordinates** (not normalized 0-1): component hierarchy with source file:line and code fragment. See `references/source-maps.md`. |
+| `debugger-log-registry`    | Get log summary (counts, clusters, file path). Then use `Grep`/`Read` on the flat log file for details.                                                                   |
+| `debugger-evaluate`        | Run a JS expression in the app runtime.                                                                                                                                   |
+
+---
+
+## 3. Component Inspection
+
+### `debugger-component-tree` vs `debugger-inspect-element`
+
+|          | `debugger-component-tree`                                              | `debugger-inspect-element`                                      |
+| -------- | ---------------------------------------------------------------------- | --------------------------------------------------------------- |
+| Best for | Layout overview; finding tap targets; user-defined component hierarchy | Identifying a visible element and tracing it to its source file |
+| Use when | "What's on screen and where?"                                          | "What component is this and where is it defined?"               |
+
+Both can point to source files, but `inspect-element` is purpose-built for source tracing. `component-tree` is for orientation and tap-target discovery.
+
+### `includeSkipped` guidance
+
+Applies to both `debugger-component-tree` and `debugger-inspect-element`. Set to `true` only when debugging filter behavior — e.g., an expected component is missing from output, or you need to inspect a very specific branch of the tree (not just an overview).
+
+> **Warning:** Output can be very large. Always combine with `maxNodes` (component-tree) or `maxItems` (inspect-element) and increase it incrementally (e.g., start at 50, then grow). Do not use `includeSkipped` without a limit on large apps.
+
+---
+
+## 4. Golden Rules
+
+1. **`debugger-status` first when something fails** — it runs discovery, connection, and returns diagnostics.
+2. **"No CDP targets" → get the app to connect to Metro** — use `restart-app` on simulator, then retry `debugger-status`.
+3. **Never assume one failure is permanent** — follow recovery steps before asking the user. For starting Metro and full failure recovery, see `argent-react-native-app-workflow` and `references/failure-scenarios.md`.
+
+---
+
+## 5. Reading Console Logs (Log Registry)
+
+Logs are written to a flat log file on disk. Use the **log-registry → grep** pattern instead of reading logs inline.
+
+### Workflow
+
+1. **Call `debugger-log-registry`** — returns: `file` (log path), `totalEntries`, `byLevel`, `clusters` (top message groups with counts and source file info)
+2. **Search the file** using `Grep` or `Read` with patterns from the response.
+
+> **Large log files:** If `totalEntries` exceeds 10 000, delegate the grep exploration to an `Explore` subagent — pass it the file path, the entry format, and the patterns you need.
+
+### Flat log format
+
+One entry per line — fields (whitespace-separated, `|` delimiter before message)
+
+| Field         | Example                     | Notes                                               |
+| ------------- | --------------------------- | --------------------------------------------------- |
+| `[L:<id>]`    | `[L:42]`                    | Unique grep anchor                                  |
+| `<timestamp>` | `2026-03-17T14:30:00.000Z`  | ISO 8601                                            |
+| `<LEVEL>`     | `ERROR`, `WARN `, `LOG  `   | Uppercase, padded to 5 chars                        |
+| `<source>`    | `src/api/user.ts:42` or `-` | Relative path from source map; `-` if unavailable   |
+| `<message>`   | `Failed login attempt`      | Full message; embedded newlines replaced with space |
+
+Source attribution (file + line) is also available in `clusters` returned by `debugger-log-registry`.
+
+Log files and messages can be large - **Always scope your search**, treat the file like a database, not a document.
+
+When reading from the log file:
+
+- Never `Read` the log file directly. Use `grep` or shell commands with limits using the above file format tips.
+- Default to `-m 50` unless you need more.
+- Use `tail -N` recent entries.
+- `clusters[].message` gives you the exact text which you may look for
+
+> **If the file is too large** Delegate to an `Explore` subagent with the file path, the format spec above, and the specific patterns you need.
+
+---
+
+## Quick Reference
+
+| Action                        | Tool                                                                |
+| ----------------------------- | ------------------------------------------------------------------- |
+| Diagnose / check connection   | `debugger-status`                                                   |
+| Connect to Metro CDP          | `debugger-connect`                                                  |
+| Reload JS (already connected) | `debugger-reload-metro`                                             |
+| Relaunch app on simulator     | `restart-app`                                                       |
+| Inspect component at point    | `debugger-inspect-element`                                          |
+| Full component tree           | `debugger-component-tree`                                           |
+| Console log overview          | `debugger-log-registry` (summary + log file path for `Grep`/`Read`) |
+| Evaluate JS                   | `debugger-evaluate`                                                 |