swipium 1.4.0 → 2.0.0

package/docs/flows.md

@@ -0,0 +1,153 @@
+# Flows
+
+A flow is a replayable YAML script of steps under `.swipium/flows/`. Flows are the Flow V2 format: selector-bound input, visual steps, device-relative gestures, waits, setup and teardown, and a `structured`, `visual`, or `auto` mode. This page covers the file format, variables, starter templates, compiling and repairing, and the CI policy. The tools themselves (`qa_flow_check`, `qa_flow_run`, `qa_flow_compile`, `qa_flow_repair`, `qa_smoke`) are in the [Tool Reference](tools.md#flows).
+
+**Contents**: [Example](#example) · [File format](#file-format) · [Step reference](#step-reference) · [Variables](#variables) · [Starter templates](#starter-templates) · [Compile and repair](#compile-and-repair) · [CI policy](#ci-policy)
+
+## Example
+
+`.swipium/flows/login-smoke.yaml`:
+
+```yaml
+name: login_smoke
+mode: structured
+fixtures:
+  - test_account
+setup:
+  - prepareTarget
+steps:
+  - waitForVisible: "Email"
+  - inputText:
+      into: "Email"
+      text: "${SWIPIUM_TEST_EMAIL}"
+  - inputText:
+      into: "Password"
+      text: "${SWIPIUM_TEST_PASSWORD}"
+  - tap: "Sign in"
+  - waitForVisible:
+      text: "Home"
+      timeoutMs: 12000
+  - assertVisible: "Home"
+```
+
+Validate it with `qa_flow_check {flow:"login-smoke"}`, then run it on a prepared session with `qa_flow_run {sessionId, flow:"login-smoke"}`. The password is typed but treated as a secret, because its variable name contains `pass`.
+
+## File format
+
+A flow is a YAML map with a non-empty `name` and a non-empty `steps` list.
+
+| Key | Meaning |
+| --- | --- |
+| `name` | Required. |
+| `steps` | Required, non-empty. Runs are fail-fast: the first failing step stops the flow. Mutating steps are never retried automatically. |
+| `setup` | Steps that run before `steps`. |
+| `teardown` | Steps that always run afterwards, even after a failure. |
+| `mode` | `structured` (default: needs a UI tree), `visual` (screenshot-based), or `auto`. A structured flow on an iOS Simulator without WDA, or in a visual-fallback session, is refused with `BACKEND_UNSUPPORTED`. |
+| `appId` | The app `prepareTarget` and `restartApp` act on (default: the session's app). |
+| `fixtures` | Names of fixtures the flow needs (from `qa_start_session` or `.swipium/fixtures.json`). |
+| `budgetProfile` | A budget profile label, such as `guardrail` or `full_smoke`. |
+
+Each step is either a bare word (`prepareTarget`, `restartApp`, `waitForIdle`, `clearOverlay`, `networkOffline`, `networkOnline`) or a map with exactly one key. Variables are referenced inline as `${NAME}`; there is no top-level variables block.
+
+**Selectors** (in `tap`, `inputText into`, `assertVisible`, `waitForVisible`, and similar steps):
+
+- Plain text matches an element's text, content description, or id (case-insensitive substring).
+- `id=<resource-id>` matches an Android resource id.
+- `accessibility id=…`, `name=…`, `predicate string=…`, and `class chain=…` are native WDA selectors on iOS.
+
+Prefer durable ids (`testID`, `accessibilityIdentifier`, resource ids) over visible text; `qa_flow_check` warns about platform-specific or brittle locators.
+
+## Step reference
+
+| Step | Form | What it does |
+| --- | --- | --- |
+| `prepareTarget` | bare | Launches the flow's app and waits for the screen to settle. |
+| `restartApp` | bare | Force-stops and relaunches the app. Mutating. |
+| `tap` | `tap: "<selector>"` | Taps an element. |
+| `tapAt` | `tapAt: [x, y]` | Taps a coordinate. Coordinate-only flows are flagged as brittle. |
+| `tapImage` | `tapImage: <png>` or `{template, minScore}` | Template-matches a PNG and taps it. |
+| `tapOcrText` | `tapOcrText: "<text>"` or `{text, minConfidence}` | Finds text by OCR and taps it. Needs an OCR provider. |
+| `inputText` | `inputText: "<text>"` or `{into, text, secret}` | Types text; `into` focuses a field first. `secret` defaults to true when the text references a credential-like variable. |
+| `assertVisible` | `assertVisible: "<selector>"` | Fails with `ASSERTION_FAILED` when not visible. |
+| `assertNotVisible` | `assertNotVisible: "<selector>"` | Fails when visible. |
+| `assertImage` | `assertImage: <png>` or `{template, minScore}` | Asserts a PNG template is on screen. |
+| `assertOcrText` | `assertOcrText: "<text>"` or `{text, minConfidence}` | Asserts text by OCR. |
+| `assertVisual` | `assertVisual: "<description>"` | Captures screenshot evidence and records a visual checkpoint for a human. It does not fail. |
+| `assertDiff` | `assertDiff: <baseline>` or `{baseline, threshold}` | Compares the screen to a saved `qa_visual` baseline. |
+| `swipe` | `swipe: up` or `{direction, area, distance}` | Device-relative swipe. `area` is `center`, `top`, `bottom`, `left`, or `right`; `distance` is a fraction of the screen (default 0.6). |
+| `scrollTo` | `scrollTo: "<selector>"` | Swipes until the target is visible (up to 8 swipes). |
+| `press` | `press: back`, `home`, or `enter` | Presses a key. |
+| `openUrl` | `openUrl: "<url>"` | Opens a deep link or URL. Mutating when the URL contains a `${VAR}`. |
+| `wait` | `wait: <ms>` or `{text}` / `{id}` | Waits a fixed time, or for an element. |
+| `waitForIdle` | bare, or `waitForIdle: <timeoutMs>` | Waits for the UI to settle. |
+| `waitForVisible` | `waitForVisible: "<selector>"` or `{text` / `id` / `"accessibility id", timeoutMs}` | Waits for an element to appear. |
+| `clearOverlay` | bare | Clears a blocking overlay (see below). |
+| `networkOffline`, `networkOnline` | bare | Turns airplane mode on or off (Android 11+). Mutating. |
+| `seed` | `seed: <fixture>` | Runs the fixture's `seed` spec (deeplink, script, or API call). Mutating. |
+| `note` | `note: "<reason>"` or `{outcome, reason}` | Records a workflow outcome (`pass` by default). |
+| `screenshot` | `screenshot: "<reason>"` | Captures evidence. |
+
+**`clearOverlay`** hides an open keyboard and does nothing else. Otherwise, on Android it presses BACK only when a BACK-dismissible overlay is actually open (a dialog, sheet, permission prompt, or RN LogBox or RedBox), never on a bare screen and never for a snackbar or banner; with nothing to clear it reports `nothingCleared:true`. On iOS it dismisses alerts and sheets with the native alert API. When the backend has no alert API or the overlay survives, the step reports `nothingCleared:false` with a note instead of claiming success.
+
+**Mutating steps** are `networkOffline`, `networkOnline`, `seed`, `restartApp`, and `openUrl` with a `${VAR}` in its URL. They, and the OCR steps `tapOcrText` and `assertOcrText` (which send screenshots to an external provider), need the `flow_mutation_run` consent in `qa_flow_run` (risk high for script seeds, otherwise medium). `qa_smoke` never runs such a flow implicitly: it records it as `blocked` (category `destructive_refused`) with a pointer to `qa_flow_run`. OCR steps are refused in sensitive sessions (`UNSAFE_ACTION_REFUSED`).
+
+**Paths**: `tapImage` and `assertImage` templates and `assertDiff` baselines must resolve (after symlinks) inside the project root, otherwise the step fails with `UNSAFE_ACTION_REFUSED`.
+
+**Sensitive sessions**: `screenshot`, `assertVisual`, and failure evidence are not captured; the step detail says so, and an `assertVisual` checkpoint is recorded as `skipped`.
+
+## Variables
+
+`${NAME}` resolves in this order:
+
+1. **Explicit variables**: `qa_flow_run {variables:{…}}` (or `qa_smoke {variables}`).
+2. **Stored session inputs**: values supplied through a needs-input answer (`qa_continue_from_blocker`) or first-run credentials. Values are never echoed; only their names are listed in `notes`.
+3. **The server environment, for `SWIPIUM_*` names only.** Any other environment variable is never read, because a flow file can come from an untrusted repository. The step fails with `MISSING_FIXTURE` and a message such as `Variables not available: HOME (flows only read SWIPIUM_* environment variables; pass it via qa_flow_run { variables } or rename it SWIPIUM_HOME)`.
+
+A missing variable is not locator drift, so the failure does not point at `qa_flow_repair`.
+
+**Secret names**: a variable whose name contains `pass`, `secret`, `token`, `otp`, `pin`, `cvv`, `key`, or `code` (case-insensitive) is a credential. Its resolved value joins the session's redaction set and is scrubbed everywhere, and `inputText` treats it as secret. So `SWIPIUM_TEST_PASSWORD` and `SWIPIUM_VERIFICATION_CODE` are secrets; `SWIPIUM_TEST_EMAIL` is not. See [Secrets and redaction](concepts.md#secrets-and-redaction).
+
+Set `SWIPIUM_*` test data in the MCP server's `env` ([environment variables](../README.md#configuration--environment-variables)).
+
+## Starter templates
+
+`swipium init flows [--root <dir>] [--force]` writes starter flows under `.swipium/flows/` (launch smoke, login smoke, iOS WDA smoke, offline, permission prompt, deep link, saved-item persistence, and a visual map or canvas smoke) plus a `smoke` pack in `.swipium/packs/smoke.yaml`. Existing files are kept unless you pass `--force`. Edit the selectors and variables, then validate each flow with `qa_flow_check` before running it.
+
+## Compile and repair
+
+- **Record, then generate**: `qa_generate {target:"flow"}` turns a session's recorded actions into one flow; `qa_generate {target:"suite"}` writes a POM suite and compiles it into flows. Recorded secrets become `${SWIPIUM_*}` placeholders.
+- **Compile a suite on disk**: `qa_flow_compile {suite}` (or `swipium suite compile` in CI) resolves page-object refs to selectors, carries variables, writes `.swipium/flows/<slug>.yaml` plus a copy under `.swipium/compiled/`, and validates each flow. It needs no session, which makes it the path for committed or hand-edited suites.
+- **Repair a failed step**: when `qa_flow_run` fails on a locator, its `nextSteps` point at `qa_flow_repair {flow, failedStep}`. The repair proposes a stronger locator from the current screen, restricted to the failed target's role, and can patch the flow file (`apply:true`) at high or medium confidence. Details: [qa_flow_repair](tools.md#qa_flow_repair).
+
+## CI policy
+
+`qa_flow_check {ci:true}`, the flow CI preflight, and the report release gate (`qa_report` CI exports and `swipium report --fail-on-gate`) read an optional `.swipium/policy.json`:
+
+```json
+{
+  "ciAllowMutations": ["network", "seed", "restart"],
+  "blockOn": ["native_crash", "error_boundary", "anr"],
+  "warnOn": ["visual_diff", "missing_fixture"],
+  "ignoreKnown": ["REVENUECAT_BILLING_UNAVAILABLE_ON_EMULATOR"]
+}
+```
+
+### Mutations in CI
+
+`ciAllowMutations` lists the mutating steps a CI run may execute. Without a policy file, or with an empty list, every mutating step is flagged. Tokens are matched case-insensitively with punctuation ignored:
+
+| Step | Accepted tokens |
+| --- | --- |
+| `networkOffline`, `networkOnline` | the step name, `network`, `network_toggle`, `connectivity` |
+| `seed` | `seed`, `seeds`, `fixtures`, `fixture_seed` |
+| `restartApp` | `restart_app`, `restart`, `lifecycle`, `app_control` |
+| `openUrl` with a `${VAR}` | `open_url` |
+| any | `all`, `*`, `mutating_steps` |
+
+The CI variable preflight also reports every `${VAR}` that a CI run cannot resolve: names outside `SWIPIUM_*` always count as missing, because flows never read them from the environment.
+
+### Release gate
+
+`blockOn`, `warnOn`, and `ignoreKnown` decide which failures block a release. Their rules (including that, without a policy file or with an empty `blockOn`, every failure blocks and `warnOn` is ignored) are in [ci-reports.md: Release-gate policy](ci-reports.md#release-gate-policy). Tokens name failure codes such as `native_crash` or `error_boundary`.
+
+Codes are listed in the [failure-code catalog](tools.md#failure-codes). Export formats and CI recipes are in [ci-reports.md](ci-reports.md).

package/docs/mcp-server.md

@@ -1,137 +1,243 @@
-# MCP Server
+# MCP server reference
 
-Swipium runs as a local stdio MCP server. The MCP client starts the process and sends tool calls over stdin and stdout.
+Swipium is a local stdio MCP server. Your MCP client starts it as a child process and talks
+JSON-RPC over its stdin and stdout. Nothing listens on the network.
 
 ## Requirements
 
 - Node.js 20 or newer.
-- A mobile app repository as the MCP `cwd`.
-- Android Studio for Android Emulator workflows.
-- Xcode for iOS Simulator workflows.
+- Host OS: macOS for the iOS Simulator and Android; Linux for Android. Android on Windows is
+  experimental and untested.
+- Android: platform-tools (`adb`), the Android Emulator package, and at least one AVD, usually
+  installed through Android Studio. Build-tools (`aapt2`) are optional; Swipium uses them to read
+  an APK's package name and SDK level. See [How Android tools are found](#how-android-tools-are-found).
+- iOS: Xcode with an iOS Simulator runtime and at least one simulator. WebDriverAgent is needed for
+  the structured UI tree, taps, typing and swipes. Visual-only checks work through `simctl` without
+  it: `qa_visual` baselines and diffs, OCR `find_text`, and template `find_image`.
+
+### How Android tools are found
+
+Swipium looks for an Android SDK in `$ANDROID_HOME`, then `$ANDROID_SDK_ROOT`, then the default
+directory (`~/Library/Android/sdk` on macOS, `~/Android/Sdk` on Linux,
+`%LOCALAPPDATA%\Android\Sdk` on Windows).
+
+- **`adb`**: the copy on `PATH` is used when there is one. Otherwise Swipium appends the SDK's
+  `platform-tools` to its own `PATH` at startup. It never shadows your `adb`, because a different
+  adb version would kill the adb server you are running.
+- **`emulator`**: booting an AVD runs the SDK copy (`emulator/emulator`) first, and falls back to
+  `emulator` on `PATH` only when no SDK copy exists. Listing AVDs and the `qa_doctor` check follow
+  the `adb` rule (`PATH` first, then the SDK copy).
+- **`aapt2`**: taken from the newest version under the SDK's `build-tools`. There is no `PATH`
+  fallback.
+
+This matters for GUI-launched clients (Claude Desktop, Cursor started from the Dock), which don't
+inherit your shell `PATH`. If Swipium still can't find the tools, set `ANDROID_HOME` in the server
+`env`.
+
+## Server command
+
+`npx -y swipium` is the portable command. After `npm install -g swipium` you can run `swipium`
+instead. From a source checkout, run `npm run build` and use
+`node /absolute/path/to/swipium/dist/index.js`.
+
+| Invocation | Behavior |
+| --- | --- |
+| `swipium` or `swipium serve` | Runs the stdio MCP server. |
+| `swipium --stdio` (flags only, no subcommand) | Runs the server and warns on stderr that the flags were ignored. |
+| `swipium init`, `verify`, `scan`, `suite`, `report`, `gc` | CLI subcommands. See `swipium --help`. |
+| `swipium <unknown word>` | Prints usage and exits with status 2 instead of starting a server. |
+
+## Project root
+
+Every tool call works in one app repository. Swipium takes it from the `projectRoot` argument, then
+the client's MCP roots, then `SWIPIUM_PROJECT_ROOT`, then `CLAUDE_PROJECT_DIR`, then the server's
+working directory when that looks like an app. The full rules are in
+[concepts.md](concepts.md#project-root). For client setup, the practical rule is: if your client
+neither sends MCP roots nor lets you set a `cwd` (Claude Desktop, Windsurf), set
+`SWIPIUM_PROJECT_ROOT` in the server `env`.
+
+## Client setup
+
+`swipium init <client>` prints the exact registration and changes nothing. Add `--apply` to
+perform it. After a successful apply it runs `swipium verify`. Options: `--scope local|user|project`
+(default `local`) and `--cwd <app dir>` (default: the directory you run it from).
+
+| Client | `swipium init` does | Where it lands |
+| --- | --- | --- |
+| Claude Code | Runs `claude mcp add swipium [--scope …] -- <command>` | `local` / `user`: `~/.claude.json`; `project`: `.mcp.json` |
+| Codex | Appends a `[mcp_servers.swipium]` block with `cwd` and timeouts (refuses if `--cwd` doesn't exist; leaves an existing block alone) | `~/.codex/config.toml` |
+| Gemini CLI | Runs `gemini mcp add --scope project\|user swipium …`; prints a manual block if that fails | `.gemini/settings.json` (project, the default), `~/.gemini/settings.json` (`--scope user`) |
+| Cursor | Merges a `swipium` entry under `mcpServers` | `.cursor/mcp.json` (for all projects, add the same entry to `~/.cursor/mcp.json` yourself) |
+| VS Code | Merges a `swipium` entry under `servers`; prints a `code --add-mcp …` line for the user profile | `.vscode/mcp.json` |
+| Claude Desktop | Not supported by `init`; configure manually | `claude_desktop_config.json` |
+| Windsurf | Not supported by `init`; configure manually | `mcp_config.json` (Cascade > MCP settings) |
+
+Which command gets written:
+
+- **Team-shared files** get the portable `npx -y swipium`. That covers Claude `--scope project`,
+  Gemini project scope, `.cursor/mcp.json` and `.vscode/mcp.json`.
+- **Machine-local registrations** get this machine's `node` and the absolute path of the installed
+  `dist/index.js`. That covers Claude local and user scope, Gemini user scope, and Codex. The
+  exception is when Swipium itself runs from the npx cache; that path would disappear, so these
+  also get `npx -y swipium`.
+
+For Cursor and VS Code, `init` refuses to edit a file that isn't plain JSON (for example JSONC with
+comments), prints the entry to add by hand, and exits with status 2. An existing `swipium` entry
+is left unchanged.
+
+### Manual configuration
+
+Claude Code:
 
-## Server Command
+```bash
+claude mcp add swipium --scope project -- npx -y swipium
+```
+
+Codex (`~/.codex/config.toml`). Codex's defaults of 10 s to start and 60 s per tool call are too
+short for a first `npx` run and for builds and boots:
+
+```toml
+[mcp_servers.swipium]
+command = "npx"
+args = ["-y", "swipium"]
+cwd = "/absolute/path/to/your/mobile-app"
+startup_timeout_sec = 30
+tool_timeout_sec = 600
+```
+
+Known caveat: in the Codex Desktop app, custom stdio MCP tools can show up in `/mcp` without being
+available in threads ([openai/codex#19425](https://github.com/openai/codex/issues/19425)). If that
+happens, use the Codex CLI.
+
+Gemini CLI:
+
+```bash
+gemini mcp add --scope project swipium npx -- -y swipium
+```
+
+The `--` keeps Gemini from reading `-y` as its own flag. `init gemini` also suggests
+`"timeout": 600000` in the settings entry.
 
-No global install:
+Cursor (`.cursor/mcp.json`). For VS Code (`.vscode/mcp.json`), use the same entry under a top-level
+`"servers"` key instead of `"mcpServers"`. This is the entry `swipium init cursor` and
+`swipium init vscode` write:
 
-```jsonc
-{s
+```json
+{
   "mcpServers": {
     "swipium": {
+      "type": "stdio",
       "command": "npx",
       "args": ["-y", "swipium"],
-      "cwd": "/absolute/path/to/your/mobile-app",
-      "timeout": 600000
+      "env": { "SWIPIUM_PROJECT_ROOT": "${workspaceFolder}" }
     }
   }
 }
 ```
 
-Global install:
+Why the entry sets `SWIPIUM_PROJECT_ROOT` even though these editors can send MCP roots: roots come
+first in the resolution order, so when the editor sends them, Swipium uses them and ignores the
+variable. The variable is a fallback for an editor version or window that sends no roots. The editor
+replaces `${workspaceFolder}` with the open folder; if it is left unexpanded, the value is not an
+absolute path and Swipium skips it.
+
+Claude Desktop and Windsurf:
 
-```jsonc
+```json
 {
   "mcpServers": {
     "swipium": {
-      "command": "swipium",
-      "args": [],
-      "cwd": "/absolute/path/to/your/mobile-app",
-      "timeout": 600000
+      "command": "npx",
+      "args": ["-y", "swipium"],
+      "env": { "SWIPIUM_PROJECT_ROOT": "/absolute/path/to/your/mobile-app" }
     }
   }
 }
 ```
 
-## Claude Code
-
-```bash
-npm install -g swipium
-swipium init claude --apply --scope project
-```
-
-No global install:
-
-```bash
-claude mcp add swipium --scope project -- npx -y swipium
-```
-
-## Gemini CLI
-
-```bash
-npm install -g swipium
-swipium init gemini --apply
-```
-
-No global install:
-
-```bash
-gemini mcp add swipium npx -y swipium
-```
-
-## Codex
-
-```bash
-npm install -g swipium
-swipium init codex --apply
-```
-
-Manual config:
-
-```toml
-[mcp_servers.swipium]
-command = "npx"
-args = ["-y", "swipium"]
-cwd = "/absolute/path/to/your/mobile-app"
-```
+Environment variables (test credentials, OCR provider, remote WDA allowlist, elicitation policy,
+retention) are listed in the
+[README's configuration section](../README.md#configuration--environment-variables).
+
+## What the server exposes
+
+- **Tools**: listed in [tools.md](tools.md). Run `swipium verify` to see the exact list and count
+  your installed version serves. Every tool carries MCP annotations: read-only tools set
+  `readOnlyHint: true` and `openWorldHint: false`, and the others also set `destructiveHint` and
+  `idempotentHint`.
+- **Server instructions**: sent on `initialize`. They give the first call
+  (`qa_test_this { mode: "execute" }`), the polling loop (`qa_job_status … waitMs`), how to relay
+  `needs_input`, blockers and consent, and the project-root order. `qa_status` without a
+  `sessionId` returns the same orientation plus the tool groups.
+- **Prompts** (5): `swipium_setup_check`, `swipium_guardrail_validation`, `swipium_full_smoke`,
+  `swipium_bug_repro`, `swipium_convert_run_to_flow`.
+- **Resources**:
+  - `swipium://session/{sessionId}/{kind}/{name}`: session artifacts (screenshots, dumps, reports,
+    logs).
+  - `swipium://project/{projectId}/app-map`: the full app map.
+  - `swipium://project/{projectId}/app-map/{kind}/{id}`: one feature, screen or test-suite section.
+
+  `resources/list` shows only the current client's project roots (its MCP roots plus roots of
+  sessions in this server process), never lists sensitive-mode sessions, and is capped at 100
+  entries per template, with the cap stated on the last entry. Anything not listed can still be
+  read by URI. Clients without resource support use `qa_get_artifact` and `qa_app_map_read`.
+
+## Server behavior
+
+- **Response modes.** Pass `responseMode: "compact" | "normal" | "verbose"` on `qa_start_session`
+  or `qa_test_this`, and every later call in that session uses it. `compact` shortens only the
+  text channel to a summary plus URIs. `structuredContent` always carries the full payload.
+- **Artifacts.** Evidence is stored under `~/.swipium/runs/` and returned as `swipium://` URIs.
+  `qa_get_artifact` returns metadata for images by default. Pass `mode: "inline"` only when you
+  need the pixels.
+- **Unknown arguments are rejected.** A top-level argument a tool doesn't declare returns
+  `INVALID_ARGUMENT` with the accepted parameter list, and nothing runs. Swipium doesn't silently
+  drop it.
+- **Stale clients.** A call to a tool removed in 2.0 (`qa_agent_brief`, `qa_capabilities`,
+  `qa_next_best_action`, `qa_detect_context`, `qa_plan`, `qa_assert_visual`), or a legacy call
+  shape (`qa_ios` `wda_*` or `screenshot` actions, `qa_wait for:"job_done"`), returns
+  `STALE_CLIENT` with the replacement call and a hint to restart the client. `qa_doctor` accepts
+  `expectedVersion`, `expectedToolCount` and `expectedSchemaHash` and reports a mismatch.
+- **Consent.** Privileged actions (builds, boots, installs, data wipes and similar) return
+  `requiresConsent` with a `consentId` instead of running. On clients that support MCP elicitation,
+  Swipium asks the user directly. How consent works, and what each outcome returns, is in
+  [concepts.md](concepts.md#consent); the security reasoning is in
+  [THREAT_MODEL.md](../THREAT_MODEL.md).
+- **Startup and shutdown.** The version and tool count are logged to stderr at startup, and
+  processes left behind by a crashed earlier server are reaped in the background. On shutdown or
+  client disconnect, Swipium restores changed network state and stops screen recorders and Metro.
+  Managed WebDriverAgent keeps running so the next server can reuse it; `qa_wda stop` stops it.
+
+## Scope
+
+Swipium supports the Android Emulator and the iOS Simulator, with optional WebDriverAgent for
+structured iOS automation. Swipium never acts on a physical device. See
+[physical-devices.md](physical-devices.md).
 
 ## Verification
 
-Run:
-
 ```bash
 swipium verify
 ```
 
-Then, inside the MCP client, call:
-
-```text
-qa_doctor
-qa_capabilities
-```
-
-Use `qa_doctor` with `platform:"android"`, `platform:"ios"`, or `platform:"both"` when checking platform-specific readiness.
-
-Expected tool count: 95.
-
-If the client lists fewer tools, restart the MCP client. MCP clients often keep an old server process alive after package upgrades.
-
-## Artifacts
-
-Swipium stores evidence as local artifacts and returns `swipium://` URIs. Use:
-
-- `qa_get_artifact` to read an artifact by URI.
-- `qa_report` to generate report artifacts.
-- `qa_screenshot` to capture screenshot artifacts.
-- `qa_app_map_read` to read app-map sections.
-
-Images default to metadata through `qa_get_artifact`. Request inline mode only when pixels are needed.
-
-## Consent
-
-Swipium requests consent before high-impact local actions such as:
-
-- Booting a simulator when required by the plan.
-- Installing external app artifacts.
-- Writing generated automation into a project directory.
-- Running mutating flow steps.
-
-The consent result includes a `consentId`. Re-call the same tool with `approve: true` and that `consentId` to continue.
-
-## Simulator Scope
-
-Public scope supports:
-
-- Android Emulator.
-- iOS Simulator.
-- Optional WebDriverAgent for structured iOS simulator automation.
-
-The public build does not support real-device execution.
+This starts a Swipium server over stdio, checks that every tool and prompt this version declares is
+listed, prints their names, count and schema hash, and calls `qa_doctor`. It exits with status 1 if a tool is missing
+or `qa_doctor` errors. It starts the copy of Swipium you ran it with, not the command your client is
+configured with.
+
+Inside the client, call `qa_doctor`. It checks both platforms by default on macOS (ready if either
+one is) and Android elsewhere. Pass `platform: "android" | "ios" | "both"` to be explicit.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| The client lists fewer or different tools than `swipium verify`, or calls return `STALE_CLIENT` | The client is still running a server it started before the upgrade. Restart the client, or reload its MCP server list. |
+| `PROJECT_ROOT_UNRESOLVED` | Pass an absolute `projectRoot`, or set `SWIPIUM_PROJECT_ROOT` in the server `env` (needed on Claude Desktop and Windsurf). |
+| The server times out on first start (Codex, Gemini) | The first `npx` run downloads the package. Raise the startup timeout (Codex `startup_timeout_sec = 30`), or install globally and point the client at `swipium`. |
+| Long tool calls time out | Raise the client's tool timeout (Codex `tool_timeout_sec = 600`, Gemini `timeout: 600000`). For builds and runs, prefer `qa_test_this { mode: "execute" }` plus `qa_job_status` polling. |
+| `adb` or `emulator` not found from a GUI client | Set `ANDROID_HOME` in the server `env`, or install the SDK in its default location. See [How Android tools are found](#how-android-tools-are-found). |
+| `INVALID_ARGUMENT` listing accepted parameters | Remove the undeclared argument. If the tool list looks outdated, restart the client. |
+| Tools missing in Codex Desktop threads | Known Codex Desktop issue ([openai/codex#19425](https://github.com/openai/codex/issues/19425)). Use the Codex CLI. |
+| `swipium init cursor --apply` or `init vscode --apply` exits with status 2 | The existing file isn't plain JSON. Add the printed entry by hand. |
+| `PHYSICAL_DEVICE_UNSUPPORTED` | A phone was the only device, or was requested explicitly. Start an emulator or simulator. See [physical-devices.md](physical-devices.md). |

package/docs/physical-devices.md

@@ -0,0 +1,84 @@
+# Physical devices
+
+Status: **not supported in Swipium 2.0.** Swipium runs only on Android Emulators and iOS
+Simulators. A physical device is visible to Swipium, but Swipium never installs on it, launches on it
+or drives it. The policy is server-side; a client cannot opt in by passing a flag. This page
+describes the current behavior and what support would need.
+
+## The refusal rule
+
+A connected phone does not stop a run by itself:
+
+- **An emulator or simulator is viable** (one is online, or an AVD or simulator can be booted):
+  Swipium picks it, and the plan's `reason` mentions that the phone is visible but out of scope.
+- **The phone is the only option, or it is requested** (its serial passed as `device`, or
+  `preferRealDevice: true` while a phone is visible): the call fails with
+  `PHYSICAL_DEVICE_UNSUPPORTED` (bucket `unsafe_refused`), so the agent can explain *why* instead
+  of reporting a bare "no device". A viable emulator or simulator, if any, is offered as the
+  alternative.
+
+## Current behavior
+
+| Path | What happens with a physical device |
+| --- | --- |
+| `qa_resolve_target` | Lists it but never selects it. It follows the refusal rule above: an emulator is chosen when one is viable, and `PHYSICAL_DEVICE_UNSUPPORTED` is returned when the phone is the only candidate, is passed as `device`, or `preferRealDevice: true` is set while it is visible. |
+| `qa_test_this` | Follows the same rule, and also refuses `preferRealDevice: true` whether or not a phone is visible, and iOS artifacts that only install on real hardware (device-only `.ipa` or `.app` builds). |
+| `qa_prepare_target` | Refuses a physical serial passed as `device`, or a phone that is the only online device, before anything is installed or launched. With a phone and an emulator online and no `device`, it returns `MULTIPLE_DEVICES`. When it boots an emulator, it binds only a serial that was not online before the boot, so a phone that happens to be plugged in is never picked up. |
+| Device auto-attach (any tool that needs a device) | Only a single online device is bound automatically, and Swipium probes it first. A physical device is refused, a still-booting emulator returns `DEVICE_NOT_READY`, and a device whose properties cannot be read (offline or unauthorized) is not bound. |
+| iOS | Swipium enumerates simulators only, through `xcrun simctl`. Real iPhones and iPads are never listed or targeted. |
+
+## How Android emulators are recognized
+
+adb lists emulators and phones side by side, so Swipium classifies each online serial
+(`src/session/attach.ts`, `src/core/targetPlan.ts`):
+
+1. A serial of the form `emulator-<port>` is an emulator.
+2. Any other serial, for example `localhost:5555`, `127.0.0.1:<port>` or a Genymotion address, is
+   probed once with `adb -s <serial> shell getprop`. It is treated as an emulator when any of these
+   is true:
+   - `ro.kernel.qemu` or `ro.boot.qemu` is `1`;
+   - `ro.hardware` is `goldfish` or `ranchu`;
+   - `ro.genymotion.version` is set, or `ro.product.manufacturer` is `Genymotion`.
+3. Everything else whose properties could be read is physical and is refused.
+4. An emulator is used only once `sys.boot_completed` is `1`.
+
+`qa_test_this`, `qa_resolve_target`, `qa_prepare_target` and device auto-attach all use this
+property probe, so a network-attached emulator (`localhost:5555`, Genymotion) is accepted everywhere.
+
+## Why the line is drawn here
+
+A developer's emulator or simulator is a disposable sandbox. A physical device usually is not:
+
+1. **Real user data.** Personal accounts, photos, messages, payment methods and 2FA apps live on
+   real hardware. Data wipes, fresh installs, permission resets and exploratory tapping have real
+   consequences there.
+2. **Changes that can't be undone.** Screen size and density overrides, airplane-mode toggles,
+   location spoofing and animation-scale changes do no harm on an emulator you can recreate. On a
+   person's phone they leave it feeling broken if a run dies before restoring them.
+3. **Identity and signing.** Real iOS devices need Apple code signing and device trust. Running
+   WebDriverAgent on hardware brings account and provisioning questions that the simulator path
+   avoids.
+4. **Fleet variance.** OEM skins, battery optimizers and vendor permission dialogs multiply the
+   overlays and interstitials that Swipium's oracle currently models for AOSP-like emulators.
+
+## Roadmap: what support would require
+
+Physical-device support is not scheduled. It would keep the same tool surface, with an explicit
+opt-in on target resolution, and it would need at least:
+
+- **A threat-model extension** (per the out-of-scope clause in `THREAT_MODEL.md`): analysis of the
+  real-user-data adversary, stronger consent for every change to device state, and explicit
+  non-support for carrier, eSIM and payment surfaces.
+- **A mutation policy:** no screen size or density overrides; no location spoofing without consent
+  for each action; data wipes and uninstalls limited to the app under test, never system or
+  third-party packages; and a mandatory check at session end that everything was restored.
+- **A data-safety preflight:** refuse devices whose accounts or profiles suggest a personal phone
+  rather than a lab device, unless the user confirms it is a test device, with the heuristics
+  documented.
+- **An iOS decision:** "bring your own signed WebDriverAgent" versus full signing automation,
+  before promising parity with iOS Simulator support.
+- **Evidence hygiene:** screenshots and OCR on a personal device can capture other apps'
+  notifications, so sensitive mode would need stricter defaults on hardware.
+
+Remote device farms, multi-tenant device brokering, and anything that sends device data off the
+machine stay out of scope even then.