swipium 1.4.0 → 2.0.0

package/README.md

@@ -4,7 +4,7 @@
 
 # Swipium
 
-MCP server for simulator-based mobile QA agents.
+An MCP server that lets coding agents QA mobile apps on Android Emulators and iOS Simulators.
 
 [![npm version](https://img.shields.io/npm/v/swipium.svg)](https://www.npmjs.com/package/swipium)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
@@ -12,280 +12,236 @@ MCP server for simulator-based mobile QA agents.
 [![MCP](https://img.shields.io/badge/MCP-server-black.svg)](https://modelcontextprotocol.io)
 [![Platform](https://img.shields.io/badge/platform-Android%20Emulator%20%2B%20iOS%20Simulator-blue.svg)](https://swipium.com)
 
-Swipium lets an AI agent run practical mobile QA from a local MCP client: launch an app in an Android Emulator or iOS Simulator, inspect screens, act on the UI, run smoke checks, collect evidence, build an app knowledge map, generate reports, and create reusable test assets.
+Swipium gives an AI coding agent (Claude Code, Codex, Gemini CLI, Cursor, VS Code, and other MCP clients) the tools a QA engineer uses: find or build the app, boot a simulator, install and launch it, read the screen, tap and type through real user flows, and write a report backed by screenshots, logs, and UI dumps. A run can be turned into a repeatable flow, a test suite, or Appium code.
 
-Website: [swipium.com](https://swipium.com)
+It is for mobile developers who want their agent to catch the broken login screen before a TestFlight or Play Console build. It runs locally (stdio, no network listener), drives devices through `adb`, `simctl`, and WebDriverAgent rather than Appium, and asks your consent before anything with side effects. [swipium.com](https://swipium.com)
 
-## About
+### A session, abbreviated
 
-The goal of the MCP is to give your agent a ready-to-use suite of tools so it can test your application using an emulator and real user flows, not directly against the code, with the experience of a QA. Avoid reaching TestFlight or production only to find an error that could have been caught before making the build.
-
-Focused on mobile applications, for now.
-
-## What is Swipium?
-
-Swipium is not a replacement for a test runner. It is an agent-facing QA harness.
-
-It helps an agent answer requests like:
-
-- "Test it."
-- "Test this e2e flow."
-- "Create test automation for this app."
-- "Smoke test this app."
-- "Explore the login flow."
-- "Generate a report with evidence."
-- "Turn this run into a reusable flow."
-- "Create an automation suite from what you observed."
-
-The MCP server keeps the workflow deterministic where possible and explicit where risk exists. Heavy steps such as booting simulators, installing apps, writing files, or generating automation are exposed as tools with structured outputs, blockers, artifacts, and consent prompts.
-
-## QuickStart
-
-Run this from the mobile app repository:
-
-```bash
-npx -y swipium verify
+```text
+You:    Smoke test this app on Android with Swipium.
+Agent > qa_test_this { goal: "smoke" }                       (mode defaults to "plan": nothing runs)
+        plan for ~/code/shop-app (framework=react-native, session 3f9c2a1b)
+        target: android (will boot Pixel_8_API_35)
+        artifact: APK android/app/build/outputs/apk/release/app-release.apk
+          1. [ ] qa_prepare_target: Install + launch   2. [ ] qa_smoke   3. [ ] qa_report
+Agent > qa_test_this { sessionId: "3f9c2a1b", mode: "execute", goal: "smoke" }
+        🔐 Consent required (low): • boot_emulator: emulator -avd Pixel_8_API_35 -no-window
+                                   • install_apk: adb install -r -g android/app/.../app-release.apk
+You:    Approve                                               (one prompt covers boot + install)
+        state: "running", jobId: "a41c09e2"
+Agent > qa_job_status { sessionId: "3f9c2a1b", jobId: "a41c09e2", waitMs: 60000 }
+        status: "done", result.state: "completed"
+        reportSummary: "PASS app · COVERED coverage · PASS tool. Read swipium://session/3f9c2a1b/report/…"
+Agent:  The app launched and passed the smoke checks with no crashes or error screens.
 ```
 
-Add Swipium to your agent:
+The report behind that summary, rendered with `npx swipium report --latest --format markdown`, includes:
 
-```bash
-npm install -g swipium
-swipium init claude --apply --scope project
+```markdown
+**Release risk: 🟢 SHIP**
+
+**App status:** PASS - No high-severity app/native finding observed in this run.
+**Coverage status:** COVERED - Structured smoke/workflow evidence was collected.
+**Tool status:** PASS - No Swipium/MCP limitations or tool errors recorded in this run.
 ```
 
-Then ask the agent:
+## Contents
 
-```text
-Test this app with Swipium. Start with qa_test_this. Use Android Emulator or iOS Simulator only. Generate a report with evidence.
-```
+[Requirements](#requirements) · [Quickstart](#quickstart) · [Starter prompts](#starter-prompts) · [How it works](#how-it-works) · [Tools](#tools) · [Where results go](#where-results-go) · [Configuration](#configuration--environment-variables) · [CLI](#cli-reference) · [CI](#ci) · [Upgrading from 1.5](#upgrading-from-15) · [Troubleshooting](#troubleshooting) · [Security](#security)
 
-For a direct MCP configuration without a global install:
-
-```jsonc
-{
-  "mcpServers": {
-    "swipium": {
-      "command": "npx",
-      "args": ["-y", "swipium"],
-      "cwd": "/absolute/path/to/your/mobile-app",
-      "timeout": 600000
-    }
-  }
-}
-```
+## Requirements
 
-## Installation
+**Node.js 20 or newer.** Swipium works with emulators and simulators only; physical devices are refused with `PHYSICAL_DEVICE_UNSUPPORTED` ([why](docs/physical-devices.md)).
 
-Run without installing:
+| Host | Android Emulator | iOS Simulator |
+| --- | --- | --- |
+| macOS | Supported | Supported (Xcode with a Simulator runtime) |
+| Linux | Supported | Not available |
+| Windows | Experimental and untested; some process-cleanup helpers rely on `ps` | Not available |
 
-```bash
-npx -y swipium verify
-```
+| Your app | What Swipium needs |
+| --- | --- |
+| React Native / Expo, debug build | Metro serving the JS bundle. `qa_metro` can start it (consent-gated); otherwise the run stops with `METRO_REQUIRED`. |
+| React Native / Expo release, or native Android / iOS | An installable artifact (APK or `.aab` for Android, a simulator `.app` for iOS; a device `.ipa` is refused) or a project Swipium can build. |
+| Expo managed (no `android/` or `ios/`) | Run `npx expo prebuild` first. Without native directories the build fails with `EXPO_PREBUILD_REQUIRED`. |
+| Flutter | A buildable Flutter project, or a built APK / `.app`. |
 
-Install globally:
+- **Android:** platform-tools, the Emulator, and at least one AVD (usually via Android Studio). `adb` on your `PATH` is used if present, else the SDK copy from `$ANDROID_HOME`, `$ANDROID_SDK_ROOT`, or the default SDK location (`~/Library/Android/sdk`, `~/Android/Sdk`, `%LOCALAPPDATA%\Android\Sdk`). The `emulator` binary that boots AVDs and `aapt2` come from the SDK first. `.aab` files need bundletool.
+- **iOS (macOS only):** Xcode and a simulator. Taps, typing, and UI-tree snapshots need **WebDriverAgent** (WDA, the on-simulator automation server Appium uses); without it iOS is visual-only ([iOS modes](docs/concepts.md#ios-modes)).
 
-```bash
-npm install -g swipium
-swipium verify
-```
+## Quickstart
 
-Install in a project:
+**1. Register Swipium with your client.** From your app repository, for Claude Code:
 
 ```bash
-npm install --save-dev swipium
-npx swipium verify
+npx -y swipium init claude --scope project           # preview; changes nothing
+npx -y swipium init claude --scope project --apply   # writes .mcp.json, then runs `swipium verify`
 ```
 
-Requirements:
+The same command handles `codex`, `gemini`, `cursor`, and `vscode` (`swipium init <client> --apply`). Claude Desktop, Windsurf, manual configs, and per-client details are in **[docs/mcp-server.md](docs/mcp-server.md)**.
 
-- Node.js 20 or newer.
-- Android Studio for Android Emulator workflows.
-- Xcode for iOS Simulator workflows.
-- A simulator-ready app artifact when testing iOS, such as a simulator `.app`.
-- An APK or buildable Android project when testing Android.
+**2. Restart the client** and check that it lists `qa_test_this`, `qa_doctor`, and `qa_report`.
 
-## Usage
-
-Start with the autopilot tool:
+**3. Ask the agent to test the app:**
 
 ```text
-qa_test_this {
-  "projectRoot": "/absolute/path/to/app",
-  "mode": "execute",
-  "goal": "smoke"
-}
+Use Swipium to smoke test this app. Run qa_doctor, then qa_test_this with
+mode "execute" and goal "smoke", poll qa_job_status until the job finishes,
+and summarize the report.
 ```
 
-Common workflow:
+`mode:"execute"` matters: the default `mode:"plan"` has no side effects and only returns what would happen. `goal:"smoke"` is the fastest path. With no `goal`, `qa_test_this` runs the smoke check and then tries to generate a test suite.
 
-1. `qa_doctor` checks local toolchain readiness. Use `platform:"android"`, `platform:"ios"`, or `platform:"both"`.
-2. `qa_test_this` resolves the project, artifact, and simulator target.
-3. `qa_job_status` polls long-running work.
-4. `qa_smoke` or `qa_explore` runs the app.
-5. `qa_report` produces the evidence report, including separate app and coverage verdicts.
-6. `qa_app_map_read` or `qa_app_map_query` reads the durable app map.
-7. `qa_flow_generate`, `qa_suite_generate`, or `qa_automation_generate` creates reusable QA assets.
+If a tool returns `PROJECT_ROOT_UNRESOLVED`, name the absolute project path in your prompt or set `SWIPIUM_PROJECT_ROOT` in the server config ([Project root](docs/concepts.md#project-root)).
 
-CLI helpers:
+### What you'll see
 
-```bash
-swipium verify                 # starts the server and checks tool injection
-swipium init claude            # preview Claude Code registration
-swipium init gemini            # preview Gemini registration
-swipium init codex             # preview Codex config
-swipium init flows             # create starter flow templates
-swipium scan                   # scan project context
-swipium suite                  # local suite helper
-```
+- **One approval prompt** listing the exact build, boot, and install commands. Clients with MCP elicitation show a real prompt; others return `requiresConsent`, which the agent must relay to you.
+- **The first build can take minutes.** The run is a background job the agent polls with `qa_job_status`.
+- **Two states.** The job `status` is `running`, `done`, `failed`, or `cancelled`. The run's `result.state` is `completed` or `needs_input` (job `done`), or `blocked` or `unsafe` (job `failed`). `needs_input` means one question for you, such as login credentials.
+- **A report** with separate verdicts for the app, coverage, and Swipium itself. Read it with `npx swipium report --latest --format markdown`.
 
-## MCP Server
+## Starter prompts
 
-Swipium runs as a stdio MCP server. MCP clients launch it as a local process and communicate through JSON-RPC over stdin and stdout.
+| Goal | Prompt |
+| --- | --- |
+| Smoke test | "Use Swipium to smoke test this app: qa_test_this mode execute, goal smoke, then summarize the report." |
+| Test login | "Use Swipium to test login with goal test_login. Don't ask me for the password: type `${SWIPIUM_TEST_EMAIL}` and `${SWIPIUM_TEST_PASSWORD}` with qa_act." (set both in the server `env`; placeholders expand server-side and secret values are redacted) |
+| Reproduce a bug | "Use Swipium to reproduce this bug with goal reproduce_bug and goalText: 'checkout button does nothing after adding a coupon'. Attach the evidence." |
+| Save a flow | "Turn the last Swipium run into a flow named login-smoke with qa_generate and save it." |
+| Release gate | "Run Swipium with goal release_gate and tell me whether the release gate passes." |
 
-Manual MCP configuration:
+Clients that support MCP prompts can use the built-in ones instead: `swipium_setup_check`, `swipium_guardrail_validation`, `swipium_full_smoke`, `swipium_bug_repro`, and `swipium_convert_run_to_flow`.
 
-```jsonc
-{
-  "mcpServers": {
-    "swipium": {
-      "command": "npx",
-      "args": ["-y", "swipium"],
-      "cwd": "/absolute/path/to/your/mobile-app",
-      "timeout": 600000
-    }
-  }
-}
-```
+## How it works
 
-Installed binary configuration:
-
-```jsonc
-{
-  "mcpServers": {
-    "swipium": {
-      "command": "swipium",
-      "args": [],
-      "cwd": "/absolute/path/to/your/mobile-app",
-      "timeout": 600000
-    }
-  }
-}
+```text
+qa_test_this {mode:"plan"}  >  qa_test_this {mode:"execute"}  >  consent  >  job
+                                                                               │
+                         qa_job_status {waitMs} ◄──────────────────────────────┘
+                           ├─ completed / blocked / unsafe  >  report (qa_get_artifact reportUri)
+                           └─ needs_input  >  ask you one question  >  qa_continue_from_blocker
 ```
 
-Important:
+`qa_test_this` finds or builds the app, boots a simulator, installs and launches the app, runs a smoke check (plus exploration or suite generation, per `goal`), and always writes a report. Failures carry a `failureCode` that `qa_explain_blocker` explains. For hands-on work the agent opens a session (`qa_start_session`), reads the screen with `qa_snapshot`, and acts on element refs such as `@e3`.
 
-- Set `cwd` to the mobile app repository.
-- Restart the MCP client after installing or upgrading.
-- Run `qa_doctor` if tools are missing or stale.
-- Use `qa_get_artifact` for report, screenshot, dump, and log artifacts.
+Concepts, explained in **[docs/concepts.md](docs/concepts.md)**:
 
-More detail: [docs/mcp-server.md](docs/mcp-server.md)
+- **[Project root](docs/concepts.md#project-root):** the repository under test, from the `projectRoot` argument, MCP roots, `SWIPIUM_PROJECT_ROOT`, `CLAUDE_PROJECT_DIR`, or the server's working directory.
+- **[Consent](docs/concepts.md#consent):** builds, boots, installs, data wipes, network changes, and repo-supplied commands need your single-use approval.
+- **[Sessions and jobs](docs/concepts.md#sessions-and-jobs):** a session holds one run's device, app, and evidence; long work is a job you poll.
+- **[Secrets and redaction](docs/concepts.md#secrets-and-redaction):** credentials are redacted from text output; screenshots are not.
+- **[iOS modes](docs/concepts.md#ios-modes):** visual-only through `simctl`, or full interaction with WDA.
+- The **app map** is Swipium's durable memory of your app's screens; a **flow** is a replayable YAML script ([docs/flows.md](docs/flows.md)); a **POM suite** is a generated page-object test suite. See the [glossary](docs/concepts.md#glossary).
 
-## Agent Integration
+## Tools
 
-### Claude Code
+Grouped by capability (`qa_status` without arguments returns the same groups). Every tool's parameters and behavior are in **[docs/tools.md](docs/tools.md)**; `swipium verify` lists what your installed version exposes.
 
-Global install:
-
-```bash
-npm install -g swipium
-swipium init claude --apply --scope project
-```
+| Group | Tools |
+| --- | --- |
+| Start | `qa_test_this`, `qa_status`, `qa_job_status`, `qa_job_cancel`, `qa_explain_blocker`, `qa_continue_from_blocker`, `qa_get_artifact` |
+| Setup | `qa_doctor`, `qa_start_session`, `qa_prepare_target`, `qa_prepare_ios_target`, `qa_ios`, `qa_wda` |
+| Build | `qa_resolve_target`, `qa_resolve_artifact`, `qa_build`, `qa_bundletool` |
+| Device | `qa_device_info`, `qa_orientation`, `qa_geolocation`, `qa_network`, `qa_metro`, `qa_app_control`, `qa_screen_record` |
+| Drive | `qa_snapshot`, `qa_inspect`, `qa_act`, `qa_clear_overlay`, `qa_check_health`, `qa_screenshot`, `qa_note`, `qa_visual`, `qa_wait` |
+| Run | `qa_smoke`, `qa_explore`, `qa_report` |
+| App map | `qa_app_map_build`, `qa_app_map_read`, `qa_app_map_query`, `qa_app_map_feature_scope`, `qa_app_map_update` |
+| Feature | `qa_test_feature` |
+| Flows | `qa_flow_check`, `qa_flow_run`, `qa_flow_compile`, `qa_flow_repair` |
+| Generate | `qa_generate` |
+| Test suite | `qa_suite_read`, `qa_suite_update`, `qa_suite_generate`, `qa_suite_export`, `qa_suite_lint` |
+| Issues | `qa_issue_log`, `qa_mobile_audit` |
+| First run | `qa_first_run` |
 
-No global install:
+Every tool carries MCP annotations: read-only tools declare `readOnlyHint:true` and `openWorldHint:false` (so clients can auto-approve them); the rest also declare `destructiveHint` and `idempotentHint`.
 
-```bash
-claude mcp add swipium --scope project -- npx -y swipium
-```
+## Where results go
 
-### Gemini CLI
+- **`<your repo>/.swipium/`:** app map, flows, test suite, issue ledger, visual baselines, generated files, and your configuration (`config.json`, `fixtures.json`, `policy.json`). The first time Swipium writes the app map or issue ledger in a Git repository, it adds `.swipium/` to `.gitignore`. Never pruned automatically.
+- **`~/.swipium/runs/`:** per-session state and evidence (screenshots, logs, UI dumps, reports), returned as `swipium://` URIs. When a server process first loads its session registry, it prunes in the background session directories older than `SWIPIUM_RETENTION_DAYS`, keeping registered sessions and the newest `SWIPIUM_RETENTION_KEEP` per project. `swipium gc` cleans up on demand.
 
-Global install:
+## Configuration & environment variables
 
-```bash
-npm install -g swipium
-swipium init gemini --apply
-```
+Set these in the MCP server's `env` block (or your shell, for CLI commands). This is the complete list.
 
-No global install:
+| Variable | Purpose |
+| --- | --- |
+| `SWIPIUM_PROJECT_ROOT` | Absolute path of the app repository when the client provides no MCP roots. |
+| `CLAUDE_PROJECT_DIR` | Set by Claude Code; used as the project root after `SWIPIUM_PROJECT_ROOT`. |
+| `ANDROID_HOME`, `ANDROID_SDK_ROOT` | Android SDK location, searched for `adb`, `emulator`, and `aapt2` (see [Requirements](#requirements)). |
+| `BUNDLETOOL_JAR` | Path to `bundletool.jar` for converting `.aab` files. A `bundletool` launcher on `PATH` also works. |
+| `DEVELOPMENT_TEAM`, `XCODE_DEVELOPMENT_TEAM` | Apple team ID for signing WDA (`ios.wda.developmentTeam` in `.swipium/config.json` takes precedence). |
+| `APPIUM_HOME` | Extra location searched for an Appium-installed WDA (besides `~/.appium` and global npm). |
+| `WDA_PROJECT_PATH`, `WEBDRIVERAGENT_PROJECT` | Extra `WebDriverAgent.xcodeproj` candidates reported by `qa_doctor` and `qa_wda` status (to build one, pass `wdaProjectPath`). |
+| `SWIPIUM_ALLOW_REMOTE_WDA` | Comma-separated exact non-loopback WDA base URLs you pre-approve. Set it in your client config, never in the repository. |
+| `SWIPIUM_TEST_*` | Test-account values: `_EMAIL`, `_USERNAME`, `_PASSWORD`, `_OTP`, `_TOKEN`, `_PIN`. Flows and `qa_act` use `${SWIPIUM_TEST_EMAIL}`; `fixtures.json` uses `"var": "SWIPIUM_TEST_EMAIL"`. |
+| Other `SWIPIUM_*` | Flows and fixtures read **only** `SWIPIUM_*` names from the environment (never `${HOME}` or `${AWS_SECRET_ACCESS_KEY}`). Names containing `pass`, `secret`, `token`, `otp`, `pin`, `cvv`, `key`, or `code` are secrets and redacted. |
+| `SWIPIUM_OCR_CMD` | OCR command for `qa_visual` `find_text` (none bundled; consent-gated). `{image}` becomes a PNG path; it prints `[{"text","confidence","bbox"}]` JSON. `ocrCommand` in `config.json` wins. |
+| `SWIPIUM_VISUAL_MASK_CMD` | Masks screenshots before OCR and visual providers see them (`visualMaskCommand` in config wins). |
+| `SWIPIUM_REQUIRE_ELICITATION=1` | Refuse every consent-gated action (`CONSENT_REFUSED`) when the client can't show a real consent prompt. |
+| `SWIPIUM_RETENTION_DAYS` | Age limit in days for `~/.swipium/runs` session directories (default 30). `0` or `off` disables the automatic prune; `swipium gc` still works. |
+| `SWIPIUM_RETENTION_KEEP` | Number of newest sessions per project always kept (default 20). |
+| `CI` | When set, reports label the run environment as CI. |
+| `SWIPIUM_DISABLE_DEVICE_DISCOVERY` | Test-suite isolation only: disables device auto-discovery. Not for normal use. |
+
+Generated flows, suites, and code never contain credential values; they reference `SWIPIUM_TEST_*`, `SWIPIUM_SECRET_N`, or `SWIPIUM_GEN_<FIELD>`, which you set when replaying. Generated Appium projects read their own variables (`SWIPIUM_PLATFORM`, `APPIUM_HOST`, `ANDROID_*`, `IOS_*`, …), documented in their README.
+
+## CLI reference
+
+With no subcommand, `swipium` runs the stdio MCP server (what clients launch). `swipium --help` prints this list.
+
+| Command | What it does |
+| --- | --- |
+| `swipium` (alias `swipium serve`) | Start the stdio MCP server. Unrecognized flags alone (such as `--stdio`) are ignored with a warning; an unknown subcommand prints usage and exits 2. |
+| `swipium init <client> [--apply] [--scope local\|user\|project] [--cwd <dir>]` | Preview (default) or apply the registration for `claude`, `codex`, `gemini`, `cursor`, or `vscode`. See [docs/mcp-server.md](docs/mcp-server.md). |
+| `swipium init flows [--root <dir>] [--force]` | Write starter flow templates into `.swipium/flows/` (existing files kept unless `--force`). |
+| `swipium verify` | Start the server over stdio, check that every tool is listed, and run `qa_doctor`. |
+| `swipium scan [path] [--check \| --dry-run \| --no-write]` | Print a readiness report. Creates `.swipium/` unless the result is `BLOCKED` or a no-write flag is set. |
+| `swipium suite <lint\|compile\|init> [projectRoot] [--suite <file>]` | `lint` flags brittle page-object locators, `compile` turns a POM suite into flows under `.swipium/flows/`, `init` explains suites. |
+| `swipium report --format junit\|sarif\|github-summary\|markdown\|json` | Render a saved report (`--latest` default, `--session`, `--report`, `--root`, `--out`, `--fail-on-gate`). Exits 1 when the gate blocks with `--fail-on-gate`, 2 on usage error or no report. |
+| `swipium gc [--dry-run] [--days N] [--keep N]` | Delete old `~/.swipium/runs` session directories and stale `~/.swipium/projects.json` entries. |
+| `swipium --help` / `-h`, `--version` / `-v` | Print usage or the version. |
 
-```bash
-gemini mcp add swipium npx -y swipium
-```
+## CI
 
-### Codex
+`swipium report` renders a finished run as JUnit, SARIF, a GitHub job summary, Markdown, or JSON; `--fail-on-gate` fails the job when the `.swipium/policy.json` release gate blocks. The CLI does not drive devices: CI still needs an agent (such as headless Claude Code) calling the MCP tools, including `qa_flow_run` to replay saved flows. Nobody can approve consent in CI, so install the app before the agent step. Recipe: **[docs/ci-reports.md](docs/ci-reports.md)**.
 
-Global install:
+## Upgrading from 1.5
 
-```bash
-npm install -g swipium
-swipium init codex --apply
-```
+2.0.0 removes and renames tools and tightens defaults. Work through this list:
 
-Manual Codex config:
+1. **Restart your MCP client.** A client still running the old server gets `STALE_CLIENT` for removed tools and old call shapes.
+2. **Rename environment variables your flows and fixtures read** so they start with `SWIPIUM_` (for example `${TEST_PASSWORD}` becomes `${SWIPIUM_TEST_PASSWORD}`). Other names are no longer read from the environment.
+3. **CI: every app install now asks for consent**, including an APK inside the project. Install the app yourself before the agent step ([docs/ci-reports.md](docs/ci-reports.md)).
+4. **Saved prompts and scripts:** replace removed tools using the [migration table](CHANGELOG.md#migrating-from-150) (also in [docs/tools.md](docs/tools.md#migrating-from-150)), and drop arguments a tool doesn't declare; they now fail with `INVALID_ARGUMENT` instead of being ignored.
+5. **Remote WDA:** `ios.wda.allowNonLoopbackUrls` in `.swipium/config.json` no longer pre-approves a URL. Pass `allowNonLoopback:true` and approve the consent, or list the URL in `SWIPIUM_ALLOW_REMOTE_WDA` in your client config.
+6. **Scripts calling `swipium <unknown>`** now exit 2 instead of starting the server.
+7. **Metro and WDA processes started by 1.5.x** are not cleaned up automatically. Stop them yourself: the Metro process on port 8081 and any old WebDriverAgent `xcodebuild`.
+8. **Known issue:** the first time an iOS session from before the upgrade is rebound, the app may be relaunched once.
 
-```toml
-[mcp_servers.swipium]
-command = "npx"
-args = ["-y", "swipium"]
-cwd = "/absolute/path/to/your/mobile-app"
-```
-
-After setup, verify that the client lists `qa_test_this`, `qa_capabilities`, and `qa_report`.
-
-## Tool Docs
+## Troubleshooting
 
-Swipium exposes 95 public MCP tools. Start with `qa_test_this` for low-context requests.
+Every error has a `failureCode`, `nextSteps`, and `retrySafe`. `qa_explain_blocker` explains any code, `qa_doctor` checks the toolchain, and the full catalog is in [docs/tools.md](docs/tools.md#failure-codes).
 
-Full reference: [docs/tools.md](docs/tools.md)
+| `failureCode` | Meaning | What to do |
+| --- | --- | --- |
+| `PROJECT_ROOT_UNRESOLVED` | Swipium can't tell which app to test. | Name the absolute path in the prompt or set `SWIPIUM_PROJECT_ROOT` ([project root](docs/concepts.md#project-root)). |
+| `STALE_CLIENT` | The client runs a pre-upgrade server or uses a removed tool. | Restart the MCP client. |
+| `ADB_NOT_FOUND` | Android platform-tools can't be found. | Install them via Android Studio; set `ANDROID_HOME` in the server `env` for GUI clients or non-default locations. |
+| `NO_DEVICE` | No emulator is online and none can be booted. | Create an AVD or iOS Simulator; `qa_test_this` boots it for you. |
+| `PHYSICAL_DEVICE_UNSUPPORTED` | Only a real phone is available. | Start an emulator, or unplug the phone. |
+| `METRO_REQUIRED` | A debug RN/Expo build needs Metro serving. | Start Metro (`qa_metro {action:"start"}` or `npx react-native start` / `npx expo start`), then retry. |
+| `EXPO_PREBUILD_REQUIRED` | The Expo project has no native directories. | Run `npx expo prebuild`, then retry. |
+| `WDA_UNREACHABLE` | WebDriverAgent isn't running or answering. | `qa_wda {action:"status"}`, then `start` or `attach`. For a plain smoke check, use `goal:"smoke"`, which works visual-only. |
+| `BACKEND_UNSUPPORTED` | The action needs WDA (iOS visual-only mode). | Attach WDA with `qa_wda`, or use `qa_visual` and `qa_screenshot`. |
+| `CONSENT_DECLINED` / `CONSENT_CANCELLED` / `CONSENT_REFUSED` | Nothing ran: you declined, the prompt was dismissed or timed out, or `SWIPIUM_REQUIRE_ELICITATION=1` blocked it. | Re-call to get a fresh prompt if you want the action. |
 
-New in 1.4.0 — 4 additional tools, all backward compatible:
+## Security
 
-- **`qa_inspect`** — return the full attributes of a single `@eN` element from the latest snapshot, without dumping the whole tree.
-- **`qa_next_best_action`** — a deterministic recommendation of the single best next tool to call (with args) and why.
-- **`qa_app_map_update`** / **`qa_app_map_diff`** — targeted provenance-tracked app-map updates, and a diff between two map snapshots.
+Swipium is a local stdio process with no network listener. Actions with side effects need your [consent](docs/concepts.md#consent), known secret values are [redacted](docs/concepts.md#secrets-and-redaction) from snapshots, artifacts, and reports, and generated output is checked for leaked secrets. A cloned repository's `.swipium/` is treated as untrusted: repo-supplied commands are shown verbatim in the consent prompt, flows read only `SWIPIUM_*` variables, and Swipium never runs `git`. Screenshots are never redacted, so use `qa_start_session { sensitive: true }` to refuse all screen captures when that matters. Details: [Threat Model](THREAT_MODEL.md). Report vulnerabilities privately per the [Security Policy](SECURITY.md).
 
-Earlier releases added device-parity, local-first visual, seeded-state, report-history (1.1.0); durable issue memory, persistent test suite, flow plan/repair, Maestro interop, agent helpers (1.2.0); and feature-focused testing plus local build/artifact resolution (1.3.0).
+## Contributing and license
 
-| Group | Tools |
-| --- | --- |
-| Start | `qa_agent_brief`, `qa_capabilities`, `qa_test_this`, `qa_job_status`, `qa_job_cancel`, `qa_status`, `qa_explain_blocker`, `qa_continue_from_blocker`, `qa_next_best_action`, `qa_get_artifact` |
-| Setup | `qa_doctor`, `qa_start_session`, `qa_detect_context`, `qa_plan`, `qa_prepare_target`, `qa_prepare_ios_target`, `qa_ios`, `qa_wda` |
-| Build | `qa_resolve_target`, `qa_resolve_artifact`, `qa_build_plan`, `qa_build`, `qa_bundletool` |
-| Device | `qa_device_info`, `qa_permissions`, `qa_orientation`, `qa_geolocation`, `qa_network`, `qa_metro`, `qa_app_control`, `qa_screen_info`, `qa_screen_record` |
-| Drive | `qa_snapshot`, `qa_inspect`, `qa_act`, `qa_clear_overlay`, `qa_check_health`, `qa_screenshot`, `qa_note`, `qa_assert_visual`, `qa_visual`, `qa_visual_find_text`, `qa_locator_suggest`, `qa_input_capabilities`, `qa_wait`, `qa_idling_status` |
-| State | `qa_seed`, `qa_state_prepare`, `qa_state_verify`, `qa_state_teardown` |
-| Run | `qa_smoke`, `qa_explore`, `qa_report`, `qa_report_compare`, `qa_run_history` |
-| App map | `qa_app_map_build`, `qa_app_map_read`, `qa_app_map_query`, `qa_app_map_update`, `qa_app_map_diff`, `qa_app_map_feature_scope`, `qa_app_map_validate` |
-| Feature | `qa_feature_scope`, `qa_feature_test_plan`, `qa_test_feature` |
-| Flows and suites | `qa_flow_check`, `qa_flow_plan`, `qa_flow_run`, `qa_flow_generate`, `qa_flow_repair`, `qa_suite_generate`, `qa_suite_compile`, `qa_suite_lint`, `qa_pom_generate`, `qa_testcase_generate` |
-| Test suite | `qa_test_suite_read`, `qa_test_suite_update`, `qa_test_suite_generate`, `qa_test_suite_export`, `qa_test_suite_lint` |
-| Interop | `qa_maestro_import`, `qa_maestro_export` |
-| Issues | `qa_issue_log`, `qa_issue_history`, `qa_issue_mark_fixed`, `qa_issue_triage`, `qa_issue_suppress`, `qa_issue_verify_fixed`, `qa_issue_metrics`, `qa_mobile_audit` |
-| First run | `qa_first_run_plan`, `qa_first_run_continue` |
-| Automation | `qa_automation_plan`, `qa_automation_generate`, `qa_automation_validate` |
-
-## Why Swipium?
-
-- Agent-native: exposes QA work as MCP tools with structured outputs.
-- Simulator-first: focuses on Android Emulator and iOS Simulator reliability.
-- Evidence-first: screenshots, logs, reports, dumps, and artifacts are stored and linked.
-- App memory: the app map preserves screens, features, test cases, flows, and coverage context.
-- Practical consent: mutating actions are gated instead of hidden behind agent text.
-- Reusable output: exploratory runs can become flows, test cases, suites, and generated automation.
-- Local by default: the server runs on the developer machine and uses local simulators.
-
-## Docs
-
-- [MCP Server](docs/mcp-server.md)
-- [Tool Reference](docs/tools.md)
-- [Project Docs Index](docs/README.md)
-- [Security Policy](SECURITY.md)
-- [Contributing](CONTRIBUTING.md)
-- [Support](SUPPORT.md)
-- [Changelog](CHANGELOG.md)
-
-## License
-
-MIT. See [LICENSE](LICENSE).
+See [CONTRIBUTING.md](CONTRIBUTING.md), [SUPPORT.md](SUPPORT.md), the [docs index](docs/README.md), and the [CHANGELOG](CHANGELOG.md). MIT licensed; see [LICENSE](LICENSE).