swipium 1.0.1 → 1.2.0

package/dist/version.js

@@ -1,11 +1,12 @@
-// Single source of truth for the Swipium version and the public v1 tool surface. Used by the
+// Single source of truth for the Swipium version and the public tool surface. Used by the
 // server identity, qa_doctor / qa_start_session, qa_capabilities, and `swipium verify`.
-export const SWIPIUM_VERSION = '1.0.1';
+export const SWIPIUM_VERSION = '1.2.0';
 export const TOOL_NAMES = [
     'qa_agent_brief',
     'qa_capabilities',
     'qa_test_this',
     'qa_job_status',
+    'qa_job_cancel',
     'qa_status',
     'qa_explain_blocker',
     'qa_continue_from_blocker',
@@ -18,6 +19,16 @@ export const TOOL_NAMES = [
     'qa_prepare_ios_target',
     'qa_ios',
     'qa_wda',
+    // Device / app environment parity (Phase 5)
+    'qa_device_info',
+    'qa_permissions',
+    'qa_orientation',
+    'qa_geolocation',
+    'qa_network',
+    'qa_metro',
+    'qa_app_control',
+    'qa_screen_info',
+    'qa_screen_record',
     'qa_snapshot',
     'qa_act',
     'qa_clear_overlay',
@@ -25,31 +36,71 @@ export const TOOL_NAMES = [
     'qa_screenshot',
     'qa_note',
     'qa_assert_visual',
+    // Visual intelligence (Phase 8, local-first OCR + coordinate audit)
+    'qa_visual',
+    'qa_visual_find_text',
+    // Agent-efficiency helpers (Phase 7)
+    'qa_locator_suggest',
+    'qa_wait',
+    'qa_idling_status',
+    'qa_input_capabilities',
     'qa_smoke',
     'qa_explore',
     'qa_report',
+    // Report 2.0: durable history and run comparison (Phase 10)
+    'qa_report_compare',
+    'qa_run_history',
+    // Seeded state (Phase 9)
+    'qa_seed',
+    'qa_state_prepare',
+    'qa_state_verify',
+    'qa_state_teardown',
     'qa_app_map_build',
     'qa_app_map_read',
     'qa_app_map_query',
     'qa_app_map_feature_scope',
     'qa_app_map_validate',
+    // Repeatable flow system (Phase 4)
     'qa_flow_check',
+    'qa_flow_plan',
     'qa_flow_run',
     'qa_flow_generate',
+    'qa_flow_repair',
+    // Persistent test suite + POM (REQ-06)
     'qa_suite_generate',
     'qa_suite_compile',
+    'qa_suite_lint',
+    'qa_pom_generate',
     'qa_testcase_generate',
+    'qa_test_suite_read',
+    'qa_test_suite_update',
+    'qa_test_suite_generate',
+    'qa_test_suite_export',
+    'qa_test_suite_lint',
     'qa_first_run_plan',
     'qa_first_run_continue',
     'qa_automation_plan',
     'qa_automation_generate',
     'qa_automation_validate',
+    // Maestro interop
+    'qa_maestro_import',
+    'qa_maestro_export',
+    // Durable issue memory + executable mobile audit (REQ-07/08)
+    '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',
 ];
 export const TOOL_COUNT = TOOL_NAMES.length;
 export const TOOL_NAME_SET = new Set(TOOL_NAMES);
 /** MCP prompts (reusable workflow templates) — PHASE3-PLAN §3.3. */
 export const PROMPT_NAMES = [
     'swipium_setup_check',
+    'swipium_guardrail_validation',
     'swipium_full_smoke',
     'swipium_bug_repro',
     'swipium_convert_run_to_flow',
@@ -57,6 +108,6 @@ export const PROMPT_NAMES = [
 export const PROMPT_COUNT = PROMPT_NAMES.length;
 /** Shown when a client may be running an older build than what's installed on disk. */
 export const STALE_CLIENT_HINT = `Swipium v${SWIPIUM_VERSION} exposes ${TOOL_COUNT} tools + ${PROMPT_COUNT} prompts. If your MCP client lists fewer ` +
-    `(e.g. qa_test_this / qa_plan / qa_flow_run / qa_ios missing), it is running a server ` +
+    `(e.g. qa_issue_log / qa_test_suite_read / qa_mobile_audit / qa_maestro_export / qa_flow_repair missing), it is running a server ` +
     `spawned before the upgrade. Restart the client to reload Swipium.`;
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,6FAA6F;AAC7F,wFAAwF;AAExF,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAEvC,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,gBAAgB;IAChB,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,WAAW;IACX,oBAAoB;IACpB,0BAA0B;IAC1B,iBAAiB;IACjB,WAAW;IACX,kBAAkB;IAClB,mBAAmB;IACnB,SAAS;IACT,mBAAmB;IACnB,uBAAuB;IACvB,QAAQ;IACR,QAAQ;IACR,aAAa;IACb,QAAQ;IACR,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,kBAAkB;IAClB,UAAU;IACV,YAAY;IACZ,WAAW;IACX,kBAAkB;IAClB,iBAAiB;IACjB,kBAAkB;IAClB,0BAA0B;IAC1B,qBAAqB;IACrB,eAAe;IACf,aAAa;IACb,kBAAkB;IAClB,mBAAmB;IACnB,kBAAkB;IAClB,sBAAsB;IACtB,mBAAmB;IACnB,uBAAuB;IACvB,oBAAoB;IACpB,wBAAwB;IACxB,wBAAwB;CAChB,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;AAEtE,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,qBAAqB;IACrB,oBAAoB;IACpB,mBAAmB;IACnB,6BAA6B;CACrB,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC;AAEhD,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAC5B,YAAY,eAAe,YAAY,UAAU,YAAY,YAAY,2CAA2C;IACpH,uFAAuF;IACvF,mEAAmE,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,wFAAwF;AAExF,MAAM,CAAC,MAAM,eAAe,GAAG,OAAO,CAAC;AAEvC,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,gBAAgB;IAChB,iBAAiB;IACjB,cAAc;IACd,eAAe;IACf,eAAe;IACf,WAAW;IACX,oBAAoB;IACpB,0BAA0B;IAC1B,iBAAiB;IACjB,WAAW;IACX,kBAAkB;IAClB,mBAAmB;IACnB,SAAS;IACT,mBAAmB;IACnB,uBAAuB;IACvB,QAAQ;IACR,QAAQ;IACR,4CAA4C;IAC5C,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,gBAAgB;IAChB,YAAY;IACZ,UAAU;IACV,gBAAgB;IAChB,gBAAgB;IAChB,kBAAkB;IAClB,aAAa;IACb,QAAQ;IACR,kBAAkB;IAClB,iBAAiB;IACjB,eAAe;IACf,SAAS;IACT,kBAAkB;IAClB,oEAAoE;IACpE,WAAW;IACX,qBAAqB;IACrB,qCAAqC;IACrC,oBAAoB;IACpB,SAAS;IACT,kBAAkB;IAClB,uBAAuB;IACvB,UAAU;IACV,YAAY;IACZ,WAAW;IACX,4DAA4D;IAC5D,mBAAmB;IACnB,gBAAgB;IAChB,yBAAyB;IACzB,SAAS;IACT,kBAAkB;IAClB,iBAAiB;IACjB,mBAAmB;IACnB,kBAAkB;IAClB,iBAAiB;IACjB,kBAAkB;IAClB,0BAA0B;IAC1B,qBAAqB;IACrB,mCAAmC;IACnC,eAAe;IACf,cAAc;IACd,aAAa;IACb,kBAAkB;IAClB,gBAAgB;IAChB,uCAAuC;IACvC,mBAAmB;IACnB,kBAAkB;IAClB,eAAe;IACf,iBAAiB;IACjB,sBAAsB;IACtB,oBAAoB;IACpB,sBAAsB;IACtB,wBAAwB;IACxB,sBAAsB;IACtB,oBAAoB;IACpB,mBAAmB;IACnB,uBAAuB;IACvB,oBAAoB;IACpB,wBAAwB;IACxB,wBAAwB;IACxB,kBAAkB;IAClB,mBAAmB;IACnB,mBAAmB;IACnB,6DAA6D;IAC7D,cAAc;IACd,kBAAkB;IAClB,qBAAqB;IACrB,iBAAiB;IACjB,mBAAmB;IACnB,uBAAuB;IACvB,kBAAkB;IAClB,iBAAiB;CACT,CAAC;AAEX,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAC;AAC5C,MAAM,CAAC,MAAM,aAAa,GAAwB,IAAI,GAAG,CAAC,UAAU,CAAC,CAAC;AAEtE,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,qBAAqB;IACrB,8BAA8B;IAC9B,oBAAoB;IACpB,mBAAmB;IACnB,6BAA6B;CACrB,CAAC;AAEX,MAAM,CAAC,MAAM,YAAY,GAAG,YAAY,CAAC,MAAM,CAAC;AAEhD,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAC5B,YAAY,eAAe,YAAY,UAAU,YAAY,YAAY,2CAA2C;IACpH,kIAAkI;IAClI,mEAAmE,CAAC"}

package/docs/README.md

@@ -1,19 +1,19 @@
 # Swipium Docs
 
-This directory contains public v1 documentation for the Swipium MCP server.
+This directory contains public documentation for the Swipium MCP server.
 
 ## Index
 
 - [MCP Server](mcp-server.md): server setup, client configuration, and agent integration.
-- [Tool Reference](tools.md): public v1 MCP tools grouped by workflow.
+- [Tool Reference](tools.md): public MCP tools grouped by workflow.
 
 ## Scope
 
-Swipium v1 is simulator-only:
+Swipium is simulator-only:
 
 - Android Emulator.
 - iOS Simulator.
 - Local MCP stdio server.
 - Local artifacts and app-map memory.
 
-Real devices, Jira integration, external ticket workflows, cloud execution, and certification are outside the public v1 scope.
+Real devices, Jira integration, external ticket workflows, cloud execution, and certification are outside the current public scope.

package/docs/mcp-server.md

@@ -100,7 +100,7 @@ qa_capabilities
 
 Use `qa_doctor` with `platform:"android"`, `platform:"ios"`, or `platform:"both"` when checking platform-specific readiness.
 
-Expected v1 tool count: 42.
+Expected tool count: 83.
 
 If the client lists fewer tools, restart the MCP client. MCP clients often keep an old server process alive after package upgrades.
 
@@ -128,10 +128,10 @@ The consent result includes a `consentId`. Re-call the same tool with `approve:
 
 ## Simulator Scope
 
-Public v1 supports:
+Public scope supports:
 
 - Android Emulator.
 - iOS Simulator.
 - Optional WebDriverAgent for structured iOS simulator automation.
 
-Public v1 does not support real-device execution.
+The public build does not support real-device execution.

package/docs/tools.md

@@ -1,6 +1,6 @@
 # Tool Reference
 
-Swipium v1 exposes 42 public MCP tools. The intended default entry point is `qa_test_this`.
+Swipium exposes 83 public MCP tools. The intended default entry point is `qa_test_this`.
 
 ## Start
 
@@ -9,13 +9,14 @@ Use these tools to orient the agent, start autopilot work, poll jobs, handle blo
 | Tool | What it does | Use when |
 | --- | --- | --- |
 | `qa_agent_brief` | Returns the recommended orchestration rules for agents. | The agent needs the correct first call, polling behavior, report behavior, or blocker handling rules. |
-| `qa_capabilities` | Lists the public v1 tool surface grouped by purpose. | The agent or user needs to discover available Swipium capabilities. |
+| `qa_capabilities` | Lists the public tool surface grouped by purpose. | The agent or user needs to discover available Swipium capabilities. |
 | `qa_test_this` | Autopilot for "test it": resolves the project, finds or builds an artifact, prepares a simulator, runs smoke or exploration, reports results, and can generate suite output. | The user gives a low-context request such as "test this app". |
 | `qa_job_status` | Polls a long-running job started by `qa_test_this` or prepare tools. | A tool returns a `jobId` with status `running`. |
 | `qa_status` | Returns compact session status and recommended next action. | The agent needs to recover context during a session. |
 | `qa_explain_blocker` | Explains a typed blocker, likely owner, and recovery path. | A run stops with a blocker and the user needs a concise explanation. |
 | `qa_continue_from_blocker` | Resumes after user input and registers secret values for redaction. | A blocker asks for credentials, OTP, target choice, or approval data. |
 | `qa_get_artifact` | Fetches artifact metadata or contents by `swipium://` URI. | A report, screenshot, dump, log, or generated file must be read. |
+| `qa_job_cancel` | Cancels a running job and aborts its spawned children. | A long-running job must be stopped early. |
 
 ## Setup
 
@@ -32,6 +33,22 @@ Use these tools to verify the local environment, create sessions, and prepare si
 | `qa_ios` | Runs iOS Simulator lifecycle operations such as boot, install, launch, screenshot, logs, privacy reset, and erase. | Direct iOS simulator control is needed. |
 | `qa_wda` | Checks, builds, or starts WebDriverAgent for structured iOS simulator automation. | iOS needs structured UI tree access instead of visual-only checks. |
 
+## Device
+
+Use these tools to inspect and control the device and app environment without raw `adb` or `simctl`. Mutating actions are consent-gated and recorded as environment changes; network changes are auto-restored at report end.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_device_info` | Reports model, SDK, ABIs, locale, screen, orientation, and installed apps (read-only). | The agent needs device context before testing. |
+| `qa_permissions` | Lists, grants, or revokes runtime permissions. Revoke is consent-gated. | A flow needs a known permission state. |
+| `qa_orientation` | Sets portrait, landscape, or auto orientation. | A screen must be tested in a specific orientation. |
+| `qa_geolocation` | Spoofs a GPS location on the emulator. Consent-gated. | Testing map or location-aware screens. |
+| `qa_network` | Reports, sets offline/online, or restores airplane-mode state. Consent-gated and auto-restored. | Testing offline behavior or network errors. |
+| `qa_metro` | Reports, starts, stops, or diagnoses the RN/Expo Metro bundler with RedBox detection. | A debug RN/Expo build needs Metro. |
+| `qa_app_control` | Runs launch, foreground, background, force_stop, restart, clear_data, or fresh_start. Destructive actions are guarded. | The app lifecycle must be controlled directly. |
+| `qa_screen_info` | Reports screen width, height, density, orientation, mode, and coordinate landmarks. | Coordinate-space context is needed for visual work. |
+| `qa_screen_record` | Records a screen video to an mp4 artifact (start/stop). Consent-gated with sensitive-screen warnings. | A run needs a video of the reproduction. |
+
 ## Drive
 
 Use these tools to observe the UI, act on it, collect evidence, and record results.
@@ -45,6 +62,23 @@ Use these tools to observe the UI, act on it, collect evidence, and record resul
 | `qa_screenshot` | Captures a screenshot artifact with coordinate-space metadata. | Visual evidence is required. |
 | `qa_note` | Records a structured QA outcome in the session. | The agent needs to log pass, fail, blocked, skipped, or finding details. |
 | `qa_assert_visual` | Captures a visual assertion with evidence. | The agent needs to document that a visual condition is true or false. |
+| `qa_visual` | Runs local visual operations: baseline capture, regression diff, image-target matching with tappable coordinates, and optional OCR. | A screen is visual-only or needs pixel-level regression checks. |
+| `qa_visual_find_text` | Locates on-screen text with OCR and returns structured regions with coordinate-space conversion. | A target has visible text but no structured selector. |
+| `qa_locator_suggest` | Scores each element's locator durability and grades automation readiness. | The agent needs to know which controls need testIDs before generating automation. |
+| `qa_input_capabilities` | Reports backend text-entry limits: ASCII, Unicode, clipboard, and WDA typing frequency. | Typing fails or behaves oddly and the agent needs the backend's input limits. |
+| `qa_wait` | Waits without a shell for `device_online`, `metro_ready`, or `job_done`. | The agent needs to block on a condition without raw `adb`/`sleep`. |
+| `qa_idling_status` | Reads app-declared idling hooks or label-heuristic settling before automation. | The agent needs to know the app has settled before acting. |
+
+## State
+
+Use these tools to create and verify reproducible preconditions instead of only reporting them as missing. All mutating seed and state actions are consent-gated and recorded.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_seed` | Creates a declared precondition via a fixture seed using a deeplink, script, or API hook. Consent-gated. | A workflow is blocked by missing test data. |
+| `qa_state_prepare` | Prepares a reproducible state profile: reset, launch, seed, and verify a ledger. | A test needs a known starting state. |
+| `qa_state_verify` | Verifies a state profile without treating setup drift as an app bug. | The precondition must be confirmed before testing. |
+| `qa_state_teardown` | Runs state-profile teardown and restores declared environment state. | A run must leave the environment clean. |
 
 ## Run
 
@@ -55,6 +89,8 @@ Use these tools to run broader QA workflows and produce reports.
 | `qa_smoke` | Runs launch smoke, baseline health, screenshot evidence, and saved flows. | The app is prepared and the agent needs a deterministic smoke pass. |
 | `qa_explore` | Performs bounded guided exploration, builds a screen graph, and records evidence. | The agent needs to discover reachable workflows or collect runtime app-map data. |
 | `qa_report` | Generates a session report with findings, blockers, evidence, mutations, workarounds, next actions, and separate app and coverage verdicts. | A run should be summarized or exported. |
+| `qa_report_compare` | Compares the current `report.json` against a baseline report. | A run should be checked for regression against a known-good report. |
+| `qa_run_history` | Summarizes local run history with pass rate, failures, flaky flows, and confidence calibration. | The user wants trends across runs, not a single report. |
 
 ## App Map
 
@@ -75,12 +111,52 @@ Use these tools to create, validate, run, and compile reusable test assets.
 | Tool | What it does | Use when |
 | --- | --- | --- |
 | `qa_flow_check` | Parses and statically validates a Swipium flow. | A flow file should be checked before execution. |
+| `qa_flow_plan` | Plans a flow against backend capabilities without executing it. | A flow should be checked for feasibility before a run. |
 | `qa_flow_run` | Executes a Swipium flow against a prepared simulator session. | A saved flow needs to run against the app. |
 | `qa_flow_generate` | Generates a flow from recorded actions. | A manual or exploratory run should become a reusable flow. |
+| `qa_flow_repair` | Suggests or patches a stronger locator for a failed flow step from the current screen. | A flow step fails on a brittle locator. |
 | `qa_suite_generate` | Generates a POM-style suite from recorded behavior. | The run should become a structured test suite. |
 | `qa_suite_compile` | Compiles a generated suite into runnable Swipium flows. | A generated suite needs executable flow output. |
+| `qa_suite_lint` | Lints generated page objects for brittle, coordinate-only, or dynamic locators. | A generated suite needs a durability check. |
+| `qa_pom_generate` | Generates page objects and a locator audit from recorded actions. | A run should produce reusable page objects. |
 | `qa_testcase_generate` | Generates test-case documentation from recorded behavior. | The run should produce human-readable test cases and steps. |
 
+## Persistent Test Suite
+
+Use these tools to grow and maintain a canonical test suite that persists across runs in `.swipium/test-suite.json`.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_test_suite_read` | Reads the canonical suite, filtered by functionality or status, as summary, json, or markdown. | The agent needs the durable suite without re-deriving it. |
+| `qa_test_suite_update` | Merges cases into the persistent suite, deduping by feature, objective, and steps. | A run produced cases to fold into the suite. |
+| `qa_test_suite_generate` | Generates or refreshes canonical cases from a recorded run and exploration. | The suite needs to be (re)built from observed behavior. |
+| `qa_test_suite_export` | Exports the persistent suite to markdown, a yaml directory, json, or junit. | The suite must be shared or fed to CI. |
+| `qa_test_suite_lint` | Validates the suite for missing expected/actual, stale map links, and duplicate ids. | The suite must be trusted before a release sign-off. |
+
+## Maestro Interop
+
+Use these tools to exchange flows with the Maestro ecosystem.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_maestro_import` | Imports supported Maestro YAML commands into a Swipium Flow V2. | An existing Maestro flow should run under Swipium. |
+| `qa_maestro_export` | Exports a Swipium Flow V2 to Maestro YAML with portability grades. | A Swipium flow should be shared as Maestro YAML. |
+
+## Issue Memory and Mobile Audit
+
+Use these tools for a durable, per-project issue ledger and executable mobile-QA audit profiles. The ledger lives in `.swipium/issues-log.jsonl`; fingerprints let later runs detect regressions of previously fixed issues.
+
+| Tool | What it does | Use when |
+| --- | --- | --- |
+| `qa_issue_log` | Lists the durable issue ledger with counts, recurrence candidates, and linked evidence. | The agent needs the project's known issues. |
+| `qa_issue_history` | Shows the append-only event trail for one issue. | An issue's lifecycle needs auditing. |
+| `qa_issue_mark_fixed` | Records a fix (date, commit, version, how-fixed) so future runs detect regressions. | A reported issue has been resolved. |
+| `qa_issue_triage` | Changes an issue's category, severity, or owner, or appends a note. | An issue needs reclassification. |
+| `qa_issue_suppress` | Suppresses known noise with a reason and expiration; it stays visible as known-noise. | A recurring non-bug should stop dominating reports. |
+| `qa_issue_verify_fixed` | Links passing test or audit evidence to a fixed issue. | A report should honestly claim an issue was verified this run. |
+| `qa_issue_metrics` | Summarizes issue trends: opened, fixed, reopened, verified, aging, and reopen rate. | The user wants issue quality trends. |
+| `qa_mobile_audit` | Plans or executes a named mobile-QA profile (smoke, account_cycle, store_compliance, resilience, release_gate). | A structured, repeatable audit is needed; execution records issues and evidence. |
+
 ## First Run
 
 Use these tools for login, account creation, onboarding, permissions, OTP, and paywall screens.
@@ -100,6 +176,39 @@ Use these tools to generate and validate automation code from Swipium evidence.
 | `qa_automation_generate` | Generates an Appium POM suite from recorded actions and validates it. | The run should produce automation code. |
 | `qa_automation_validate` | Validates generated automation code without a device. | Generated files need checks for secrets, durability, capabilities, syntax, and empty files. |
 
+## Detailed Reference: Device, Visual, State, and History Tools
+
+Technical detail for the tools added alongside the device-parity, visual-intelligence, seeded-state, and reporting phases. All take a `sessionId` from `qa_start_session` (except `qa_report_compare`, which is filesystem-only). Mutating actions accept `consentId` + `approve` and are recorded in the report's mutation ledger.
+
+### Device and app environment
+
+- **`qa_device_info`** — read-only Android introspection. *Inputs:* `listPackages?`, `packageFilter?`. *Outputs:* `props` (manufacturer, model, SDK, release, ABIs, locale, timezone), `screen` (`width`/`height`/`density`), `orientation`/`rotation`/`autoRotate`, `installedThirdPartyCount`, optional `packages[]`. No consent.
+- **`qa_orientation`** — set rotation. *Inputs:* `orientation: portrait | landscape | auto`. *Outputs:* resulting `orientation`/`rotation`/`autoRotate`. Non-destructive; logged as an environment change.
+- **`qa_geolocation`** — spoof GPS via `adb emu geo fix <lng> <lat>`. *Inputs:* `lat`, `lng` (decimal degrees). *Outputs:* `{ lat, lng, set }`. Consent-gated (medium). Emulator/`direct` backend only; iOS and real devices return `BACKEND_UNSUPPORTED`.
+- **`qa_permissions`** — runtime permission control. *Inputs:* `action: list | grant | revoke`, `package?` (default session `appId`), `permission?` (`android.permission.*`, required for grant/revoke). *Outputs:* `granted[]`/`denied[]` (list) or `{ package, permission, action }`. `list` is read-only; `grant` is consent-gated low (it can mask a permission-prompt bug); `revoke` is consent-gated medium (can break app state).
+- **`qa_network`** — offline/online via `cmd connectivity airplane-mode` (Android 11+). *Inputs:* `action: status | offline | online | restore`. *Outputs:* `network` (`online`/`offline`), `restoreAvailable`. `offline`/`online` consent-gated (medium); the original airplane state is recorded on first change and auto-restored at `qa_report`, on `restore`, and on server shutdown.
+- **`qa_metro`** — RN/Expo Metro lifecycle. *Inputs:* `action: status | diagnose | start | stop`. *Outputs:* `framework`, `metroListening`, `reverseSet`, `serving`, `ready`, `metroPid`, plus `redBox` + `recovery[]` (+ logcat artifact) for `diagnose`. `start` is consent-gated (low): it runs `adb reverse tcp:8081 tcp:8081` and spawns Metro (`npx expo start --dev-client` or `npx react-native start`) detached, logging to an artifact and tracking the PID; `stop` signals the whole process group.
+- **`qa_app_control`** — app lifecycle. *Inputs:* `action: launch | foreground | background | force_stop | restart | clear_data | fresh_start`, `acknowledgeBundleRisk?`. *Outputs:* `packageName`, `action`, `processKilled`, `foreground`, `foregroundIsApp`. `clear_data`/`fresh_start` are destructive → consent-gated (high); on debug RN/Expo builds they additionally require `acknowledgeBundleRisk:true` because a data wipe can remove the cached JS bundle.
+- **`qa_screen_info`** — coordinate-space metadata for visual-fallback work. *Outputs:* `screen` (`width`/`height`/`density`), `orientation`, session `mode`, `latestScreenshot`, named `landmarks` and `bands` (device pixels, origin top-left), `counters`, `budget`. Read-only.
+- **`qa_screen_record`** — screen video. *Inputs:* `action: start | status | stop`, `save?: always | on_failure`, `failed?`. *Outputs:* `recording`/`capturing`/`autoStopped`, `seconds`, and on stop a `uri` (mp4 artifact) + `bytes`. Consent-gated (medium); refused on sensitive sessions. Android uses `adb screenrecord --time-limit 180`; iOS uses `simctl io recordVideo`. One recording per session.
+
+### Visual intelligence (local-first)
+
+- **`qa_visual`** — deterministic visual ops + regression. *Inputs:* `action: baseline | diff | find_image | ocr`, `name?` (baseline/diff), `template?` (find_image PNG path), `threshold?` (diff, default 0.02), `minScore?` (find_image, default 0.85), `force?`. *Outputs:* always include `coordinateSpace` (screenshot↔device scale); `diff` adds `changedRatio`/`pass`/`changedBoxDevice`; `find_image` adds `devicePoint`. `baseline`/`diff`/`find_image` are local and need no consent; `ocr` is consent-gated and requires a configured `ocrCommand`. Withheld when a secure (password/OTP) field is on screen unless `force:true`.
+- **`qa_visual_find_text`** — OCR text locator. *Inputs:* `query`, `minConfidence?` (default 0.8). *Outputs:* `found`, matched `region` (text/confidence/bbox), `devicePoint`, `coordinateSpace`. Consent-gated (the screenshot is passed to the configured local OCR provider); requires `ocrCommand` returning JSON regions.
+
+### Seeded state
+
+- **`qa_seed`** — create a declared precondition. *Inputs:* `fixture` (must declare a `seed`: `deeplink | script | api`). *Outputs:* `{ fixture, type, seeded, warnings[] }`. Consent-gated; risk scales by type (`script` high, `api` medium, `deeplink` low). Git commands are refused (`GIT_SCOPE_FORBIDDEN`); a failed seed is reported as a SETUP failure (`missing_test_data`), never an app bug.
+- **`qa_state_prepare`** — apply a state profile as one transaction. *Inputs:* `profile` (`.swipium/state/<name>.yaml` or inline YAML). *Outputs:* a state `ledger` + `ledgerUri`. Consent-gated when it mutates (reset/launch/seed); refuses debug-bundle-loss resets unless acknowledged.
+- **`qa_state_verify`** — confirm a profile's declared checks (e.g. `assertVisible`). *Inputs:* `profile`. *Outputs:* verification `ledger`. Non-mutating; failures are setup/state blockers, not app-test failures.
+- **`qa_state_teardown`** — run profile teardown. *Inputs:* `profile`. *Outputs:* teardown `ledger`. Consent-gated when it mutates; restores declared state such as `networkOnline` and runs fixture cleanup hooks.
+
+### Report history
+
+- **`qa_report_compare`** — diff two reports. *Inputs:* `current`, `baseline` (paths to `report.json`), `trendRoot?`. *Outputs:* new/fixed failures, changed screenshots, outcome changes, runtime regression, optional flake status, and a `summary`. Filesystem-only — no session or device.
+- **`qa_run_history`** — local trend summary. *Inputs:* `sessionId?` or `projectRoot?`. *Outputs:* report count, per-flow `passRate`, median/average runtime, top failures, flaky flows, confidence calibration, and slowest steps. Reads `.swipium/runs/**/report.json` (and legacy `.swipium/ci/**`).
+
 ## Recommended Entry Points
 
 | User intent | First tool |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swipium",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "private": false,
   "description": "Swipium MCP server for simulator-based mobile QA workflows, evidence capture, app maps, and generated test suites.",
   "keywords": [
@@ -27,7 +27,8 @@
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "THREAT_MODEL.md"
   ],
   "engines": {
     "node": ">=20"