@swmansion/argent 0.24.1-next.9 → 0.25.0

package/README.md

@@ -1,215 +1,40 @@
 <br/>
-<p align="center">
-  <a href="https://argent.swmansion.com">
-    <img width="1100" height="382" alt="argent-header" src="https://github.com/user-attachments/assets/6cec01d5-da3c-4b6c-97c3-0374a63c213c" />
-  </a>
-</p>
+<p align="center"><a href="https://argent.swmansion.com"><img width="1100" height="382" alt="argent-header" src="https://github.com/user-attachments/assets/6cec01d5-da3c-4b6c-97c3-0374a63c213c" /></a></p>
 
 [![Ad](https://swm-delivery.com/www/images/zone-gh-argent-1?n=1)](https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-argent-1&n=1)
 [![Ad](https://swm-delivery.com/www/images/zone-gh-argent-2?n=1)](https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-argent-2&n=1)
 [![Ad](https://swm-delivery.com/www/images/zone-gh-argent-3?n=1)](https://swm-delivery.com/www/delivery/ck-slug.php?zoneid=zone-gh-argent-3&n=1)
 
-**[Argent](https://argent.swmansion.com)** is an **agentic toolkit** that gives your AI assistant direct access to iOS Simulators, Android emulators and physical devices, TVs (Apple TV, Android TV, Fire TV) and Electron/Chromium desktop and web apps. Ask it to tap a button, run a profiler or reproduce an issue manually - all from within your CLI, without switching context.
+**[Argent](https://argent.swmansion.com)** gives your AI assistant direct control of iOS simulators, Android emulators and devices, TVs (Apple TV, Android TV, Fire TV) and Electron/Chromium apps. Tap a button, profile a screen, reproduce a bug - without leaving the CLI.
 
 ```bash
-npx @swmansion/argent@latest init
-# or, in a pnpm project (where npm's devEngines check may refuse to run npx):
-pnpm dlx @swmansion/argent@latest init
+npx @swmansion/argent@latest init  # pnpm: pnpm dlx @swmansion/argent@latest init
 ```
 
-## Supported platforms
+<p align="center"><img src="https://github.com/software-mansion/argent/blob/main/assets/showcase.gif" alt="argent showcase video gif" width="100%" /></p>
 
-Argent drives a growing set of targets through a single toolkit, each with the right interaction model - touch, remote or mouse:
+## What it does
 
-| Platform          | Targets                                                                 | Interaction      |
-| ----------------- | ----------------------------------------------------------------------- | ---------------- |
-| **iOS**           | Simulators and physical iPhones                                         | Touch / gesture  |
-| **Android**       | Emulators (AVDs) and physical devices over adb                          | Touch / gesture  |
-| **TV**            | Apple TV (tvOS), Android TV / Google TV, Amazon Fire TV (Vega)          | D-pad / remote   |
-| **Desktop & web** | Electron and Chromium apps (incl. React Native Web / Expo web) over CDP | Mouse / keyboard |
+- **Interact** - tap, swipe, gesture, type, hardware buttons; D-pad on TV; mouse and keyboard on desktop.
+- **Flows** - record a path once, replay it deterministically as a repro or smoke test.
+- **Visual regression** - diff a baseline against a live capture, OCR- and font-aware.
+- **Profiling** - Hermes, React DevTools, Xcode Instruments, Perfetto: renders, CPU hotspots, hangs.
+- **Debugging** - logs, network (`fetch` and native), JS evaluation, native and React trees.
+- **React Native** - build, launch and iterate, no extra setup.
 
-## Capabilities
+Ask your assistant _"What can Argent do?"_ to list every tool.
 
-- **Autonomous mobile, TV and desktop development** - Allow your agent to work with iOS, Android, TV and Electron/web apps on its own - let it build, open, interact with the app and debug it. Ask for reproducing issues, testing features manually, profiling your app and much more, without ever interrupting your work.
-- **UI interaction** - Give your agent the full control toolkit - tapping, swiping, pinching, typing, gestures and hardware buttons on mobile; the directional remote on TV; mouse, scroll and drag on desktop/web. Let it navigate your app exactly as a user would, without lifting a finger.
-- **Record & replay flows** - Capture a sequence of interactions once and let your agent replay it deterministically, so manual repros and smoke tests become repeatable.
-- **Visual regression** - Diff two screenshots (or a saved baseline against a live capture) with OCR- and font-aware comparison to catch unintended UI changes.
-- **Profiling with batteries included** - Argent can perform and analyze React Native (Hermes), React DevTools and native (Xcode Instruments / Android Perfetto) profiling sessions - down to fiber renders, CPU hotspots and cross-correlated commit-vs-hang reports. Get comprehensive summaries and ask to optimise your app where you find fit.
-- **Debugging and diagnostics** - Let your agent inspect logs, capture network traffic (JS `fetch` and native), evaluate JS in the running app, walk the native UIKit and React component trees, and reproduce failing states - so you can jump straight to the fix.
-- **Desktop & web control** - For Electron and Chromium apps your agent can drive tabs, read and write cookies and storage, walk the DOM and inspect network over the Chrome DevTools Protocol.
-- **React Native out of the box** - Argent works with React Native apps natively, so your agent can build, launch, and iterate on your RN project the same way it would any native app - no extra setup required.
+## Documentation
 
-> **Tip:** Once installed, ask your assistant _"What can Argent do?"_ - it will walk you through all capabilities available.
-
-<br/>
-<p align="center">
-  <img src="https://github.com/software-mansion/argent/blob/main/assets/showcase.gif" alt="argent showcase video gif" width="100%" />
-</p>
-
----
-
-## Installation
-
-#### Prerequisites
-
-- **Node.js 20.12** or later
-- For iOS / tvOS: macOS with **Xcode** installed (Apple TV uses tvOS simulators — Xcode downloads the tvOS runtime on demand)
-- For Android / Android TV: **Android SDK Platform Tools** (`adb`) on `PATH`, and the **Android Emulator** package if you want to boot AVDs from Argent. Create AVDs via Android Studio or `avdmanager`.
-- For Fire TV (Vega): the **Vega SDK** (`vega` CLI) on `PATH`
-- For Electron / Chromium: nothing extra to control an already-running app - just launch it with `--remote-debugging-port`, or let Argent spawn your Electron app for you
-
-##### Linux host: extra prerequisites for Android emulators
-
-Argent runs Android emulators on Linux but the default install can be slow if a few host-side knobs aren't right. Cover these once and the experience matches macOS:
-
-- **KVM access.** The emulator falls back to slow software emulation (TCG) without `/dev/kvm`. Make sure virtualization is enabled in BIOS/UEFI (`vmx` for Intel, `svm` for AMD in `/proc/cpuinfo`) and that your user can read/write `/dev/kvm` — on most distros that means joining the `kvm` group:
-
-  ```bash
-  sudo usermod -aG kvm "$USER"
-  # log out and back in so the new group takes effect
-  ```
-
-- **GPU mode (`-gpu swiftshader` on Linux, override available).** The Android emulator's Linux GPU story is messy: `-gpu auto` frequently resolves to lavapipe (slow software Vulkan via host libvulkan, ~10× cold-boot regression on flagship hardware), and `-gpu host` silently produces a corrupted or black emulator window on hosts with non-trivial GL stacks — dual-GPU / Optimus laptops, NVIDIA + Mesa coexistence via libglvnd, Wayland sessions on hybrid graphics, headless / containerized hosts. The failure mode is invisible to argent's framebuffer-based screenshot tool, so an agent reports success while the developer sees a black window.
-
-  Argent picks `-gpu swiftshader` on Linux for universal compatibility: it sidesteps the host GL stack entirely and renders via the emulator's bundled SwiftShader. On modern multi-core machines this is indistinguishably smooth from hardware-accelerated `-gpu host` (and far faster than lavapipe).
-
-  Override with the `ARGENT_EMULATOR_GPU_MODE` env var if you've verified `-gpu host` works on your machine (typical single-GPU Mesa box with a healthy X session):
-
-  ```bash
-  ARGENT_EMULATOR_GPU_MODE=host argent ...
-  ```
-
-  Argent's boot-device preflight prints a warning if `/dev/kvm` isn't usable — the condition that causes a 10–50× TCG-vs-KVM slowdown.
-
-- **System image.** Prefer the `default` or `google_apis` variants of `x86_64` system images for headless agent workflows; `google_apis_playstore` adds noticeable boot-time CPU churn from Play services. Always pick `x86_64` on Intel/AMD hosts — ARM images run via QEMU translation and are dramatically slower.
-
-- **AVD config.** AVDs created via `avdmanager create avd` default to `hw.gpu.enabled=no`. Argent overrides this with an explicit `-gpu` arg at launch (so the on-disk config doesn't need editing). For the smoothest experience under heavy native builds (gradle compilations alongside the AVD), bump the AVD's RAM and CPU count — edit `~/.android/avd/<name>.avd/config.ini`:
-
-  ```
-  hw.ramSize = 8192
-  hw.cpu.ncore = 6
-  vm.heapSize = 512
-  ```
-
-  Stock 2 GB / 4 vCPU AVDs can be CPU-starved into wedged-system_server states by a concurrent gradle/Kotlin compile.
-
-- **Headless / CI mode (`ARGENT_EMULATOR_NO_WINDOW=1`).** Argent shows the emulator window by default so a local developer can see the AVD UI. In a headless context — CI runner, container, or a Wayland-only session where the emulator's bundled Qt has no `wayland` platform plugin and SIGABRTs on the crash-consent dialog — opt out by exporting `ARGENT_EMULATOR_NO_WINDOW=1` before starting the tool-server. This appends `-no-window` to the spawn args, selecting `qemu-system-x86_64-headless` which doesn't need a Qt window. Argent's screencap-based screenshot tool reads the in-memory framebuffer correctly without a visible window.
-
-#### Run `init` in your project
-
-From your project root:
-
-```bash
-npx @swmansion/argent@latest init
-# or, in a pnpm project (where npm's devEngines check may refuse to run npx):
-pnpm dlx @swmansion/argent@latest init
-```
-
-This command triggers an installation wizard which:
-
-- Installs `@swmansion/argent` globally
-- Detects your editor and registers the MCP server
-- Copies skills, rules, and agent definitions into your workspace
-
-#### Prefer a manual install?
-
-```bash
-npm install -g @swmansion/argent
-argent init
-```
-
-#### Share Argent with your team (committable install)
-
-By default Argent installs **globally**. To version Argent _with your repo_ so every
-teammate gets the same setup on `npm install` — no per-developer global install, no
-`argent init` — choose the local mode:
-
-```bash
-npx @swmansion/argent@latest init --local
-# or, in a pnpm project:
-pnpm dlx @swmansion/argent@latest init --local
-```
-
-> Note: in a freshly `pnpm init`-ed project, `npx` itself may refuse to run
-> (npm's `devEngines` check) — use the `pnpm dlx` form there.
-
-This adds `@swmansion/argent` to your project's `devDependencies` and writes MCP
-configs that launch the project-local copy (`node node_modules/@swmansion/argent/dist/cli.js mcp`).
-Commit `package.json` + your lockfile, the generated MCP config (`.mcp.json`,
-`.cursor/mcp.json`, …), `.argent/install.json`, and the skills/rules/agents files.
-Teammates then just run `npm install`.
-
-Pass `--global` to force the default mode in scripts; `--local` and `--global` are
-mutually exclusive. A non-interactive (`--yes`) run defaults to global unless the
-project already opted into local mode (a committed `.argent/install.json`, or
-`@swmansion/argent` declared in the project's own `package.json`).
-
-> In local mode the committed MCP config runs the project-local copy, so the bare
-> `argent` command is **not** on teammates' `PATH`. Note that `npm install` builds
-> Argent's native deps (`tree-sitter`) on each machine — prebuilt for macOS, Linux
-> x64, and Windows x64; other targets (Linux arm64, Windows arm) compile from source
-> and need a C/C++ toolchain.
-
-## CLI Reference
-
-| Command            | Description                                                                                                                                                                                               |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `argent init`      | Install and configure MCP in the current workspace (`--global` default, `--local` for a committable devDependency)                                                                                        |
-| `argent install`   | Alias for `init` command                                                                                                                                                                                  |
-| `argent update`    | Pull the latest version and refresh workspace configuration (acts on the present install — both when a global install and a project devDependency coexist; `--global`/`--local` select explicitly)        |
-| `argent uninstall` | Unregister the MCP server and uninstall the package (`--global`/`--local` choose which install — and its configs — is removed; non-interactive runs never remove a coexisting global install)             |
-| `argent remove`    | Alias for `uninstall` command                                                                                                                                                                             |
-| `argent mcp`       | Start MCP server instance, used internally by agent                                                                                                                                                       |
-| `argent tools`     | List tools exposed by the tool-server (`describe <name>` for details)                                                                                                                                     |
-| `argent run`       | Invoke a tool by name                                                                                                                                                                                     |
-| `argent server`    | Manage the shared tool-server: `start` / `status` / `stop` / `logs`                                                                                                                                       |
-| `argent lens`      | Open Argent Lens bound to a fresh coding-agent session — Claude by default, `--agent` selects codex/gemini/opencode/cursor (macOS; behind the `argent-lens` flag — run `argent enable argent-lens` first) |
-| `argent link`      | Route client requests to a remote tool-server                                                                                                                                                             |
-| `argent unlink`    | Remove the persisted remote tool-server link                                                                                                                                                              |
-| `argent enable`    | Enable a predefined feature flag (`--scope project` for project-local)                                                                                                                                    |
-| `argent disable`   | Disable a feature flag (`--scope project` for project-local)                                                                                                                                              |
-| `argent flags`     | List available feature flags and their state                                                                                                                                                              |
-| `argent providers` | Inspect and manage external device providers: `list` / `check` / `publish` / `withdraw` / `prune`                                                                                                         |
-| `argent telemetry` | Manage telemetry: `status` / `enable` / `disable`                                                                                                                                                         |
-
-## Supported Editors
-
-`argent init` auto-detects and configures MCP for:
-
-| Editor      | Config location                                                             |
-| ----------- | --------------------------------------------------------------------------- |
-| Claude Code | `.mcp.json` (project) or `~/.claude.json` (global)                          |
-| Cursor      | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)               |
-| VS Code     | `.vscode/mcp.json`                                                          |
-| Windsurf    | `~/.codeium/windsurf/mcp_config.json` (global)                              |
-| Zed         | `.zed/settings.json` (project) or `~/.config/zed/settings.json` (global)    |
-| Gemini CLI  | `.gemini/settings.json`                                                     |
-| Codex CLI   | `.codex/config.toml` (project) or `~/.codex/config.toml` (global)           |
-| Hermes      | `~/.hermes/config.yaml` (global)                                            |
-| opencode    | `opencode.json` (project) or `~/.config/opencode/opencode.json` (global)    |
-| Kiro        | `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json` (global) |
+[Installation](https://docs.swmansion.com/argent/docs/fundamentals/installation) · [Platforms](https://docs.swmansion.com/argent/docs/fundamentals/supported-platforms) · [CLI](https://docs.swmansion.com/argent/docs/reference/cli) · [Editors](https://docs.swmansion.com/argent/docs/reference/editors)
 
 ## Privacy
 
-Argent collects opt-out usage and diagnostic telemetry to help us prioritise features and fix what breaks.
-
-You can opt out at any time:
-
-```bash
-argent telemetry disable   # check status with: argent telemetry status
-```
-
-For the full details — see the [Argent Privacy Notice (Telemetry)](https://github.com/software-mansion/argent/blob/main/Telemetry.md).
+Telemetry is opt-out: `argent telemetry disable`. See the [Privacy Notice](https://github.com/software-mansion/argent/blob/main/Telemetry.md).
 
 ## License
 
-Argent uses a mixed licensing model.
-
-**Source code** is released under the [Apache License 2.0](LICENSE.txt).
-
-**Proprietary binaries** (the per-platform `bin/<platform>/simulator-server` and `bin/darwin/ax-service` executables and the `.dylib` files in `native-devtools-ios`) are the intellectual property of Software Mansion S.A. and are licensed solely for use within this project. Decompiling, reverse-engineering, or redistributing them without explicit written permission is prohibited.
-
-By using Argent, you acknowledge and agree to this structure. See [LICENSE](https://github.com/software-mansion/argent/blob/main/LICENSE.txt) for full details.
+Argent uses a mixed licensing model. **Source code** is released under the [Apache License 2.0](LICENSE.txt). **Proprietary binaries** (the per-platform `bin/<platform>/simulator-server` and `bin/darwin/ax-service` executables and the `.dylib` files in `native-devtools-ios`) are the intellectual property of Software Mansion S.A. and are licensed solely for use within this project. Decompiling, reverse-engineering, or redistributing them without explicit written permission is prohibited. By using Argent, you acknowledge and agree to this structure. See [LICENSE](https://github.com/software-mansion/argent/blob/main/LICENSE.txt) for full details.
 
 ## Argent is created by Software Mansion
 

package/dist/cli-cmds.mjs

@@ -20976,31 +20976,51 @@ function toAttributes2(record2) {
   }
   return attributes;
 }
-var OTLP_HEADER_ENV_VARS = [
+var CLEARED_OTLP_ENV_VARS = [
   "OTEL_EXPORTER_OTLP_HEADERS",
-  "OTEL_EXPORTER_OTLP_LOGS_HEADERS"
+  "OTEL_EXPORTER_OTLP_LOGS_HEADERS",
+  "OTEL_EXPORTER_OTLP_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_CLIENT_KEY",
+  "OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY"
 ];
+var NO_COMPRESSION = "none";
 function createExporter(config3) {
-  const saved = OTLP_HEADER_ENV_VARS.map((name) => [name, process.env[name]]);
-  for (const name of OTLP_HEADER_ENV_VARS) delete process.env[name];
+  const saved = CLEARED_OTLP_ENV_VARS.map((name) => [name, process.env[name]]);
+  for (const name of CLEARED_OTLP_ENV_VARS) delete process.env[name];
   try {
     return new OTLPLogExporter({
       url: config3.endpoint,
       headers: { authorization: `Bearer ${config3.token}` },
       timeoutMillis: EXPORT_TIMEOUT_MS,
+      // Left unset, the SDK takes this from OTEL_EXPORTER_OTLP_COMPRESSION (or
+      // its _LOGS_ variant), so a machine that already runs OpenTelemetry would
+      // gzip argent's batches - a request shaped differently from the one the
+      // ingestion side is sized and tested against, decided by a variable set
+      // for something else. Unlike the variables cleared above, one explicit
+      // value settles it: the SDK takes user-provided over env here rather than
+      // merging the two or reading anything to decide.
+      compression: NO_COMPRESSION,
       // The exporter bounds a request with `req.setTimeout()`, which Node only
       // arms once the socket is CONNECTED — so a collector whose address drops
       // packets (corporate egress filter, dead host behind a firewall) leaves a
-      // socket stuck connecting that no export deadline can reach, holding the
-      // process open for the OS connect timeout after shutdown() has resolved.
-      // The agent's socket timeout is armed when the socket is CREATED, so it
-      // covers connect too: it fires, the request emits 'timeout', and the
-      // exporter's handler destroys it.
+      // socket stuck in the connecting state that no export deadline can reach,
+      // holding the process open for the OS connect timeout (~75s on macOS)
+      // after shutdown() has already resolved. The agent's socket timeout is
+      // armed when the socket is CREATED, so it also covers connect: it fires,
+      // the request emits 'timeout', and the exporter's handler destroys it.
       //
-      // keepAlive is restated because supplying httpAgentOptions at all
-      // replaces the agent the SDK would otherwise build, whose default is
-      // keepAlive: true; without it the long-lived tool-server pays a fresh
-      // TCP+TLS handshake for every batch.
+      // keepAlive is restated to match the agent the SDK would otherwise build,
+      // whose default is keepAlive: true — supplying httpAgentOptions at all
+      // replaces it, and keepAlive: false would open and close a socket per
+      // request. It does NOT save the handshake across the 10s batch cadence:
+      // this same timeout reaps an idle keep-alive socket, so one parked in the
+      // pool between batches is destroyed at EXPORT_TIMEOUT_MS, long before the
+      // next batch reaches for it. Reuse survives only for batches flushed
+      // within the timeout of each other, e.g. a force-flush of a queue that
+      // spans more than one batch.
       httpAgentOptions: { timeout: EXPORT_TIMEOUT_MS, keepAlive: true }
     });
   } finally {
@@ -21837,7 +21857,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID2 = randomUUID5();
 function readCliVersion() {
   if (true) {
-    return "0.24.1-next.9";
+    return "0.25.0";
   }
   return "0.0.0";
 }

package/dist/installer.mjs

@@ -15468,31 +15468,51 @@ function toAttributes2(record) {
   }
   return attributes;
 }
-var OTLP_HEADER_ENV_VARS = [
+var CLEARED_OTLP_ENV_VARS = [
   "OTEL_EXPORTER_OTLP_HEADERS",
-  "OTEL_EXPORTER_OTLP_LOGS_HEADERS"
+  "OTEL_EXPORTER_OTLP_LOGS_HEADERS",
+  "OTEL_EXPORTER_OTLP_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_CLIENT_KEY",
+  "OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY"
 ];
+var NO_COMPRESSION = "none";
 function createExporter(config) {
-  const saved = OTLP_HEADER_ENV_VARS.map((name) => [name, process.env[name]]);
-  for (const name of OTLP_HEADER_ENV_VARS) delete process.env[name];
+  const saved = CLEARED_OTLP_ENV_VARS.map((name) => [name, process.env[name]]);
+  for (const name of CLEARED_OTLP_ENV_VARS) delete process.env[name];
   try {
     return new OTLPLogExporter({
       url: config.endpoint,
       headers: { authorization: `Bearer ${config.token}` },
       timeoutMillis: EXPORT_TIMEOUT_MS,
+      // Left unset, the SDK takes this from OTEL_EXPORTER_OTLP_COMPRESSION (or
+      // its _LOGS_ variant), so a machine that already runs OpenTelemetry would
+      // gzip argent's batches - a request shaped differently from the one the
+      // ingestion side is sized and tested against, decided by a variable set
+      // for something else. Unlike the variables cleared above, one explicit
+      // value settles it: the SDK takes user-provided over env here rather than
+      // merging the two or reading anything to decide.
+      compression: NO_COMPRESSION,
       // The exporter bounds a request with `req.setTimeout()`, which Node only
       // arms once the socket is CONNECTED — so a collector whose address drops
       // packets (corporate egress filter, dead host behind a firewall) leaves a
-      // socket stuck connecting that no export deadline can reach, holding the
-      // process open for the OS connect timeout after shutdown() has resolved.
-      // The agent's socket timeout is armed when the socket is CREATED, so it
-      // covers connect too: it fires, the request emits 'timeout', and the
-      // exporter's handler destroys it.
+      // socket stuck in the connecting state that no export deadline can reach,
+      // holding the process open for the OS connect timeout (~75s on macOS)
+      // after shutdown() has already resolved. The agent's socket timeout is
+      // armed when the socket is CREATED, so it also covers connect: it fires,
+      // the request emits 'timeout', and the exporter's handler destroys it.
       //
-      // keepAlive is restated because supplying httpAgentOptions at all
-      // replaces the agent the SDK would otherwise build, whose default is
-      // keepAlive: true; without it the long-lived tool-server pays a fresh
-      // TCP+TLS handshake for every batch.
+      // keepAlive is restated to match the agent the SDK would otherwise build,
+      // whose default is keepAlive: true — supplying httpAgentOptions at all
+      // replaces it, and keepAlive: false would open and close a socket per
+      // request. It does NOT save the handshake across the 10s batch cadence:
+      // this same timeout reaps an idle keep-alive socket, so one parked in the
+      // pool between batches is destroyed at EXPORT_TIMEOUT_MS, long before the
+      // next batch reaches for it. Reuse survives only for batches flushed
+      // within the timeout of each other, e.g. a force-flush of a queue that
+      // spans more than one batch.
       httpAgentOptions: { timeout: EXPORT_TIMEOUT_MS, keepAlive: true }
     });
   } finally {
@@ -16690,7 +16710,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = randomUUID4();
 function readCliVersion() {
   if (true) {
-    return "0.24.1-next.9";
+    return "0.25.0";
   }
   return "0.0.0";
 }

package/dist/tool-server.cjs

@@ -93813,31 +93813,51 @@ function toAttributes2(record2) {
   }
   return attributes;
 }
-var OTLP_HEADER_ENV_VARS = [
+var CLEARED_OTLP_ENV_VARS = [
   "OTEL_EXPORTER_OTLP_HEADERS",
-  "OTEL_EXPORTER_OTLP_LOGS_HEADERS"
+  "OTEL_EXPORTER_OTLP_LOGS_HEADERS",
+  "OTEL_EXPORTER_OTLP_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_LOGS_CLIENT_CERTIFICATE",
+  "OTEL_EXPORTER_OTLP_CLIENT_KEY",
+  "OTEL_EXPORTER_OTLP_LOGS_CLIENT_KEY"
 ];
+var NO_COMPRESSION = "none";
 function createExporter(config2) {
-  const saved = OTLP_HEADER_ENV_VARS.map((name) => [name, process.env[name]]);
-  for (const name of OTLP_HEADER_ENV_VARS) delete process.env[name];
+  const saved = CLEARED_OTLP_ENV_VARS.map((name) => [name, process.env[name]]);
+  for (const name of CLEARED_OTLP_ENV_VARS) delete process.env[name];
   try {
     return new OTLPLogExporter({
       url: config2.endpoint,
       headers: { authorization: `Bearer ${config2.token}` },
       timeoutMillis: EXPORT_TIMEOUT_MS,
+      // Left unset, the SDK takes this from OTEL_EXPORTER_OTLP_COMPRESSION (or
+      // its _LOGS_ variant), so a machine that already runs OpenTelemetry would
+      // gzip argent's batches - a request shaped differently from the one the
+      // ingestion side is sized and tested against, decided by a variable set
+      // for something else. Unlike the variables cleared above, one explicit
+      // value settles it: the SDK takes user-provided over env here rather than
+      // merging the two or reading anything to decide.
+      compression: NO_COMPRESSION,
       // The exporter bounds a request with `req.setTimeout()`, which Node only
       // arms once the socket is CONNECTED — so a collector whose address drops
       // packets (corporate egress filter, dead host behind a firewall) leaves a
-      // socket stuck connecting that no export deadline can reach, holding the
-      // process open for the OS connect timeout after shutdown() has resolved.
-      // The agent's socket timeout is armed when the socket is CREATED, so it
-      // covers connect too: it fires, the request emits 'timeout', and the
-      // exporter's handler destroys it.
+      // socket stuck in the connecting state that no export deadline can reach,
+      // holding the process open for the OS connect timeout (~75s on macOS)
+      // after shutdown() has already resolved. The agent's socket timeout is
+      // armed when the socket is CREATED, so it also covers connect: it fires,
+      // the request emits 'timeout', and the exporter's handler destroys it.
       //
-      // keepAlive is restated because supplying httpAgentOptions at all
-      // replaces the agent the SDK would otherwise build, whose default is
-      // keepAlive: true; without it the long-lived tool-server pays a fresh
-      // TCP+TLS handshake for every batch.
+      // keepAlive is restated to match the agent the SDK would otherwise build,
+      // whose default is keepAlive: true — supplying httpAgentOptions at all
+      // replaces it, and keepAlive: false would open and close a socket per
+      // request. It does NOT save the handshake across the 10s batch cadence:
+      // this same timeout reaps an idle keep-alive socket, so one parked in the
+      // pool between batches is destroyed at EXPORT_TIMEOUT_MS, long before the
+      // next batch reaches for it. Reuse survives only for batches flushed
+      // within the timeout of each other, e.g. a force-flush of a queue that
+      // spans more than one batch.
       httpAgentOptions: { timeout: EXPORT_TIMEOUT_MS, keepAlive: true }
     });
   } finally {
@@ -94682,7 +94702,7 @@ var _CI_VENDOR_COUNT_FOR_TEST = vendors_default.length;
 var SESSION_ID = (0, import_node_crypto3.randomUUID)();
 function readCliVersion() {
   if (true) {
-    return "0.24.1-next.9";
+    return "0.25.0";
   }
   return "0.0.0";
 }
@@ -96039,7 +96059,7 @@ var import_node_path5 = __toESM(require("node:path"));
 var import_semver2 = __toESM(require_semver2());
 
 // ../tool-server/package.json
-var version2 = "0.24.0";
+var version2 = "0.25.0";
 
 // ../tool-server/src/utils/update-checker.ts
 var import_update_core = __toESM(require_dist4());
@@ -154349,85 +154369,11 @@ function createRunFlowTool(registry2) {
       completedMsg: ({ params }) => `Ran flow ${displayFlowName(params)}`,
       failedMsg: ({ params, failureSignal: failureSignal2 }) => `Failed to run flow ${displayFlowName(params)}: ${failureSignal2.error_code}`
     },
-    description: `Run a saved flow from the .argent/flows/ directory, or an explicit boundary-managed flow_path.
-Use when a scenario is already authored as YAML and the whole of it should replay in one call with a
-per-step verdict; reach for the individual gesture tools when nothing is authored yet, and for
-run-sequence when the steps are an ad-hoc list rather than a stored flow.
-Steps run in order: \`launch\` starts an app from scratch (terminate + relaunch) and waits until it is
-ready (on iOS it also pins later element lookups to that app rather than auto-detecting the frontmost
-one); \`tool\` calls dispatch through the registry (a raw \`tool\` step ends that iOS pin, so lookups
-auto-detect again until the next \`launch\`, though a tool that cannot change the foreground app leaves the
-launched id as a fallback for a timed-out auto-detect, and \`launch-app\`/\`restart-app\` leave the id they
-started as that fallback instead); \`tap\`/\`long-press\`/\`type\` resolve a selector to an
-element and act on it (\`tap: { on, times: 2 }\` double-taps; \`long-press: { on, duration }\` presses and
-holds; \`tap\`/\`long-press\` alternatively take a raw normalized point \u2014 bare \`{ x, y }\` or \`on: { x, y }\`;
-any selector may scope its matches geometrically, the CSS combinators read off frames: \`within: <selector>\`
-(descendant \u2014 inside that container's frame), \`after: <selector>\` (CSS \`~\` \u2014 following it in reading
-order), \`next: <selector>\` (CSS \`+\` \u2014 the nearest such follower, which unlike CSS reaches past a
-non-matching neighbour rather than failing), plus \`any: true\` (CSS \`*\` \u2014 legal only WITH a scope and
-never beside text/id/role). Scopes nest to disambiguate \u2014 \`within: { id: card, within: { id: list } }\`
-reads "inside card inside list", each container's frame inside the next);
-\`swipe\` performs one finger flick (\`swipe: left\`, or \`swipe: { from?, direction|to|by, momentum?, duration? }\` \u2014
-direction is the FINGER's travel, the opposite sense of scroll-to's content direction; \`by: { x?, y? }\` \u2014 signed
-0\u20131 screen fractions, combined length at least 0.03 (a diagonal clears it where neither axis does); duration in ms,
-default 300, minimum 150, maximum 10000; each bound is a parse error that rejects the file before any step runs;
-\`momentum: false\` lands exactly where the finger lifts instead of flinging);
-\`scroll-to\` scrolls (momentum-free) until a target is visible; \`pinch\` zooms
-(\`pinch: { on?, scale }\` \u2014 scale > 1 in, < 1 out; screen center when \`on\` is omitted); \`rotate\` is the
-two-finger rotation gesture (\`rotate: { on?, by }\` \u2014 degrees, + clockwise, within \xB13000\xB0; screen center
-when \`on\` is omitted; distinct from the \`rotate\` tool, which changes device orientation); \`await\` waits
-for a UI condition, and additionally takes the one condition that has no selector: \`idle: true\` waits
-until the screen has content and stops moving in BOTH the UI tree and the rendered pixels (it never
-fails a run \u2014 a screen that never settles passes carrying a \`warning\`, which is what makes it safe to
-persist; the one idle outcome that does stop the run is an \`error\` for a tree source THIS step could not
-read at all \u2014 a broken window rather than a verdict about the app, which leaves the run not-ok and skips
-every later step; it says nothing about WHICH screen settled \u2014 a dropped tap leaves the source screen
-perfectly idle \u2014 so pair it with the element check that names the destination); \`wait\` pauses for a fixed number of milliseconds; \`assert\` checks one now; \`snapshot\`
-diffs a screenshot \u2014 or, with \`cropOn: <selector>\`, one element's cropped region \u2014 against a stored
-baseline (a missing baseline fails the step \u2014 set updateBaselines to adopt the current screen; a
-cropped element whose size drifted fails on dimensions); \`echo\` annotates; \`run\` executes another flow
-inline \u2014 a YAML path resolved against the directory of the flow file that references it (co-located
-runs only); \`script\` runs a local .mjs file in a fresh Node process for setup, cleanup, or any work a device step cannot do
-(\`script: { path: ../../scripts/seed.mjs, timeout?: <ms> }\` \u2014 always a map, never a bare path; the path
-is resolved against the flow file that names the step, exactly as a \`run\` target is, so a saved flow
-climbs out of .argent/flows/ to reach the project's own scripts/ directory. The step needs no device, so
-a script-only flow runs with nothing booted \u2014 but a \`run\` or a \`when\` step beside it still resolves
-one, \`when\` even when the only thing it guards is another script, so a platform-gated seed needs a
-device of that platform. Its stdout and stderr come back on the step report. Co-located runs only.).
-A selector-less gesture \u2014 a coordinate \`tap\`/\`long-press\`/\`swipe\`, or a \`pinch\`/\`rotate\` with no \`on\` \u2014 resolves
-no frame out of the tree, so an unreadable tree source does NOT stop it the way it stops \`idle\`: it
-settles best-effort, dispatches anyway, and the step PASSES carrying a \`warning\` that quotes the source's
-own error. That green says the gesture was SENT, not that it landed. Restore the tree source (usually
-relaunch the app so the instrumentation loads), or accept the warning where the app can serve no tree;
-the first such gesture proves the outage and later ones spend that verdict without paying the settle
-window again. A tree read that comes back, or a relaunch, retires that verdict \u2014 which only makes the
-next gesture pay a fresh window, and it warns again if the source is still down.
-A \`when:\` block (condition + \`steps:\`, no else) runs its steps only if the condition holds \u2014
-checked once with the short assert grace \u2014 for one-sided divergences like interstitials and coach
-marks; a skipped block reports distinctly and failures inside an entered block are real failures.
-A flow is self-contained when its first non-\`echo\`/\`script\` step is \`launch\`; it must not declare
-\`executionPrerequisite\`. Other flows use the device's current state. Device id is injected by the runner (flows store none) \u2014 pass \`device\` or
-\`platform\` to pick one, else the single booted device is used. On Chromium a \`launch\` step's value is an
-Electron app path ({ chromium: <path> | { path, args } }) the runner boots (on the tool-server host) rather
-than an installed app id it relaunches. With no explicit \`device\`, a run whose leading launch is
-unambiguously chromium (\`platform: chromium\`, or a lone \`{ chromium: \u2026 }\` target) boots that app and
-starts there \u2014 following a leading \`run:\`, \`echo:\` or \`script:\`, so a fragment that composes a chromium
-e2e flow boots too, and so does a flow that seeds a backend before it launches;
-otherwise the first launch attaches to an already-running instance and never kills it. Every later
-launch \u2014 a nested e2e flow's own, or a mid-flow relaunch \u2014 boots a fresh instance the run moves onto;
-an instance the run already owns for that same app is killed first (its exit awaited) so the
-replacement can't lose the race against its single-instance lock. Instances the runner still owns at
-run end are torn down then. A launch declaring no id for the run's platform is an error, not a cue to
-switch platforms. Every step hard-stops the flow on failure; later steps are reported as skipped.
-Returns a structured report ({ flow, device, executionPrerequisite, ok, aborted?, passed, failed,
-skipped, errored, steps }) \u2014 \`device\` is the device the run STARTED on; when launches moved it onto
-runner-booted instances, each names its instance in that step's reason and marks the move \u2014 \`run moved
-off <id>\`, or \`retired <id> (same app relaunched)\` when the instance it left was the one killed \u2014
-a relaunch that retired an older owned instance names both.
-
-If a fragment has an execution prerequisite and prerequisiteAcknowledged is not set to true, the tool
-returns a notice with the prerequisite instead of running.
-Pass exactly one flow source: name for a saved flow under project_root, or flow_path for an explicit YAML \u2014 both together, or neither, fails the call.`,
+    description: `Run a saved YAML flow end to end. Use when
+asked to replay a recorded path, re-run a QA regression, or check that a known journey still passes; for a
+one-off interaction use the gesture tools instead, and to author a flow use flow-start-recording. Pass
+exactly one flow source: name (under project_root) or flow_path.
+Returns a per-step report: the first failure stops the run and the rest report as skipped.`,
     longRunning: true,
     zodSchema: zodSchema66,
     fileInputs: fileInputs3,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swmansion/argent",
-  "version": "0.24.1-next.9",
+  "version": "0.25.0",
   "mcpName": "io.github.software-mansion/argent",
   "description": "MCP server for iOS Simulator and Android Emulator control",
   "license": "Apache-2.0",

package/skills/argent-create-flow/references/flow-yaml.md

@@ -109,7 +109,7 @@ Scopes can combine and nest, with at most six scope keys. Use strict selectors f
 
 ## Directives
 
-Directives stop the flow on failure and skip later steps. `flow-execute` documents their shapes. The available directives are `launch`, `tap`, `long-press`, `swipe`, `type`, `scroll-to`, `pinch`, `rotate`, `await`, `assert`, `wait`, `snapshot`, `run`, `script`, `when`, `echo`, and `tool`.
+Directives stop the flow on failure and skip later steps. The available directives are `launch`, `tap`, `long-press`, `swipe`, `type`, `scroll-to`, `pinch`, `rotate`, `await`, `assert`, `wait`, `snapshot`, `run`, `script`, `when`, `echo`, and `tool`.
 
 Use the launch map for cross-platform flows. A bare launch applies everywhere and becomes an app path on Chromium. The map takes `native:`, `ios:`, `android:`, `vega:`, and `chromium:`. `native:` is one id shared by iOS, Android, and Vega, and a per-platform key overrides it for that platform. `chromium:` accepts a relative or absolute app path. A launch that declares no id for the run's platform is an error, not a cue to switch platforms. On iOS, a successful launch also pins later tree reads to that app until the next raw `tool:` step, so read [The runner tree is not the discovery tree](#the-runner-tree-is-not-the-discovery-tree) when a read describes the wrong screen.
 

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

@@ -1,23 +1,13 @@
 ---
 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, waiting for an element to appear or disappear, 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. Not for TV targets.
 ---
 
 ## Unified tool surface
 
 All interaction tools below accept a `udid` parameter and auto-dispatch iOS vs Android based on its shape (UUID → iOS simulator, `chromium-cdp-<port>` → Chromium (CDP) app, anything else → Android adb serial). You use the same tool names on every platform.
 
-**Chromium (CDP) app** = any Chromium runtime exposing a Chrome DevTools Protocol endpoint: an Electron app (boot it with `boot-device` + `electronAppPath`), or any Chromium-family browser (Chrome/Brave/Edge) launched with `--remote-debugging-port`. The latter is auto-discovered by `list-devices` on port `9222` plus anything in `ARGENT_CHROMIUM_PORTS`. The same describe/tap/swipe/keyboard/screenshot surface drives all of them.
-
-**Multi-tab / windows (Chromium only):** a Chromium device may have several tabs / BrowserWindows. Use `chromium-tabs` to `list` them (stable ids `t1`, `t2`, …, optional labels), open a `new` one, `select` which is active, or `close` one. Every other tool (`describe`, `gesture-tap`, `screenshot`, `debugger-evaluate`, `open-url`, …) acts on the **active** tab, so `chromium-tabs action=select` before driving a different tab. Note: a cross-process navigation (some redirects) can swap a tab's underlying CDP target — re-run `chromium-tabs action=list` to pick it up under a fresh id.
-
-**Cookies & storage (Chromium only):** `chromium-cookies` reads/writes cookies via the Network domain (so HttpOnly cookies are visible): `action=get` (optionally scoped by `url`), `set` (`name`, `value`, + `url`/`domain`, optional `secure`/`httpOnly`/`sameSite`/`expires`), `delete` (`name`), `clear` (all). `chromium-storage` reads/writes Web Storage for the active page: `store=local|session`, `action=get` (one `key` or all entries), `set`, `remove`, `clear`. Both are per-origin / active-tab. Handy for seeding auth before a flow or asserting app state after one.
-
-> **TV targets (Apple TV / Android TV) are not covered by this skill.** A TV target is **focus-driven, not touch-driven** — the `gesture-*` tools are the wrong tools for it. This applies to both Apple TV simulators (UUID-shaped, identical to iOS) and Android TV / leanback devices (serial-shaped, identical to a phone emulator). If `list-devices` tags your target `runtimeKind: "tv"`, stop and use the `argent-tv-interact` skill: `describe` to read focus, `tv-remote` for remote / D-pad presses, and `keyboard` to type.
-
-> **Physical iPhones (an iOS entry with kind `"device"`) follow a different contract:** automation is app-scoped and only a subset of these tools exists there. Use the `argent-ios-device-interact` skill instead.
-
-For platform-specific caveats (Metro `adb reverse`, locked-screen describe errors, etc.), see § 9 Platform-specific notes at the bottom.
+**Chromium (CDP) app** = an Electron app or a Chromium-family browser (Chrome/Brave/Edge) exposing a Chrome DevTools Protocol endpoint. The same describe/tap/keyboard/screenshot surface drives it, but scrolling, tabs, cookies and storage differ — **read `references/chromium.md` before driving a `chromium` target.**
 
 ## 1. Before You Start
 
@@ -98,7 +88,7 @@ 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
+### If `describe` Tool Fails
 
 Read the exact error and choose the action that matches it:
 
@@ -186,21 +176,7 @@ Special keys: `enter`, `escape`, `backspace`, `tab`, `space`, `arrow-up`, `arrow
 { "udid": "<UDID>", "text": "{{secret:APP_PASSWORD}}" }
 ```
 
-The placeholder is resolved on the machine running the tool-server, from the first of these that defines the name:
-
-| #   | Source                                        | Which keys it exposes                                                |
-| --- | --------------------------------------------- | -------------------------------------------------------------------- |
-| 1   | `ARGENT_SECRET_<NAME>` environment variable   | prefixed vars only — the CI-native path                              |
-| 2   | `<project>/.argent/secrets.env`               | every key (`APP_PASSWORD=…`) — gitignore this file                   |
-| 3   | `<project>/.env.local`, then `<project>/.env` | only `ARGENT_SECRET_`-prefixed keys, so app config stays unreachable |
-| 4   | `~/.argent/secrets.env`                       | every key — per-user, works in any project                           |
-
-Rules:
-
-- The result echoes the placeholder, never the value. An unknown name fails with the list of available secret _names_ and every source it looked in, with paths — read that list before asking the user anything.
-- The auto-screenshot after the call is skipped so the typed value cannot re-enter your context as pixels. Do **not** `describe` or `screenshot` a non-secure field you just filled with a secret — submit or navigate away first, then verify the resulting screen. To submit, put the text step and the Enter step in **one `run-sequence`**. The skip covers a whole batch that contains the placeholder, but a second bare `keyboard` call gets its own screenshot of the filled field.
-- Nothing outside those sources is reachable; never ask the user to paste a secret value into the conversation. Ask them to put it in a secrets file instead — a file edit applies to the next call, while an exported env var only reaches a tool-server started afterwards.
-- The project sources are found by walking up from the tool-server's working directory. If a project file is not being picked up, the failure's source list shows the paths actually consulted; `~/.argent/secrets.env` needs no project and always applies.
+Where the value is read from, and the rules for using a placeholder — including not screenshotting the field afterwards — are in `references/secrets.md`. Read it before typing any credential.
 
 ### paste — Paste text into the focused field
 
@@ -224,20 +200,18 @@ 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.)
+**Never poll `screenshot`/`describe` in a loop to wait for something.** Use `await-ui-element`: it blocks server-side on the same tree `describe` reads. It has no bare-timer mode by design — for a plain pause, use your own harness sleep.
 
 ```json
 { "udid": "<UDID>", "condition": "visible", "selector": { "text": "Continue" } }
 ```
 
-- `condition`: `exists`, `visible`, `hidden`, or `text`.
-- `selector`: `{ text?, identifier?, role? }` — every provided field must match. `text` matches the element's label or value and `role` its element role (e.g. `AXButton`, `button`, `TextView`, `StaticText`), both as case-insensitive substrings; `identifier` matches its accessibility id / resource-id / testID **exactly** (case-insensitive), also accepting the unqualified Android resource-id name (`submit` matches `com.example.app:id/submit`). 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 **visible** match in **reading order** (top-to-bottom, left-to-right — the same order `describe` lists them, so it's the one you saw first; when no match is visible, the first match overall), 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` passes when the selector matches nothing. If `note` says it never matched, treat the check as failed and fix the selector. On iOS, a degraded empty tree does not report `hidden` success; the note gives the recovery hint.
-- Optional `timeoutMs` (default 5000) and `pollIntervalMs` (default 400).
+The tool's own description carries the conditions, selector matching, defaults and return shape. What it does not tell you:
 
-Returns `{ success, elapsed, note?, cause? }`. On failure, `note` describes the result. `cause` is `unmet`, `unreadable`, or `cancelled`. Only `unmet` means the tree was readable and the condition was false.
+- A `hidden` check that succeeds **immediately** may be a false pass — its `note` then says the selector never matched anything at all. Treat that as a failed check and fix the selector; do not read it as "the element went away".
+- The synthetic `ROOT` container `describe` prints is never matched, so a `role` like `AXGroup`/`html` won't trivially "match the screen".
+- To disambiguate a loose selector, pin the `role` to a text role like `StaticText` — that skips a same-named button.
+- On a `text` timeout the `note` quotes the text of the element the check actually read, so you can see which match it landed on.
 
 ### await-screen-idle — Block until the screen stops changing
 
@@ -297,18 +271,14 @@ For visual regression checks, before/after screenshot comparisons, and detailed
 
 ## 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.
+Use `run-sequence` to batch multiple interaction steps into **a single tool call**. Only one screenshot is returned — after all steps complete.
 
-Do **not** use `run-sequence` when any step depends on observing the result of a previous step
+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
+- "scroll to bottom", "scroll to top", "scroll until X" -> sequence 3-5 scrolls
+- form interactions, "clear and retype field" -> triple-tap to select all, then type the new value
 - "submit form" → fill all fields in sequence, tap submit
 - "go back to X" → defined tap sequence for the navigation
 
@@ -394,6 +364,10 @@ Stops on the first error (or unmet `await-ui-element` condition) and returns par
 - **Locked screen / secure surfaces**: `describe` throws a clear error if it can't capture (keyguard, DRM, Play Integrity). Unlock the device or fall back to `screenshot`.
 - **APK vs .app in `reinstall-app`**: pass `.apk` absolute path on Android; `.app` directory on iOS.
 
+### Chromium
+
+See `references/chromium.md` — tabs, cookies/storage.
+
 ### iOS
 
 _(no iOS-only gotchas collected here yet — add them as they come up)_

package/skills/argent-device-interact/references/chromium.md

@@ -0,0 +1,24 @@
+# Chromium (CDP) Targets
+
+Everything in the related SKILL.md still applies; this page covers what differs.
+
+## Multi-tab / windows
+
+A Chromium device may have several tabs / BrowserWindows. Use `chromium-tabs` to `list` them (stable ids `t1`, `t2`, …, optional labels), open a `new` one, `select` which is active, or `close` one.
+
+Every other tool (`describe`, `gesture-tap`, `screenshot`, `debugger-evaluate`, `open-url`, …) acts on the **active** tab, so `chromium-tabs action=select` before driving a different tab.
+
+Note: a cross-process navigation (some redirects) can swap a tab's underlying CDP target — re-run `chromium-tabs action=list` to pick it up under a fresh id.
+
+## Cookies & storage
+
+`chromium-cookies` reads/writes cookies via the Network domain (so HttpOnly cookies are visible):
+
+- `action=get` (optionally scoped by `url`)
+- `set` (`name`, `value`, + `url`/`domain`, optional `secure`/`httpOnly`/`sameSite`/`expires`)
+- `delete` (`name`)
+- `clear` (all)
+
+`chromium-storage` reads/writes Web Storage for the active page: `store=local|session`, `action=get` (one `key` or all entries), `set`, `remove`, `clear`.
+
+Both are per-origin / active-tab. Handy for seeding auth before a flow or asserting app state after one.

package/skills/argent-device-interact/references/secrets.md

@@ -0,0 +1,21 @@
+# Typing Secrets
+
+Where a `{{secret:<NAME>}}` placeholder gets its value, and the rules for using one. See the `keyboard` section of SKILL.md for the placeholder syntax itself.
+
+## Where the value comes from
+
+The placeholder is resolved on the machine running the tool-server, from the first of these that defines the name:
+
+| #   | Source                                        | Which keys it exposes                                                |
+| --- | --------------------------------------------- | -------------------------------------------------------------------- |
+| 1   | `ARGENT_SECRET_<NAME>` environment variable   | prefixed vars only — the CI-native path                              |
+| 2   | `<project>/.argent/secrets.env`               | every key (`APP_PASSWORD=…`) — gitignore this file                   |
+| 3   | `<project>/.env.local`, then `<project>/.env` | only `ARGENT_SECRET_`-prefixed keys, so app config stays unreachable |
+| 4   | `~/.argent/secrets.env`                       | every key — per-user, works in any project                           |
+
+## Rules
+
+- The result echoes the placeholder, never the value. An unknown name fails with the list of available secret _names_ and every source it looked in, with paths — read that list before asking the user anything.
+- The auto-screenshot after the call is skipped so the typed value cannot re-enter your context as pixels. Do **not** `describe` or `screenshot` a non-secure field you just filled with a secret — submit or navigate away first, then verify the resulting screen. To submit, put the text step and the Enter step in **one `run-sequence`**. The skip covers a whole batch that contains the placeholder, but a second bare `keyboard` call gets its own screenshot of the filled field.
+- Nothing outside those sources is reachable; never ask the user to paste a secret value into the conversation. Ask them to put it in a secrets file instead — a file edit applies to the next call, while an exported env var only reaches a tool-server started afterwards.
+- The project sources are found by walking up from the tool-server's working directory. If a project file is not being picked up, the failure's source list shows the paths actually consulted; `~/.argent/secrets.env` needs no project and always applies.