mobile-debug-mcp 0.33.0 → 0.35.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,28 +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).
+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:
@@ -83,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:
@@ -130,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"
@@ -149,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": {
@@ -211,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`:
 
-read_log_stream response example:
+```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.
+
+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
@@ -240,7 +275,8 @@ Both return `success`, resolved `device`, `readiness`, `elapsed_ms`, and a
 or settled; wait succeeds only for settled. Codes are `READINESS_UNAVAILABLE`,
 `READINESS_TIMEOUT`, and `DEVICE_UNAVAILABLE`. Invalid/unknown inputs are rejected.
 
-`readiness.state` is loading, transitioning, settled, or unknown. Visible native
+`readiness.state` is loading, transitioning, settled, unknown, or debugger_paused
+for an owned Android debugger stop. Visible native
 progress indicators establish loading; exact Loading / Please wait labels
 (ignoring case, whitespace and trailing dots/ellipsis) are heuristic loading.
 Loading takes priority over unchanged trees. Two different valid signatures show
@@ -252,12 +288,15 @@ keywords such as a button named Progress are not sufficient loading evidence.
 The summary includes `basis` (observed/heuristic/insufficient), `scope: device_ui`,
 latest successful capture time and snapshot session/revision, sample
 count, `stable_for_ms`, up to eight signal-code evidence records, limitations,
-and capability flags. Evidence excludes UI text and full trees. Unresponsive and
-debugger-paused detection are explicitly unsupported on both platforms; neither
-slow hierarchy retrieval nor a deadline expiry proves either state.
+and capability flags. Evidence excludes UI text and full trees. Managed Android
+[debugger pauses](debugger.md) are reported from session evidence without acquiring
+a UI tree; readiness waits fail with `DEBUGGER_PAUSED`. External-debugger and iOS
+pause detection remain unsupported. Unresponsive detection is unsupported; neither
+slow hierarchy retrieval nor a deadline expiry proves a pause or unresponsiveness.
 
 Tree responses (including compact and nested trees) add a single-sample readiness
-summary without extra reads. Such a summary reports loading or unknown; it does
+summary without extra reads. It reports an owned debugger pause when known;
+otherwise a single-sample summary reports loading or unknown; it does
 not inherit stability from an earlier request. Existing loading/delta fields and
 compact error evidence are preserved.
 

package/docs/tools/system-traces.md

@@ -0,0 +1,134 @@
+# Android system traces
+
+[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
+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,
+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.
+
+| 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_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. |
+
+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
+IDs. Repeated terminal operations return the stored outcome.
+
+## 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:
+older installed servers may not expose these tools. Capability failure is a
+reported limitation; it is not evidence that the app is frozen.
+
+Establish the initial UI state and include an outcome assertion in the journey.
+The launch-only example below demonstrates bracketing; it does not prove an app
+outcome. Use a fresh screenshot or semantic assertion appropriate to the actual
+screen. Settings, for example, may resume a subpage rather than show its main
+title. Allow enough capture time for complete observations as well as inputs.
+
+Always finalise an owned recording, including when a journey fails. Stop to keep
+diagnostic evidence; cancel to discard it. Check both `state` and `cleanup`, and
+use status/retry for an unresolved session before starting another capture.
+Do not rely on automatic duration expiry as routine cleanup.
+
+A useful report identifies the device, journey and assertion outcomes, trace ID,
+linked correlation IDs, coverage, artifact path and cleanup outcome. `covered`
+describes the capture session lifetime, not proof that every event survived the
+ring buffer. Capture success and valid trace contents are separate from a
+performance diagnosis. These tools do not return CPU summaries, frame metrics,
+blocked-thread analysis or a root cause. Inspect the artifact with an available
+analyser before making those claims; otherwise report analysis **unrun** and
+provide the local artifact for follow-up. Host/device clocks remain unaligned.
+
+## Bracket a journey
+
+1. `get_system_trace_capabilities({"platform":"android","deviceId":"emulator-5554"})`
+2. `start_system_trace({"platform":"android","deviceId":"emulator-5554","durationMs":30000})`
+3. Use the returned `trace_id` as `systemTraceId`:
+
+```json
+{
+  "platform": "android",
+  "deviceId": "emulator-5554",
+  "systemTraceId": "<trace_id>",
+  "steps": [
+    { "id": "launch", "type": "start_app", "appId": "com.android.settings", "verificationMode": "none" }
+  ]
+}
+```
+
+4. `stop_system_trace({"traceId":"<trace_id>"})` returns `artifact.path` for local
+   inspection in Perfetto. Delete the file/directory when finished.
+
+An invalid, inactive, foreign-server or different-device reference prevents all
+journey steps. A failed journey leaves the capture available to stop or cancel;
+journeys do not control its lifetime. Without `systemTraceId`, journey behaviour
+and evidence remain unchanged. Linked journey/step evidence has
+`trace_context: {"supported":true,"trace_id":"…","markers":[]}`. The journey
+returns `system_trace` with `trace_id`, `coverage` (`covered` or `partial` if
+capture ended during execution), and `clock_alignment:"unknown"`. Trace results
+list linked `correlation_ids`. These are associations, not injected markers or
+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),
+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` contains absolute `path`, `format:"perfetto"` and `size_bytes`.
+`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
+`INVALID_ARGUMENT`, `UNSUPPORTED_PLATFORM`, `TRACE_UNSUPPORTED`, `TRACE_BUSY`,
+`TRACE_NOT_FOUND`, `TRACE_START_FAILED`, `TRACE_STOP_FAILED`,
+`TRACE_ARTIFACT_FAILED`, `ACTION_TIMEOUT`, and `TRACE_CANCELLED`.
+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
+
+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
+reported; missing sched/input rejects start. No arbitrary config, wildcard app
+annotations, heap, screenshot or logcat sources are enabled. Device/system
+annotations may still contain sensitive information; this is not app-private data.
+
+Capture has a device-side duration limit and a server finalisation timer. Start
+acknowledgement has a 35-second budget, graceful stop 10 seconds, and transfer
+30 seconds. Only the recorded PID/start-time/output-path owner can be signalled;
+no kill-by-name cleanup. A device disconnect or uncertain stop reports failure,
+never a successful artifact. Partial transfers are discarded; bounded device
+output remains retryable. Successful transfers remove owned device files.
+
+Host artifacts use unique restricted temporary directories and remain for
+user-managed deletion. Nothing is uploaded or returned as base64. Normal server
+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.
+
+## 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.
+- [Android 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.33.0",
+  "version": "0.35.0",
   "description": "MCP server for mobile app debugging (Android + iOS), with focus on security and reliability",
   "type": "module",
   "bin": {
@@ -17,29 +17,32 @@
     "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",
     "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"
   }
 }