mobile-debug-mcp 0.34.0 → 0.36.0

package/docs/tools/interact.md

@@ -1,23 +1,23 @@
-# Interact (UI actions, waits, and verification)
+# Interaction
 
-This document covers deterministic UI resolution, actions, waits, and outcome verification.
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
 
-## Verification pattern
+Use these tools to select UI targets, perform actions, wait for transitions, and
+verify the resulting state. See [interaction principles](TOOLS.md#interaction-principles)
+for the distinction between execution, synchronization, and verification.
 
-For mutation actions, the intended agent loop is:
+## On this page
 
-**RESOLVE -> ACT -> WAIT (if needed) -> EXPECT**
+- Find a target: [find_element](#find_element), [wait_for_ui](#wait_for_ui).
+- Act on it: [basic input](#tap--swipe--type_text--press_back), [tap_element](#tap_element), [scroll_to_element](#scroll_to_element), [adjust_control](#adjust_control).
+- Wait for change: [screen changes](#wait_for_screen_change), [UI changes](#wait_for_ui_change), [readiness-aware waits](#readiness-aware-waits).
+- Verify the outcome: [screen](#expect_screen), [visible element](#expect_element_visible), [control state](#expect_state).
+- Control execution: [conditional actions](#conditional-actions), [verification modes and journeys](#interaction-execution-controls-rfc-018).
+- Investigate failures: [outcome classification and network activity](#classify_action_outcome--get_network_activity), [evidence correlation](correlated-evidence.md).
 
-Role split:
-
-- `wait_for_*` = resolution and synchronization
-- `expect_*` = final outcome verification
-
-Important:
-
-- `wait_for_*` tools must not be used as the final verification of action success when an applicable `expect_*` tool exists.
-- action tools report execution success, not outcome correctness.
-- `classify_action_outcome` should receive the runtime `action_type` when you want routing to distinguish local-state and side-effect actions.
+When classifying a result, pass the runtime `action_type` to
+`classify_action_outcome` so local-state changes and backend side effects can be
+distinguished.
 
 ## Conditional actions
 
@@ -125,7 +125,7 @@ Example response:
   "target": { "selector": { "x": 100, "y": 200 }, "resolved": null },
   "success": true,
   "trace": {
-    "action_id": "tap_element_1710000000002_3",
+    "action_id": "tap_1710000000000_1",
     "steps": [
       {
         "stage": "resolve",
@@ -292,6 +292,8 @@ Notes:
 - initial support is for slider-like controls that expose `value_range` or readable numeric value state
 - `expect_state` is the verification surface used to read back the resulting value
 - direct target placement is preferred; drag fallback is treated as degraded mode
+- `maxAttempts` defaults to 5; omitted tolerance is 0 for discrete controls, or
+  the larger of half a step and 1% of the range for continuous controls
 - the tool returns `target_state`, `actual_state`, `within_tolerance`, `converged`, `attempts`, and `adjustment_mode`
 
 Input example:
@@ -458,7 +460,10 @@ Notes:
 
 ## tap_element
 
-Tap a previously resolved UI element using its `elementId`.
+Tap a previously resolved `elementId`, or provide a `selector` to resolve and tap
+in one call. Supply exactly one of these targets. Selector calls can use
+`waitFor`; handle-based calls cannot. See [execution controls](#interaction-execution-controls-rfc-018)
+for lookup budgets and selector options.
 
 Input:
 
@@ -734,8 +739,25 @@ the journey; remaining steps report `not_run`. Journey responses default to comp
 `defaults` supplies execution controls; step verification overrides the default.
 `captureOnFailure: true` includes a screenshot-free failure snapshot in debug mode.
 
-See [RFC 018](../specs/018-interaction-latency-and-batched-journeys/spec.md) for
-contracts and the device acceptance criteria.
+Example `run_journey` request:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "steps": [
+    { "id": "open-settings", "type": "tap", "selector": { "text": "Settings" } },
+    { "id": "verify-account", "type": "assert", "timeoutMs": 15000,
+      "assertion": { "kind": "element_visible", "selector": { "text": "Account" } } }
+  ]
+}
+```
+
+Replace the labels with elements from your own UI. Journey timeouts use camelCase
+(`timeoutMs`, `pollIntervalMs`), unlike standalone UI wait/assertion fields
+(`timeout_ms`, `poll_interval_ms`). See
+[RFC 018](../specs/018-interaction-latency-and-batched-journeys/spec.md) for design
+history and device acceptance criteria.
 
 ## Readiness-aware waits
 
@@ -768,4 +790,4 @@ for supported states and limits.
 ## Correlated evidence
 
 Actions and journeys expose identifiers and phase timestamps for linking later
-observations. See [correlated evidence](evidence.md) for scope and limitations.
+observations. See [evidence correlation](correlated-evidence.md) for scope and limitations.

package/docs/tools/manage.md

@@ -1,16 +1,21 @@
-# Manage (build & device management)
+# App management
 
-This document covers tools that perform project builds, device selection, installation, and app lifecycle operations.
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
 
-For app launch and restart flows, agents should use:
+Use these tools to select a device, build and install an app, and control its
+lifecycle.
 
-**ACT -> WAIT (if needed) -> EXPECT**
+After `start_app` or `restart_app`, [inspect the resulting UI](observe.md) and
+[assert the expected screen or element](interact.md#expect_screen). If the app
+is still loading, use a [readiness check](observe.md#app-readiness) or an
+appropriate [UI wait](interact.md#wait_for_ui) before continuing.
 
-For example:
+## On this page
 
-1. `start_app` or `restart_app`
-2. optional `wait_for_screen_change`
-3. `expect_screen` when the expected landing screen is known
+- [List devices](#list_devices).
+- [Build an app](#build_app).
+- [Install an existing artifact](#install_app).
+- [Launch, stop, restart, or reset an app](#start_app--terminate_app--restart_app--reset_app_data).
 
 ## list_devices
 Enumerate connected Android devices and iOS simulators.
@@ -51,50 +56,21 @@ Notes:
 - Requires `platform`, `projectType`, and `projectPath`.
 - Android builds prefer the project `gradlew` when present.
 - iOS builds honor environment-based Xcode destination and derived-data settings where configured.
-- Android setup typically needs `ADB_PATH` or `ANDROID_SDK_ROOT`/`ANDROID_HOME`, plus `GRADLE_JAVA_HOME` or `JAVA_HOME` for Gradle-backed builds.
+- Standard toolchains are discovered automatically. Use [path overrides](../../README.md#environment-setup) when discovery needs help. Gradle-backed builds require a suitable Java installation.
 - iOS setup typically needs `XCRUN_PATH` and `MCP_IDB_PATH` or `IDB_PATH` when `idb` is not on `PATH`.
 
 ---
 
-## build_and_install (buildAndInstallHandler)
-Orchestrates build then install and returns streamed NDJSON events plus a final result object.
-
-This is a documented repository helper, not part of the main public MCP tool list in `toolDefinitions`.
-
-Input:
-
-```json
-{ "projectPath": "/path/to/project", "platform": "android", "deviceId": "emulator-5554", "projectType": "kmp" }
-```
-
-NDJSON events (example stream):
-
-```json
-{"type":"build","status":"started","platform":"android"}
-{"type":"build","status":"finished","artifactPath":"/path/to/app.apk"}
-{"type":"install","status":"started","artifactPath":"/path/to/app.apk","deviceId":"emulator-5554"}
-{"type":"install","status":"finished","artifactPath":"/path/to/app.apk","device":{"platform":"android","id":"emulator-5554"}}
-```
-
-Final result:
-
-```json
-{ "success": true, "artifactPath": "/path/to/app.apk", "device": { "platform": "android", "id": "emulator-5554" }, "output": "Performing Streamed Install\nSuccess" }
-```
-
-Notes:
-- If `projectType` === `kmp`, the handler prefers Android by default. Set `platform` explicitly to override.
-- If `MCP_DISABLE_AUTODETECT=1`, callers MUST provide `platform` or `projectType`.
-
----
-
 ## install_app
-Install an app onto a connected device or simulator.
+Install a built artifact, or build and install from a project directory.
+`platform`, `projectType`, and `appPath` are required. `projectType` is one of
+`native`, `kmp`, `react-native`, or `flutter`; acceptance of a project type does
+not establish tested support for every framework.
 
 Input:
 
 ```json
-{ "platform": "android", "appPath": "/path/to/app.apk", "deviceId": "emulator-5554" }
+{ "platform": "android", "projectType": "native", "appPath": "/path/to/app.apk", "deviceId": "emulator-5554" }
 ```
 
 Response:
@@ -155,4 +131,9 @@ Notes:
 - Use `details.observed_app` as the quick decision signal for what the tool actually saw after launch.
 - Android launch feedback usually includes package/activity matching; iOS launch feedback includes launch output and PID when available.
 - When the landing screen is known, use `expect_screen` as the final verification step.
-- If launch timing is uncertain, insert `wait_for_screen_change` before `expect_screen`.
+- If launch timing is uncertain, use a UI wait or readiness check before the final assertion.
+
+`terminate_app`, `restart_app`, and `reset_app_data` also require `platform` and
+`appId`, with optional `deviceId`. Resetting app data removes application state;
+use it only when a clean app state is intended. Execution controls apply to
+`start_app` and `restart_app`; see [verification modes](interact.md#interaction-execution-controls-rfc-018).

package/docs/tools/observe.md

@@ -1,31 +1,33 @@
-# Observe (logs, screenshots, UI trees)
+# Observation
 
-Tools that retrieve device state, logs, screenshots, fingerprints, and UI hierarchies.
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
 
-These tools are primarily for:
+Use observations to understand the current UI and investigate unexpected behaviour.
+Screenshots show layout; UI trees expose labels, identifiers, and control state.
+Logs and debug snapshots provide context when the UI does not explain a failure.
+Use [interaction assertions](interact.md#expect_element_visible) to establish an
+expected outcome.
 
-- building context before an action
-- supporting synchronization
-- diagnostics when verification fails
+## On this page
 
-They are **not** the primary success signal when an applicable `expect_*` tool exists.
+- Inspect the UI: [screenshot](#capture_screenshot), [UI tree](#get_ui_tree), [current screen](#get_current_screen), [fingerprint](#get_screen_fingerprint).
+- Investigate a failure: [logs](#get_logs), [debug snapshot](#capture_debug_snapshot), [log streams](#start_log_stream--read_log_stream--stop_log_stream).
+- Check whether the UI has settled: [app readiness](#app-readiness).
 
-Covered observations support optional `actionRef` and return acquisition/freshness
-metadata; see [correlated evidence](evidence.md).
-
-Android performance investigations can use [system traces](system-traces.md)
-to bracket a journey and retrieve a local Perfetto artifact.
+To connect an observation to a specific action, use [evidence
+correlation](correlated-evidence.md). For Android performance questions, collect a
+[system trace](system-traces.md) around the interaction.
 
 ## get_logs
 
-Fetch recent logs as structured entries optimized for AI agents.
+Fetch recent logs as structured entries for diagnosis.
 
 Use logs as a debugging aid only. Prefer `expect_*` for verification, and use logs after verification fails or when an error is suspected.
 
 Input (example):
 
 ```json
-{ "platform": "android|ios", "appId": "com.example.app", "deviceId": "emulator-5554", "pid": 1234, "tag": "MyTag", "level": "ERROR", "contains": "timeout", "since_seconds": 60, "limit": 50 }
+{ "platform": "android", "appId": "com.example.app", "deviceId": "emulator-5554", "pid": 1234, "tag": "MyTag", "level": "ERROR", "contains": "timeout", "since_seconds": 60, "limit": 50 }
 ```
 
 Defaults:
@@ -86,10 +88,10 @@ Input:
 { "platform": "android", "deviceId": "emulator-5554" }
 ```
 
-Response (example):
+Response (selected fields):
 
 ```json
-{ "device": { "platform": "android", "id": "emulator-5554" }, "screen": "", "resolution": { "width": 1080, "height": 2400 }, "snapshot_revision": 12, "captured_at_ms": 1710000000123, "loading_state": { "active": true, "signal": "spinner", "source": "ui_tree" }, "elements": [ { "text": "Sign in", "type": "android.widget.Button", "resourceId": "com.example:id/signin", "clickable": true, "bounds": [0,0,100,50], "state": { "enabled": true }, "stable_id": "com.example:id/signin", "role": "button", "test_tag": "com.example:id/signin", "selector": { "value": "com.example:id/signin", "confidence": { "score": 1, "reason": "resource_id" } }, "semantic": { "is_clickable": true, "is_container": false } } ] }
+{ "device": { "platform": "android", "id": "emulator-5554" }, "screen": "", "resolution": { "width": 1080, "height": 2400 }, "snapshot_session_id": "example-server-session", "snapshot_revision": 12, "captured_at_ms": 1710000000123, "loading_state": { "active": true, "signal": "spinner", "source": "ui_tree" }, "elements": [ { "text": "Sign in", "type": "android.widget.Button", "resourceId": "com.example:id/signin", "clickable": true, "bounds": [0,0,100,50], "state": { "enabled": true }, "stable_id": "com.example:id/signin", "role": "button", "test_tag": "com.example:id/signin", "selector": { "value": "com.example:id/signin", "confidence": { "score": 1, "reason": "resource_id" } }, "semantic": { "is_clickable": true, "is_container": false } } ] }
 ```
 
 Notes:
@@ -133,8 +135,9 @@ Input:
 {
   "reason": "optional string describing why snapshot is taken",
   "includeLogs": true,
+  "includeScreenshot": true,
   "logLines": 200,
-  "platform": "android | ios",
+  "platform": "android",
   "appId": "optional package/bundle id to scope logs",
   "deviceId": "optional device serial/udid",
   "sessionId": "optional log stream session id to prefer"
@@ -152,17 +155,17 @@ Behavior:
 - `semantic` is optional, derived from `raw`, and intended for planning only.
 - `raw` now includes `snapshot_revision`, `captured_at_ms`, and `loading_state` when detectable.
 
-Response (example):
+Response (selected fields):
 
 ```json
 {
   "raw": {
-    "timestamp": 1710000000,
+    "timestamp": 1710000000000,
     "reason": "Crash after tapping checkout",
     "activity": "CheckoutActivity",
     "fingerprint": "abc123",
     "screenshot": "<base64 PNG string>",
-    "ui_tree": { ... },
+    "ui_tree": { "elements": [] },
     "logs": [ { "timestamp": "2024-03-09T12:00:00.000Z", "level": "ERROR", "tag": "CheckoutViewModel", "pid": 1234, "message": "NullPointerException at CheckoutViewModel" } ]
   },
   "semantic": {
@@ -214,12 +217,41 @@ Guidance:
 ---
 
 ## start_log_stream / read_log_stream / stop_log_stream
-Start a background adb logcat stream and retrieve parsed NDJSON entries.
+Start an app-scoped background stream on Android (`adb logcat`) or an iOS
+simulator (`xcrun simctl ... log stream`). Start with `start_log_stream`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "packageName": "com.example.app",
+  "sessionId": "app-diagnostics",
+  "level": "error"
+}
+```
+
+`packageName` is required and is also used for an iOS bundle ID. `platform`
+defaults to Android. Android accepts `level`: `error` (default), `warn`, `info`,
+or `debug`. The iOS adapter does not use that level argument. Omitted session IDs
+use `default`; supply an explicit ID to keep diagnostic streams distinct.
+
+Pass the same session ID to `read_log_stream` and, when finished,
+`stop_log_stream`:
+
+```json
+{ "sessionId": "app-diagnostics" }
+```
+
+Use distinct session IDs across platforms: when an ID exists only on iOS, read
+and stop select iOS; otherwise they select Android. Reads retain the stream's device scope.
+`read_log_stream` also accepts the optional [action reference](correlated-evidence.md)
+for evidence correlation. A read returns accumulated entries and any available
+crash summary; reading does not itself stop the background stream.
 
-read_log_stream response example:
+Example read response (selected fields):
 
 ```json
-{ "entries": [ { "timestamp": "2026-03-20T...Z", "level": "ERROR", "tag": "AppTag", "pid": 1234, "message": "FATAL EXCEPTION" } ], "crash_summary": { "crash_detected": true } }
+{ "entries": [ { "timestamp": "2026-03-20T12:00:00Z", "level": "ERROR", "tag": "AppTag", "pid": 1234, "message": "FATAL EXCEPTION" } ], "crash_summary": { "crash_detected": true } }
 ```
 
 ## App readiness

package/docs/tools/system-traces.md

@@ -1,7 +1,10 @@
-# Android system traces
+# System traces for Android and iOS
+
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
 
 Use system traces to collect scheduling and system annotations around a slow
-interaction. Capture is optional, device-wide and Android-only; it does not
+interaction. Capture is optional; Android uses device-wide Perfetto and iOS simulators use
+app-attached Instruments Time Profiler. It does not
 automatically diagnose performance problems. No root or Android CLI installation
 is required. The device must provide Perfetto (Android API 29+), authorised ADB,
 tracing services, required sched/input categories, readable process identity,
@@ -9,14 +12,14 @@ base64 decoding and writable `/data/misc/perfetto-traces` storage.
 
 ## Tools
 
-All inputs reject unknown fields. `platform` is `android` or `ios`; iOS is
-unsupported and never starts capture. Optional `deviceId` uses existing device
-resolution; supplying one is recommended when multiple devices are connected.
+All inputs reject unknown fields. `platform` is `android` or `ios`. Android's
+optional `deviceId` uses existing device resolution. iOS requires an explicit
+booted simulator UDID, plus `appId` for start; it never records the Mac host.
 
 | Tool | Arguments | Result |
 | --- | --- | --- |
-| `get_system_trace_capabilities` | `platform`, `deviceId?` | `supported`, `backend`, resolved `device`, prerequisite booleans, reasons, enabled sources, unavailable categories, limitations. No recording. |
-| `start_system_trace` | `platform`, `deviceId?`, `durationMs?` | Owned recording session after data-source acknowledgement. Duration is an integer 1,000–120,000 ms, default 30,000. |
+| `get_system_trace_capabilities` | `platform`, `deviceId?`, `appId?`, `template?` | Common: `supported`, `backend`, resolved `device`, reasons and limitations. Android: prerequisite booleans, `enabled_sources`, `unavailable_categories`. iOS: prerequisites as `available`/`missing`/`unknown`, `discovered_templates`, `templates`, `app`, `xcode_version`, `recovery`. No recording. |
+| `start_system_trace` | `platform`, `deviceId?`, `durationMs?`, `appId?`, `template?` | Owned recording session after native readiness acknowledgement. Duration is an integer 1,000–120,000 ms, default 30,000. |
 | `get_system_trace_status` | `traceId` | Reconcile process/deadline and finalise ended recording. |
 | `stop_system_trace` | `traceId` | Gracefully stop and retrieve local artifact; retry transfer/cleanup after failure. |
 | `cancel_system_trace` | `traceId` | Stop and discard partial files. Already retrieved artifacts remain local. |
@@ -24,10 +27,10 @@ resolution; supplying one is recommended when multiple devices are connected.
 Trace control IDs are UUIDs and cannot redirect to another device. One capture
 per device and four pending sessions per server are allowed. Pending failed
 cleanup reserves its slot until resolved. Terminal records with complete cleanup
-expire after 10 minutes or eviction beyond 100 records. Server restart invalidates
+expire after 10 minutes or eviction beyond 100 records per backend (the router retains at most 100 completed IDs). Server restart invalidates
 IDs. Repeated terminal operations return the stored outcome.
 
-## Agent workflow and interpretation
+## Capture workflow
 
 Trace a reproducible slow or stalled interaction when existing UI timing/state
 and logs leave a performance question unresolved. Check tool discovery first:
@@ -87,12 +90,13 @@ proof of causality; host intervals are not aligned with device trace clocks.
 ## Session response and failures
 
 JSON responses contain `trace_id`, process-scoped `session_id`, `device`,
-`backend:"perfetto"`, `state` (starting/recording/stopping/completed/cancelled/failed),
+`backend:"perfetto"` (Android) or `"xctrace"` (iOS), `state` (starting/recording/stopping/completed/cancelled/failed),
 nullable `reason` and `completion_reason`, host UTC capture bounds, nullable
-`artifact`, `cleanup`, `correlation_ids`, `enabled_sources`, and
-`unavailable_categories`. Capture bounds include command/acknowledgement latency.
+`artifact`, `cleanup`, and `correlation_ids`. Android additionally returns
+`enabled_sources` and `unavailable_categories`. Capture bounds include command/acknowledgement latency.
 
-`artifact` contains absolute `path`, `format:"perfetto"` and `size_bytes`.
+Android `artifact` contains absolute `path`, `format:"perfetto"` and `size_bytes`;
+see the iOS section below for Instruments artifact and session fields.
 `cleanup` contains `status` (pending/complete/failed) and `remaining_resources`.
 Errors preserve known session metadata and set MCP `isError`. Argument/unknown-ID
 errors return `{error:{tool,code,message}}` without a session. Codes include
@@ -103,7 +107,7 @@ Capability failures return ordinary `supported:false` responses with reasons.
 Read state/cleanup independently: a successful artifact transfer can still have
 failed device-file cleanup. Retry stop/status, or cancel to discard failed output.
 
-## Limits and privacy
+## Android limits and privacy
 
 The fixed preset requests sched, freq, idle, am, wm, gfx, view and input categories,
 a 16 MiB ring buffer and a 32 MiB maximum output. Missing optional categories are
@@ -124,3 +128,74 @@ shutdown attempts owned cleanup for up to 10 seconds. A server crash can leave
 a uniquely named bounded device file for manual removal; restart performs no
 broad cleanup sweep. Device suspend can extend Perfetto's own monotonic duration
 limit; the server timer bounds wall-clock lifetime while the server is running.
+
+## iOS simulator Instruments capture
+
+Requires macOS, full Xcode with Instruments and clang, a booted simulator visible
+in both `simctl` and `xctrace list devices`, and an already running development
+app. Journey input also needs a compatible idb companion; capability discovery
+for capture does not establish HID input support. The initial verified target is iPhone 17 Pro simulator / iOS 26.4.1 with
+Xcode 27.2. Physical-device capture is unsupported and unrun. Tool installation,
+OS profiling permissions and pairing/security changes are user actions.
+
+```json
+{"platform":"ios","deviceId":"<simulator-UDID>","appId":"<bundle-id>","template":"Time Profiler","durationMs":60000}
+```
+
+Use this target with capabilities and start, then bracket a `run_journey` on the
+same simulator using the returned `systemTraceId`, and stop/cancel as above.
+Omitting `template` defaults to Time Profiler. `appId` and `template` are rejected
+on Android. Capabilities do not start capture; permissions and symbols remain
+`unknown` until separately established. Installed templates are listed separately
+from support: System Trace scheduling coverage is unverified, Animation Hitches
+reported unsupported on the tested simulator, and Hangs is bundled within Time
+Profiler rather than a selectable standalone template. No silent substitution.
+
+The server resolves the bundle to an exact current executable/PID, pins the UDID,
+and waits for a uniquely named Darwin recording-start notification before
+returning `recording`. It compiles a small private listener with Xcode clang in
+the owned temporary directory. A failed/uncertain start cleans up and returns a
+failure, not an automatic retry. Errors such as `APP_NOT_RUNNING`,
+`PROFILING_PERMISSION_REQUIRED`, `READINESS_TIMEOUT` and `TARGET_DISCONNECTED`
+include bounded recovery guidance; raw recorder output is not returned.
+
+Only the session-owned recorder is signalled; cleanup never terminates the app.
+iOS readiness has a 35-second budget, stop/finalisation 30 seconds and artifact
+validation 30 seconds. Recording is bounded by native duration and server
+monitoring. Monitoring retains the pinned app identity and tolerates two consecutive
+non-definitive command failures, resetting after a successful poll. The third
+fails capture with its bounded reason (`COMMAND_FAILED`, `ACTION_TIMEOUT`, or
+`TRACE_MONITOR_FAILED` for an unclassified failure). Storage limits, changed app
+identity and a missing running app fail immediately. Expiry and recorder exit
+are still checked after a tolerated poll failure. Shutdown attempts cancellation under an overall ten-second budget.
+Failed export can be retried using stop/status without starting another recording;
+cancel removes owned partial files. Completed artifacts remain for user deletion.
+
+The `.trace` result may be a bundle/directory. `artifact` adds
+`format:"instruments"`, `kind`, recursive `size_bytes`, and
+`validation:{readable,schema,sample_rows}`. Validation checks a readable TOC,
+matching target UUID/PID/template, `time-sample` schema and exported sample data.
+Zero rows mean no CPU sample evidence. Warnings are preserved as bounded
+classifications. This establishes readable capture, not successful symbolication,
+working hang detection or root-cause diagnosis. Do not treat a saved failed trace
+as a successful recording.
+
+Results also include `app_id`, `pid`, `executable`, `template`,
+`recording_ready_at_ms`, `warnings` and `clock_alignment:"unknown"`. The profiled
+app stays pinned even if the journey navigates elsewhere; linked IDs do not prove
+that other apps are captured. Start/stop during a linked journey reports partial
+coverage. Host capture bounds include startup/finalisation uncertainty.
+
+At least 1 GiB free output space is required before recording. The server checks
+a 256 MiB recursive size threshold each second; this is a soft limit and can be
+overshot during polling/finalisation. Oversized output fails and is discarded.
+Final bundles reject symlinks and use restricted file/directory permissions.
+Even app-attached capture may include sensitive system metadata, paths, symbols,
+logs and signposts. Keep artifacts local and delete them when finished; no upload,
+base64 response, permission bypass or restart-wide cleanup sweep occurs.
+
+## Related guides
+
+- [Interaction](interact.md#interaction-execution-controls-rfc-018): run the journey being measured.
+- [Evidence correlation](correlated-evidence.md): interpret action and observation timing.
+- [Runtime debugger](debugger.md): inspect paused application state.

package/docs/tools/system.md

@@ -1,6 +1,11 @@
-# System (environment & health checks)
+# Environment diagnostics
 
-Tools that provide a lightweight view of the local mobile debugging environment and surface issues early so agents can decide whether to proceed.
+[Documentation](../README.md) · [Tool reference](TOOLS.md)
+
+Check local toolchains and connected devices before building, installing, or
+interacting with an app. If discovery cannot find a tool, configure the relevant
+[path override](../../README.md#environment-setup), then check again. Once the
+required platform is available, continue with [device selection](manage.md#list_devices).
 
 ## get_system_status
 A fast, non-throwing healthcheck that inspects key dependencies and connections required for mobile debugging.
@@ -11,7 +16,7 @@ Input:
 {}
 ```
 
-Response (example):
+Response (selected fields):
 
 ```json
 {
@@ -63,13 +68,15 @@ Behavior notes:
 - Always returns structured JSON and never throws; any failures are surfaced in the `issues` array.
 - `status` gives a quick overall gate: `ready`, `degraded`, or `blocked`.
 - `summary.android`, `summary.ios`, and `summary.gradle` provide the fastest path to the actual blocker category.
-- Designed to be fast (<~1s probes where possible); startup callers may prefer a `fastMode` variant that only checks existence.
+- The public tool accepts an empty input object; it exposes no `fastMode` option.
+- Probes are best-effort and can take longer when native tooling is slow.
 - Useful to call at the start of an agent session to gate subsequent actions.
 
 Usage guidance:
 - Call before build/install flows to avoid wasted build attempts on misconfigured systems.
 - Call early in a session when device or toolchain availability is uncertain.
-- If `success: false`, attempt recovery steps or report issues to the user.
+- `success: false` can reflect issues on a platform you are not using. Inspect the
+  relevant platform status and blockers before deciding whether to proceed.
 
 Recommended setup patterns:
 - Default: let the server discover tools automatically from standard locations and call `get_system_status` first to confirm what is available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-debug-mcp",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -17,29 +17,33 @@
     "test:integration": "npm run test:device",
     "test:device": "npm run build && tsx test/device/index.ts",
     "test": "npm run test:unit",
-    "lint": "eslint src test --quiet",
-    "lint:fix": "eslint src test --fix",
+    "lint": "eslint src test --quiet && npm run check:quality && npm run check:architecture",
+    "lint:fix": "eslint src test --fix && npm run check:quality && npm run check:architecture",
+    "package:antigravity": "node scripts/agent-plugin.mjs --export-antigravity",
     "sync:agent-plugin": "node scripts/agent-plugin.mjs --sync",
+    "check:quality": "node scripts/code-quality.mjs",
+    "check:architecture": "node scripts/check-architecture.mjs",
     "check:agent-plugin": "node scripts/agent-plugin.mjs --check",
     "verify": "npm run lint && npm run build && npm run test:unit && npm run check:agent-plugin"
   },
-
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "fast-xml-parser": "^5.5.1",
-    "zod": "^3.22.4",
-    "sharp": "^0.32.1"
+    "sharp": "^0.35.5",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@types/node": "^25.4.0",
     "@typescript-eslint/eslint-plugin": "^8.57.1",
     "@typescript-eslint/parser": "^8.57.1",
+    "archunit": "2.5.4",
     "eslint": "^9.39.4",
     "eslint-plugin-unused-imports": "^4.4.1",
-    "tsx": "^4.21.0",
+    "minimist": "^1.2.8",
+    "tsx": "^4.23.15",
     "typescript": "^5.9.3"
   }
 }